Connect GitHub

GitHub runs a hosted MCP server, so a harness agent can read code, search a repository, look at commits and pull requests, and — if you allow it — create branches, commit files and open pull requests. GitHub does not let XPT Tracker register itself, so the connector signs in with a fine-grained personal access token that you create in GitHub.

Before you start

You need Why
Workspace admin role in XPT Tracker Only admins add and connect connectors
A GitHub account with access to the repositories agents should work with The connector acts as this account
On an organization that requires approval for fine-grained tokens: an organization owner who approves the token GitHub does not accept the token until it is approved

Choose the account deliberately. A connector is shared: every agent you give it to acts in GitHub as the owner of the token. Branches, commits and pull requests appear under that account's name, not the agent's. A dedicated GitHub account for agents (for example acme-agents), added only to the repositories agents should work in, keeps that clear and keeps a person's own access out of it.

Step 1: create the token in GitHub

  1. In GitHub, open Settings → Developer settings → Personal access tokens → Fine-grained tokens and press Generate new token.

  2. Resource owner: the organization that owns the repositories (or your own account).

  3. Repository access: Only select repositories, and pick only the repositories agents need. The agent sees nothing else.

  4. Permissions — choose the level for the work agents will do:

    Agents should Repository permissions
    Read code, commits and pull requests Contents: Read, Pull requests: Read
    Also create branches, commit files and open pull requests Contents: Read and write, Pull requests: Read and write
    Also read and write issues add Issues: Read or Read and write

    Metadata: Read is added automatically.

  5. Set an expiration date, generate the token and copy it. GitHub shows it only once.

Step 2: add the connector in XPT Tracker

  1. Open Workspace settings → MCP → Connectors and press Add connector.

  2. Fill in the form:

    Field Value
    Name GitHub
    Key github (the key cannot be changed later)
    Server URL https://api.githubcopilot.com/mcp/
    Authentication Bearer token
    Token the token from step 1

  3. Press Add connector. The connector is ready at once and shows Connected.

Give it to agents

Open AI Studio → Agents, select a harness agent, and add GitHub in its Connectors section. The change applies from the agent's next turn.

Ask in plain language, for example "@dev read the README of acme/web and find where the sign-up form is validated" or "@dev fix the typo on the pricing page in acme/web on a new branch and open a draft pull request".

What agents can and cannot do

What the agent can do depends on the token's permissions. With read and write access:

Area Agents can
Files Read a file or list a folder; create, update or delete a file; commit several files at once
Branches and commits Create a branch; list branches, commits and tags; read a commit
Pull requests Open a pull request (also as a draft); read its diff, files, reviews and check results; update it; review and comment; merge it
Issues Read, create and update issues and comments; manage sub-issues
Search Search code, commits, issues, pull requests, repositories and users
Releases and teams Read releases and tags, teams and their members

What the connector does not do:

Not possible Why, and what to do
Clone a private repository into the agent's working directory, build it or run its tests The connector gives the agent GitHub's API, not git. The token stays in XPT Tracker and never enters the agent's sandbox, so git clone of a private repository has nothing to sign in with. A public repository the agent can still clone with git like anyone else
Run or rerun GitHub Actions The server offers no Actions tools; check results of a pull request can be read
Keep the agent to its own branches A token with Contents: Read and write can write to any branch the account may write to, including the default branch, and can merge pull requests. Protect the default branch (below)

Protect the default branch

Before giving agents write access, protect the default branch so that nothing reaches it without a person:

  1. In the repository, open Settings → Rules → Rulesets (or Settings → Branches → Branch protection rules) and add a rule for the default branch, for example main.
  2. Turn on Require a pull request before merging, with at least one required approval.
  3. Turn on Block force pushes, and leave the agents' account out of any bypass list.

With that rule, an agent can push to its own branches and open pull requests, but a person reviews and merges. Asking agents to work on branches with a recognisable prefix (for example agent/…) makes their work easy to find.

Change or rotate the token

To give the connector a new token — when the old one expires, or to change its permissions — create the new token in GitHub and use Replace token in the connector's ⋯ menu. The new token applies from the agent's next turn.

When something goes wrong

What you see What to do
The connector shows Needs reconnect GitHub refused the token: it expired, was revoked, or is waiting for the organization's approval. Create or approve a token and use Replace token
The agent cannot find a repository The repository is not among the token's selected repositories. Edit the token in GitHub and add it
The agent can read but not write The token has read-only permissions. Give it Read and write for Contents and Pull requests in GitHub
A push to the default branch is refused Branch protection is working as intended. Ask the agent to use a branch and open a pull request