Configure GitHub access

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, 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

@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.