What permissions does a personal token need for a GitHub source, and why might pull requests be missing?

Tares needs a fine-grained token with Metadata read, Contents read and Pull requests read for a GitHub source, or a classic token with the repo scope for private repositories. Without Pull requests read, commits still arrive but pull requests do not, and the daemon log says why once. Add write on Contents and Pull requests only if agents should change repositories with the token.

How it works

A GitHub source with a personal token polls one repository every 2 minutes by default. Each poll reads the repository’s commits and its pull requests, opened, merged or closed. Tares resolves the credential you picked in Settings > GitHub at every poll, so the token’s permissions decide what comes back.

The permissions map to the data like this:

• Metadata read. GitHub requires it for any repository access.
• Contents read. Lets Tares read the repository’s commits and the changed files it adds to each commit.
• Pull requests read. Lets Tares read pull requests. Without it the pull request half of the poll fails.
• Contents and Pull requests write. Needed only if agents should change repositories with this token, for example to write files on a branch or open pull requests. Reading needs no write access.

A classic token works too. It needs the repo scope to read private repositories.

If the token cannot read pull requests, commits keep arriving and the daemon log says why once. The log line appears one time, so check the daemon log from when the source was first polled. If you see commits as commit events but no pull_request events, the missing Pull requests read permission is the first thing to check.

Set it up

1. Create a fine-grained token on GitHub. Select the repositories you want and grant Metadata read, Contents read and Pull requests read. Add Contents and Pull requests write only if agents should change repositories with it. For a classic token, choose the repo scope when the repositories are private.
2. In Tares, open Settings > GitHub, choose Add a personal token, and paste it.
3. Add one source per repository: Sources > Add source > GitHub, pick the credential and the repository, and save. You can also add the source as YAML, or send the same object with POST /api/sources:

- name: checkout-api
  connector: github
  poll: 2m
  config:
    repo: acme/checkout-api
    credential: github
    labels:
      - { name: repo, field: repo, primary: true }

4. Wait for the next poll. Commits appear first. Pull requests appear as they are opened, merged or closed.

If pull requests do not show up, work through this list:

• The token lacks Pull requests read. Edit the token on GitHub, add the permission, and the next poll picks it up. The daemon log names this reason once.
• The prs option is off. It defaults to true. With prs set to false the source reports commits only.
• The pull request is old. The first poll imports recent commits and no old pull requests, so only pull requests opened, merged or closed after the source starts are reported.
• The pull request was reopened between two polls. Tares does not report it.
• You see a 403 from GitHub. The token lacks a permission, and the error names the call.

For the full field list, including branch, limit, files and api_url for GitHub Enterprise, see the GitHub connector page.

What you get

• Commits from each repository you add, with the changed files attached to each commit by default.
• Pull requests opened, merged or closed, as pull_request events keyed by owner/repo#number, once the token has Pull requests read.
• The same event types and labels the GitHub App produces for pull requests, so a trigger such as a merged-pull-request filter on event_type and action keeps working if you later switch to the App.
• A read-only token by default. Write access is added only when agents should act through it.

These events feed the triggers and agents described in AI SRE, so a deploy-related pull request can be correlated with an incident.

When something else fits

• Choose the GitHub App when you want events as they happen by webhook, more event types such as pushes, reviews, issues, releases and CI runs, every installed repository in one source, and check runs from agents. The GitHub connector page walks through both setups.
• Stay with a personal token when you want a quick, per-repository setup with polling and no public address for Tares, which a webhook would need.

Related