Repositories

A repository grant is one GitHub repository, or one whole App installation, that a single Agent may read and change. Where a connection grants an external account and a skill teaches a procedure, a repository grant hands an Agent short-lived GitHub credentials scoped to named repositories. This page covers installing the Chickpea GitHub App, granting repositories to an Agent, what the Agent may then reach, the environment-variable alternative, and removing the app.

Prerequisites

• The Owner or Admin role in Chickpea. Every GitHub view in Admin, including an Agent’s Repositories tab, needs the admin.configure permission, which Members do not have.
• Permission on GitHub to create an App. Under your personal account, or under the organization you name.
• One Agent to grant to. Repository grants stop at the Agent, like connections, memory, and skills.

There is no personal access token lane. The GitHub App is the only mechanism.

Install the Chickpea GitHub App

Grant repositories to an Agent

Verify

In a channel the Agent is published to, ask it for something only GitHub can answer:

@oncall which pull requests are open on acme/api?

The Agent answers in the thread with pull requests from that repository. A grant that has not been saved, or a repository the installation cannot reach, produces no GitHub access at all rather than a partial answer.

What the Agent gets

Chickpea mints a GitHub installation token for each turn that needs one. GitHub scopes the token to the granted repository names, and Chickpea caps its permissions at contents write, pull requests write, issues write, metadata read, and actions write. Tokens are held in memory until five minutes before they expire, never join the model’s context or a channel’s frozen snapshot, and are injected at egress.

The token is usable only against these routes.

Four rules bound what those routes allow.

• DELETE is never allowed. It is not in the method list, so no endpoint reached this way can delete a repository, branch, release, issue, comment, or file.
• Workflow and deployment controls are denied inside granted repositories. Repository dispatches, workflow dispatches, enabling or disabling a workflow, and approving a run, a pending deployment, or a deployment protection rule are all refused.
• GitHub hosts are reserved for this integration. Chickpea strips github.com and api.github.com from every Agent’s generic API connections, so a pasted bearer credential cannot create an unscoped GitHub route.
• The Agent is told its exact list. Chickpea gives it the granted repository names, the allowed hosts and methods, and the instruction never to probe other repositories or add authentication headers of its own.

Grants are policy, not credentials. In a channel thread whose Agent snapshot is frozen, the frozen grants remain authoritative for what may be added and the live Agent remains authoritative for revocations, so removing a grant takes effect on the next turn.

What works without the coding sandbox

Repository-aware model work runs on the default Cloudflare deploy, which ships no container. Reading files at a branch, tag, or commit, searching code inside a granted repository, listing and reading pull requests, reading and writing issues and comments, and reading Actions runs all go over the REST API and need nothing extra.

Install the coding sandbox when an Agent needs a real checkout, package installation, tests, or a dev server. Chickpea selects the container tier for a turn only when the target is Cloudflare, the tier is installed and enabled, the GitHub App is connected, and the Agent holds at least one valid enabled repository grant. Otherwise the turn runs on the standard sandbox.

On Node

Repository grants work the same way on Node: the same App credentials, the same installation tokens, the same allowlist. The coding sandbox is never available on Node, which always uses the standard in-memory sandbox.

Deployment-owned App credentials

An operator can supply the App themselves instead of creating one through Admin. Set both GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY in the deployment’s environment. Either variable alone leaves GitHub unconnected.

Without a stored slug, Admin cannot open the GitHub install page for you; install the app from GitHub instead. Neither variable appears in .env.example or .dev.vars.example.

From Slack

Ask @Chickpea for repository access and it hands back a Chickpea link rather than doing it in the channel, because credentials never pass through a Slack message. Opening the link binds the proposed repository to its installation and enables the grant, which anyone who may edit that Agent can finish. When the GitHub App is not connected yet, the link starts app creation instead, and only an Owner or Admin can complete that.

Remove the app

Next steps

• Agents: the rest of what an Agent is made of, including connections, skills, and the coding sandbox.
• Security model: how credentials and authority are handled on every turn.
• How Chickpea works: where repository access sits in the life of one mention.