# GitHub repositories

Connect GitHub to a workspace, set which repositories agents may use, and declare repository access in a manifest.

Agents work on GitHub with `git` and `gh`, using a token the platform issues for each run. Three
things decide what a run gets:

1. **The connection.** A workspace admin connects a GitHub organisation or account by installing
   the platform's GitHub App on it.
2. **The ceiling.** The workspace admin says which repositories agents may be given, and the most
   they may do there.
3. **The manifest.** The agent names the repositories it needs under `access.github`.

A run gets exactly the repositories its manifest names, limited by the ceiling and by what the
installation can see. Nothing is granted per person or per agent outside the manifest.

## Connect GitHub

In the Console, open **Settings → Organization → GitHub** and choose **Connect GitHub**. GitHub asks you to pick
the organisation or account and the repositories the App may see, then asks you to sign in once.
The sign-in confirms you own that account (an organisation owner, or the user it belongs to); the
platform keeps no copy of your GitHub token.

From the CLI, `tanomis github connect` prints the same link.

The first connection allows agents to **read** every repository the installation can see. Adding
or removing repositories on GitHub updates the connection automatically.

## Set the ceiling

The ceiling lists repositories, or `owner/*` patterns, with the most any agent may be given. A
specific repository overrides its owner's pattern.

```bash
tanomis github ceiling set 'anyfind/*' --can read
tanomis github ceiling set anyfind/agent-platform-website-tanomis --can read,push,pull_request
tanomis github status
```

## Declare access in the agent

```yaml title="agent.yaml"
access:
  github:
    repos:
      anyfind/agent-platform-website-tanomis:
        can: [read, push, pull_request]
```

Deploy as usual. A declaration the workspace cannot honour is refused with the reason, for example:

```text
access.github: cannot be used in workspace acme: Asks for push and pull_request on
anyfind/agent-platform-website-tanomis; this workspace allows read (anyfind/*). Raise the
ceiling in Settings → Organization → GitHub, or narrow the manifest.
```

`tanomis agent access NAME` shows what an agent may reach in the current workspace, using the same
status the Console shows. See the [manifest reference](/reference/agent-manifest#github-repositories)
for capabilities and slots for global agents.

## What a run sees

Inside the sandbox, `git` and `gh` authenticate automatically for the declared repositories only.
With more than one repository, `gh` outside a clone needs `-R owner/name`. Every `git` or `gh`
operation asks for a fresh token, so lowering the ceiling or disconnecting GitHub stops the next
operation. Tokens expire within an hour and are revoked when the run ends.