# GitHub

Connect a GitHub repository to use its files as a versioned recipe source, and declare which repositories a runtime's tasks may work in.

Connecting GitHub makes selected repositories available to Introspection. A
[recipe](/recipes) 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.

This page is also the canonical reference for the **`runtime.github`** grant:
[Workspace repositories](#workspace-repositories) below is where the grant
semantics, the permission ceiling, and the live-update caveat are specified.

## Typical workflow

1. Connect GitHub and grant Introspection access to the recipe repository.
2. Register a recipe from a ref or directory in that repository.
3. Develop a change on a branch and open a pull request.
4. Verify the candidate runtime version created from the pull-request commit.
5. Merge the change so the default-branch commit becomes available as a
   production runtime version.

See [Agent development lifecycle](/guides/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:

1. Select **Connect** on the GitHub integration.
2. Install the **Introspection GitHub App** on the GitHub account or
   organization that owns the repository.
3. Select the repositories Introspection may access.

Organization owners connect the GitHub App once from the Integrations page.

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](/guides/work-with-repositories) covers the full path from
installation to a cloned checkout.

## 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.

## Workspace repositories

An agent [task](/platform/tasks-and-runs) can prepare repository changes in its
sandbox and, when granted, push a branch or open a pull request through the
same GitHub App installation. The grant is declared in the
[runtime manifest](/platform/runtime-manifest), in the `runtime.github` block:

```yaml
runtime:
  github:
    repositories:
      - acme/api-service
      - acme/web
    permissions:
      contents: write
      pull_requests: write
```

### The grant, not a clone list

`repositories` is a **grant, not a clone list**: each entry is an `owner/name`
slug for a repository already registered to the project (never a URL), and
naming a repository clones nothing by itself. There is no limit on how many may
be granted — a grant costs nothing until a task uses it. Two granted
repositories cannot share a name, because the checkout always lands at
`workspace/repos/<repository name>`.

A task then picks the subset it actually wants, with its ref and depth:
`introspection tasks create --repository OWNER/NAME[@REF][:DEPTH]` (repeatable),
or `repositories: [{ repo, ref, depth }]` on `TaskCreateParams`. That list has
no server-side count limit either, but unlike the grant it is cloned at boot
before the first turn, so its length is startup latency. An entry outside the
grant is dropped by the server rather than failing the launch.

### The permission ceiling

`permissions` mirrors the GitHub Actions `permissions:` block and is the
**ceiling, not the request**. Every supported read is implicit, so authors
declare only write elevations, such as `contents: write` and
`pull_requests: write` for a branch-and-PR workflow. The allow-list is
`contents`, `pull_requests`, `issues`, `checks`, `statuses`, `deployments`, and
`discussions`; keys accept both the underscored and the GitHub Actions
hyphenated spellings (`pull_requests` and `pull-requests` are the same key).
Keys outside the allow-list — `workflows`, `administration`, `actions`,
`packages`, `pages`, `security_events`, `repository_projects` — are refused by
name.

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. The grant decides the ceiling, not which repository holds the
recipe — a recipe may grant its own repository, the
[self-improving agent](/platform/security#self-improving-agents) pattern, which
carries its own governance decisions.

### When a grant change takes effect

The grant is part of the runtime version, so editing `runtime.github` in the
manifest changes nothing until a new version is deployed from that commit, and
a running task keeps the repositories it cloned at launch.

An explicit `PATCH /v1/runtimes/{id}` on `config_json` is the one path that
does change a **live** runtime's grant, and it applies from that runtime's
next token mint. `config_json` is **replaced wholesale, not merged** — it is
the same object that holds `resources` and the manifest's `runtime.config`
keys — so send the runtime's current `config_json` with `github` edited into
it, or the rest is silently dropped until the next manifest deploy rewrites
the row.

[Work with repositories](/guides/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 from
the dashboard also uninstalls the GitHub App.

**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.

## Related

- [Recipes](/recipes): how a repository and commit become your agent's pinned behavior.
- [Runtime manifest](/platform/runtime-manifest): where the `runtime.github` block lives.
- [Security](/platform/security#self-improving-agents): governing an agent granted write access to its own recipe.
- [Tasks](/platform/tasks-and-runs): the executions that prepare changes; publishing them requires the grant described above.
- [Work with repositories](/guides/work-with-repositories): the end-to-end procedure and review boundary.

GitHub

Connect a GitHub repository to use its files as a versioned recipe source, and declare which repositories a runtime’s tasks may work in.

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.

This page is also the canonical reference for the runtime.github grant: Workspace repositories below is where the grant semantics, the permission ceiling, and the live-update caveat are specified.

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.

Organization integrations page with a GitHub connection card and Connect action — Organization owners connect the GitHub App once from the Integrations page.

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.

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.

Workspace repositories

An agent task can prepare repository changes in its sandbox and, when granted, push a branch or open a pull request through the same GitHub App installation. The grant is declared in the runtime manifest, in the runtime.github block:


runtime:
  github:
    repositories:
      - acme/api-service
      - acme/web
    permissions:
      contents: write
      pull_requests: write

The grant, not a clone list

repositories is a grant, not a clone list: each entry is an owner/name slug for a repository already registered to the project (never a URL), and naming a repository clones nothing by itself. There is no limit on how many may be granted — a grant costs nothing until a task uses it. Two granted repositories cannot share a name, because the checkout always lands at workspace/repos/<repository name>.

A task then picks the subset it actually wants, with its ref and depth: introspection tasks create --repository OWNER/NAME[@REF][:DEPTH] (repeatable), or repositories: [{ repo, ref, depth }] on TaskCreateParams. That list has no server-side count limit either, but unlike the grant it is cloned at boot before the first turn, so its length is startup latency. An entry outside the grant is dropped by the server rather than failing the launch.

The permission ceiling

permissions mirrors the GitHub Actions permissions: block and is the ceiling, not the request. Every supported read is implicit, so authors declare only write elevations, such as contents: write and pull_requests: write for a branch-and-PR workflow. The allow-list is contents, pull_requests, issues, checks, statuses, deployments, and discussions; keys accept both the underscored and the GitHub Actions hyphenated spellings (pull_requests and pull-requests are the same key). Keys outside the allow-list — workflows, administration, actions, packages, pages, security_events, repository_projects — are refused by name.

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. The grant decides the ceiling, not which repository holds the recipe — a recipe may grant its own repository, the self-improving agent pattern, which carries its own governance decisions.

When a grant change takes effect

The grant is part of the runtime version, so editing runtime.github in the manifest changes nothing until a new version is deployed from that commit, and a running task keeps the repositories it cloned at launch.

An explicit PATCH /v1/runtimes/{id} on config_json is the one path that does change a live runtime’s grant, and it applies from that runtime’s next token mint. config_json is replaced wholesale, not merged — it is the same object that holds resources and the manifest’s runtime.config keys — so send the runtime’s current config_json with github edited into it, or the rest is silently dropped until the next manifest deploy rewrites the row.

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 from the dashboard also uninstalls the GitHub App.

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.

Recipes: how a repository and commit become your agent’s pinned behavior.
Runtime manifest: where the runtime.github block lives.
Security: governing an agent granted write access to its own recipe.
Tasks: the executions that prepare changes; publishing them requires the grant described above.
Work with repositories: the end-to-end procedure and review boundary.