> ## Documentation Index
> Fetch the complete documentation index at: https://www.cloudtag.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure GitHub access

> Connect the agent's own GitHub account by signing in, or paste a token, and clone repositories into its sandbox for one group, a bundle or the whole organization.

The agent can work in your GitHub repositories: read code to answer questions, and, if you allow it, push changes. Each repository you add is cloned into the agent's sandbox at the start of every conversation, under `/workspace/`.

## Connect the agent's GitHub account

Give the agent its own GitHub account the way it has its own mailbox, then sign in as it once. Owners and Admins do this on the organization's page:

1. Create a GitHub account for the agent, e.g. `acme-cloud-bot`, and invite it to the repositories it should use. **Accept each invitation while signed in as that account.**
2. Under **Agents**, open the agent and click **Connect GitHub**.
3. GitHub asks which account to use. Pick the agent's account, not your own, and authorize Cloud Tag.

The agent's card then shows **GitHub: acme-cloud-bot**. Cloud Tag keeps the token encrypted. The agent reads and pushes as that account, with whatever access you give it on GitHub, and nothing more. Use your own account only if you want the agent to act as you.

**Connect again** signs in afresh, e.g. as a different account; Cloud Tag revokes the old token. Repositories added with the agent's account then clone as the new one, so it needs access to them too. **Disconnect GitHub** revokes the token too. Repositories added with that account stop being cloned until it connects again.

If GitHub stops accepting the sign-in, for example because someone revoked it in the account's GitHub settings, the card shows **connect again**.

This needs the Cloud Tag operator to have set up a GitHub OAuth App (see DEPLOY.md). Without one, the **Connect GitHub** link doesn't appear. Add repositories with a token instead.

### Repositories in a GitHub organization

Many GitHub organizations restrict which OAuth apps can use their repositories. In one that does, the agent's account can be a member and still be refused until an owner of that GitHub organization approves Cloud Tag:

- The agent's account requests approval at **GitHub → Settings → Applications → Authorized OAuth Apps → Cloud Tag**. When adding a repository fails for this reason, Cloud Tag shows the link.
- An outside collaborator can't always request approval. If the request button is missing, ask an owner of the GitHub organization to approve Cloud Tag in its **Third-party access** settings.
- The restriction covers the organization's public repositories too.

Repositories on a personal GitHub account need no approval.

## Add a repository

Repositories can be added for one group (its **Connectors** page), a [bundle](https://www.cloudtag.tech/docs/admins/attach-to-scope.md), or every group in the organization (the organization's **Connectors** tab).

1. Under **GitHub repositories**, enter the repository URL, e.g. `https://github.com/acme/handbook`. Owners and Admins get suggestions from the repositories the agents' accounts can reach.
2. Optionally, enter a branch.
3. Under **Clone with**, pick an agent's GitHub account, or **A token I paste**.
4. Click **Add or replace**. Cloud Tag checks with GitHub that the account or token can read the repository before saving it.

Only the organization's Owners and Admins can add repositories with an agent's account, because the account belongs to the whole organization. A group's admins can add repositories to their group with a token of their own.

Add the same repository again to replace its account, token or branch; **Remove** takes it out. For the same repository at several levels, the narrowest wins: the group's own, then a bundle's, then the organization's. A repository whose agent's account is disconnected is skipped, so a wider level's entry for it takes over.

### With a token instead

If you'd rather not connect an account, create a **fine-grained personal access token** in GitHub for the repository, ideally on a dedicated GitHub account for the agent:
- **Contents: read** for the agent to read the code;
- **Contents: write** only if it should push.

Choose **A token I paste** and paste it.

## What it can do with it

```text
@cloud in the handbook repo, where do we document the on-call rotation? Quote the section.
```

The agent can push to a repository when its account or token has write access to it. Changes under `.github/workflows` also need the token's `workflow` permission, which a connected account doesn't have.

Pull requests, issues and other GitHub actions beyond the clone need GitHub's MCP server as a connector. On a **Connectors** page, add `https://api.githubcopilot.com/mcp/` and sign in with GitHub. Sign in as the agent's account if its pull requests and comments should come from it rather than from you. The connector asks for `repo` and `read:org`. Like the agent sign-in, this needs the operator's GitHub OAuth App. Without it, paste a GitHub token as the connector's **API token** instead.

## Differences from Claude Tag

Claude Tag gives the agent its own identity through the Claude GitHub App, installed on each GitHub organization. Cloud Tag has the agent sign in as a GitHub account instead, so nothing is installed. The agent acts as that account. There's no GitLab support yet.