GitHub
Connecting GitHub makes selected repositories available to Introspection. A recipe can then point to a repository, ref, and optional sub-path. Introspection resolves that source to an exact commit so each Runtime version has reproducible behavior.
Repository changes also participate in the Runtime lifecycle. Pull-request commits can produce candidate Runtime versions, while commits on the default branch can produce production Runtime versions. The Runtime and environment configuration determines which version receives traffic.
Typical workflow
- Connect GitHub and grant Introspection access to the recipe repository.
- Register a recipe from a ref or directory in that repository.
- Develop a change on a branch and open a pull request.
- Verify the candidate Runtime version created from the pull-request commit.
- Merge the change so the default-branch commit becomes available as a production Runtime version.
See Agent development lifecycle for the full local, development, staging, and production sequence.
Connect a repository
An organization admin or owner connects GitHub from the organization integrations page:
- Select Connect on the GitHub integration.
- Install the Introspection GitHub App on the GitHub account or organization that owns the repository.
- Select the repositories Introspection may access.
The connection belongs to the Introspection organization, with one active GitHub connection per organization. It uses the GitHub App installation rather than a personal OAuth token, and Introspection stores its credential encrypted.
Installing the App decides what Introspection can reach; it does not by
itself make any repository usable. A project registers the ones it works with,
from Project settings → Repositories or with introspection repositories add. Creating a recipe from a GitHub selector — which introspection runtimes create and the dashboard’s new-runtime flow both do — registers the repository it pins
automatically, so most projects only register the additional repositories
their agents work on. Work with
repositories covers the full path from
installation to a cloned checkout.
Access and permissions
Reading recipe source
When a task needs recipe source, the platform mints a short-lived installation
token from the GitHub App and uses it to clone the repository into the run’s
sandbox. The token is down-scoped to contents:read for the one repository the
runtime’s pinned recipe resolves to. It is minted per use, never long-stored,
and is not general GitHub API or repository write access.
Publishing changes
An agent task can prepare repository changes in its
sandbox. Pushing a branch or opening a pull request is granted through the same
GitHub App installation, by declaring
workspace repositories in the
runtime manifest’s runtime.github block. repositories names which registered
repositories the runtime’s tasks may check out, and permissions raises the
ceiling on what its minted token may do — mirroring the GitHub Actions
permissions: block over a closed allow-list (contents, pull_requests,
issues, checks, statuses, deployments, discussions). Reads are
implicit, so an author only declares write elevations, such as
contents: write and pull_requests: write for a branch-and-PR workflow.
The manifest is the grant only — nothing is cloned because a recipe named
it. A task requests the subset it actually wants via repositories on
POST /v1/tasks (--repository on the CLI), and an entry outside the grant is
dropped. Because the grant rides the runtime version, editing runtime.github in
the manifest takes effect only once a new runtime version is deployed from that
commit — with the exception of a direct PATCH /v1/runtimes/{id}, which rewrites
the live row and applies from the next token mint (it replaces config_json
wholesale; see Runtimes).
The token minted to clone recipe source is separate and stays read-only. A
runtime that declares no runtime.github block gets no repository write
capability.
Work with repositories covers the full path: registering a repository to the project, declaring the grant and its permission ceiling, requesting the clone from a task, and shipping the agent’s change through review.
How repository changes stay in sync
GitHub sends verified lifecycle events directly to the Introspection control plane. The platform uses them to keep connected resources in sync:
- Installation events update or remove the organization’s GitHub connection when the App is suspended, restored, or uninstalled.
- Pull request events create and update preview runtime versions, release staging from a closed preview when appropriate, and update Introspection issues linked to that pull request.
- Pushes to the repository’s default branch create production runtime versions for registered recipes.
Because lifecycle events flow back from GitHub, the connection stays in sync whether you manage it from Introspection or from GitHub. Disconnecting in the app also uninstalls the App on GitHub.
Renaming a repository on GitHub is not synced. A registration stores the
owner/name it was created with, and nothing updates it — repository rename
and transfer events are not handled. After a rename, pushes no longer match the
registration and stop creating production runtime versions, with no error
raised. Register the new name and re-point the grant. A repository a recipe
is pinned in cannot be re-pointed — the pin is immutable and unregistering is
refused while a recipe holds it — so that case needs a new recipe, and a new
runtime, against the new registration.
Disconnect or reconnect
Removing the connection in Introspection uninstalls the GitHub App and revokes Introspection’s repository access. If GitHub reports that an installation has expired or been revoked, the integration is marked for an admin to reconnect.