Connect repositories

A project’s Repositories tab is the code its agents build. Attaching one is what lets a task be bound to a repository, which is what gives a run something to check out and work in.

What you’ll need

• The Manage integrations permission, to install the GitHub App for the workspace.
• Admin rights on the GitHub organization or account that owns the repository, because installing an app is an account-level grant.

Install the GitHub App

The app is installed once for the whole workspace, not per project.

1. Settings, then GitHub. With nothing installed the page reads No GitHub App Installed.

2. Install GitHub App sends you to GitHub’s own installation screen, at github.com/apps/<the app>/installations/new.

3. On GitHub, pick the account or organization to install into, then choose All repositories or Only select repositories and pick them.

4. Install returns you to CommandChain, which records the installation and shows the account, the installation id, whether access is all or selected repositories, and the permissions granted.

Selected-repository access is the safer default. Widening it later is a change on GitHub’s side, from the same installation screen.

What the grant screen asks for

Three permissions, and no webhook events:

Permission	Access	What it is for
Metadata	Read	Listing the repositories the installation can see
Contents	Write	Reading the code, and pushing the branch a task’s work lands on
Pull requests	Write	Opening the pull request that promotes a reviewed changeset

Contents write is the one worth pausing on: it is what lets work be pushed at all. It is scoped to the repositories you selected, and it is used by the runner and the platform rather than by an agent (see below).

Attach a repository to a project

1. Open the project, then Repositories.

2. Add Repository searches the repositories the installation can see. Nothing outside the installation is searchable, which is the grant doing its job.

3. Pick one, add a note saying what it is for, and add it.

4. Optionally tick extract intents to have an agent read the code and propose requirements and scope items for Project Data. You review every candidate before any of it lands.

Each row shows the repository, its note (select the note to edit it), its index status, and the intent-extraction control: Extract intents first time, Analyzing while an agent is reading it, Review N intents when there are candidates waiting, and Re-extract afterwards. Remove detaches it from the project and touches nothing on GitHub.

Without the GitHub App

The tab reports No GitHub App installed and offers Set Up GitHub to anyone who can manage integrations. A project can also point at a plain git remote by storing GIT_REMOTE_URL in the project’s environment, which needs no forge and no token. Pull requests need GitHub.

What agents may do with your code

The split is worth being precise about, because it is a security property rather than an implementation detail.

Who	What it may do
The agent	Read and write files inside its sandboxed working tree, on the task’s own branch
The runner	Clone, fetch, commit, and push, using the git access the machine already has
The platform	Open and merge pull requests through the GitHub App installation

The agent never pushes. It is sandboxed and cannot reach your git credentials, so when it finishes, the runner makes the commit and the push, authored as the runner rather than as a person. An agent that wanted to exfiltrate your keys could not read them, and one that wanted to force-push could not reach the remote.

Work also lands on a branch of its own, named for the task, never on your default branch. See workspaces and git for what the runner does around the agent, and the security model for the boundary as a whole.

Next steps

• Set environment variables and secrets: what a run gets besides the code.
• Ship code from a meeting: repositories, branches, merge, and release.
• Workspaces and git: the checkout on your machine.