What is the difference between connecting GitHub with the GitHub App and with a personal token?

Tares connects GitHub with the GitHub App, which delivers events by webhook as they happen, or with a personal token, which polls every 2 minutes by default. The App covers pull requests, pushes, reviews, comments, issues, releases and CI runs across every installed repository in one source. A token covers commits and pull requests opened, merged or closed, with one source per repository. Agents act as the App or as the token’s user, and only the App supports check runs.

How it works

You pick a credential, and Tares decides how events arrive. The GitHub connector page has the full reference.

• GitHub App (recommended). GitHub sends events by webhook as they happen. You get pull requests, pushes, reviews, review comments, comments, issues, releases and CI runs. Every repository the App is installed on feeds one github source.
• Personal token. Tares polls GitHub, every 2 minutes by default. You get commits, and pull requests opened, merged or closed. You add one source per repository.

The first poll of a token source imports recent commits and no old pull requests. A pull request reopened between two polls is not reported.

Agents act under the credential you choose in the agent’s GitHub settings. With the App, every write shows as the App (your-app[bot]). With a token, writes show as the token’s user. Only the App lets an agent post its verdict as a check run on a pull request.

Both ways produce the same events and labels, such as repo, action, number, author and branch. A trigger written for a token keeps working when you switch to the App. For example, pull_request events arrive with both, while commit events come only from a token, and push, issues, release and workflow_run events come only from the App.

Every App delivery is checked against the App’s webhook secret before anything is stored. A delivery GitHub sends twice is stored once.

Set it up

GitHub App on Tares Cloud

1. In your workspace settings, choose Connect GitHub.
2. Pick the organization and the repositories, and confirm on GitHub. Your workspace gets a github source carrying every event of those repositories.

GitHub App on a self-hosted Tares

1. Open Settings > GitHub and choose Create GitHub App.
2. Enter the GitHub organization, or leave it empty for your own account, and check that the address is how GitHub reaches this Tares.
3. Choose Continue on GitHub and confirm the App with its permissions and events.
4. Back in Tares, choose Install on GitHub, pick the repositories and install.

Tares stores the App as a credential and creates the github source for you. GitHub must be able to reach your Tares for webhooks to arrive. A local tares up is not reachable from the internet, so run a tunnel and use its address as the public URL:

cloudflared tunnel --url http://localhost:8787
TARES_PUBLIC_URL=https://<your-tunnel>.trycloudflare.com tares up

Personal token

1. Create a fine-grained token on GitHub with the repositories you want, and these permissions: Metadata read, Contents read, Pull requests read. Add Contents and Pull requests write only if agents should change repositories with it.
2. Open Settings > GitHub, choose Add a personal token and paste it.
3. For each repository, go to Sources > Add source > GitHub, pick the credential and the repository, and save.

The resulting source looks like this:

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

If pull requests do not arrive on a token source, the token lacks Pull requests read. Commits still arrive.

What you get

• With the App: events as they happen, no polling delay, and all installed repositories in one source. Reviews, comments, issues, releases, pushes and CI runs are included, so triggers can react to the whole pull request lifecycle.
• With the App: agents that post a check run, a pass, fail or neutral result with notes on the lines it is about, on a pull request’s head commit. Ask for it in the agent’s instructions.
• With a token: a quick start on a Tares that GitHub cannot reach, because Tares pulls from GitHub and needs no webhook delivery.
• With either: the same event types and labels, so a trigger such as one that fires on every merged pull request in two repositories works unchanged. Use it as the first step when you build on the AI SRE guide.

For a repository set that grows, the App saves you from adding a source for each one.

When something else fits

Choose a personal token when you only need commits and pull requests opened, merged or closed for a few repositories, or when your Tares cannot be reached from GitHub. Choose the GitHub App when you want reviews, comments, issues, releases, pushes or CI runs, events as they happen, agent writes under an App identity, or check runs.

Related