GitHub App sandbox access

Use defineGitHubAppConnection() when an agent needs authenticated git and gh commands inside its sandbox. The connection exposes no model-facing connection tools. At root-sandbox acquisition the host verifies the configured installation, mints a one-hour installation token, and configures both a Git credential helper and the GitHub CLI without placing the App private key in the sandbox.

GitHub is the authority boundary. Assembly Line does not choose or narrow the installation's permissions or repository access. The token inherits the permissions and the all-repositories or selected-repositories choice configured on the GitHub App installation. Use a separate App when two agent deployments need different authority.

Choose an installation owner

The connection supports two installation modes:

Deployment-owned mode is the usual choice for an autonomous coding or review agent. User mode is appropriate for a multi-user agent host where GitHub access must follow the active user.

1. Create the GitHub App

Create the App under the personal account or organization that should own it. Choose the repository permissions for the actual agent role. For example:

• A coding agent that pushes branches and opens pull requests normally needs Contents: Read and write and Pull requests: Read and write.
• A read-only reviewer that publishes a check normally needs Contents: Read, Pull requests: Read, and Checks: Read and write.
• Add other permissions only for behavior the agent actually needs. For example, editing workflow files or dispatching workflows needs additional GitHub permissions.

Assembly Line accepts any GitHub App permission set. Changing the permissions in GitHub changes the authority of subsequently minted tokens; the framework does not maintain a second permission policy.

For environment mode, disable webhooks unless another part of the deployment uses them. A callback URL, setup URL, and user authorization are not needed. For user mode, enable user authorization during installation and set the callback URL to:

https://<agent-host>/assembly-line/connections/callback

If the deployment consumes GitHub installation webhooks, set the webhook URL to the following and configure GITHUB_APP_WEBHOOK_SECRET:

https://<agent-host>/assembly-line/connections/github-app/webhook

2. Install the App on the GitHub organization

Open the App's Install App page and install it on the organization. Choose All repositories or Only select repositories according to the desired agent boundary. Organization owners can install the App directly; other members may need to request owner approval.

Record these values:

• App ID from the App's General settings page.
• Installation ID from the numeric id in the installed App's URL or from the GitHub App installations API.
• A newly generated private key in PEM format.

Keep the private key only in the runtime host's secret manager. GitHub stores only the public half of a generated key, so retain the downloaded PEM securely and rotate it deliberately.

3. Select the plugin

Install the package, then select and lock its plugin without reinstalling:

pnpm add @assemblyline-agents/github
assembly-line add github /path/to/agent --no-install

No connection file is generated.

For a deployment-owned installation, select the shared GitHub plugin and put the GitHub App exception under its contribution:

# agent.md
model: openrouter/openai/gpt-5.4
sandbox: e2b
capabilities:
  github:
    connections:
      github-app:
        installation: environment

Store these host secrets:

GITHUB_APP_ID
GITHUB_APP_PRIVATE_KEY
GITHUB_APP_INSTALLATION_ID

installationIdEnv can name a different uppercase environment variable when a host runs more than one App connection. GITHUB_API_URL is an optional API endpoint override.

For per-user installation instead, omit the installation exception and configure:

GITHUB_APP_ID
GITHUB_APP_PRIVATE_KEY
GITHUB_APP_SLUG
GITHUB_APP_CLIENT_ID
GITHUB_APP_CLIENT_SECRET

Start authorization with the same user identity that will start runs:

curl -H "Authorization: Bearer $ASSEMBLY_LINE_ADMIN_TOKEN" \
  "https://<agent-host>/assembly-line/connections/authorize?connection=github-app&channel=http&userId=user_123"

Open the returned URL and install or authorize the App. Assembly Line verifies that the user can access the installation, discards the transient GitHub user token, and stores only the installation marker in the user-scoped grant.

Runtime behavior

The connection materializes credentials only for a root run that explicitly requests a lease through authenticated sandboxCredentials input. Merely configuring GitHub on an agent does not resolve or project it into unrelated sandboxes. For an authorized lease, the connection:

• live-verifies the App id, installation id, suspension state, account, and repository-selection mode;
• requests an unmodified installation token from GitHub;
• configures HTTPS Git authentication for github.com;
• configures gh through a sandbox-local hosts.yml; and
• records the App account, repository selection, returned permission map, verification time, and expiry in a redacted issuance audit.

Subagent sandboxes do not inherit root-agent connection credentials. Tokens and credential files are excluded from durable workspace manifests and expire after one hour. Revoked, suspended, mismatched, expired, or unauthorized installations issue no credential. An unavailable requested lease fails closed instead of starting without the requested GitHub access. Unrelated file and shell work does not touch GitHub credentials at all.

The private key, installation token, Git credential contents, and gh credential contents never enter prompts, run events, or durable grants. Agents with unrestricted shell access can use the materialized installation token through Git and gh, so the GitHub App settings are the effective external write boundary.