GitHub

Tares connects to GitHub in one of two ways. You pick a credential, and Tares decides how events arrive.

With the GitHub App

On Tares Cloud

In your workspace settings, choose Connect GitHub, pick the organization and the repositories, and confirm on GitHub. Your workspace gets a github source carrying every event of those repositories. To add another organization, choose Connect another account. Disconnect removes the credential from your workspace and uninstalls the App on GitHub.

Self-hosted

1. Open Settings > GitHub and choose Create GitHub App.
2. Enter the GitHub organization to create it in (leave it empty for your own account). Under Address and App name, check that the address is how GitHub reaches this Tares.
3. Choose Continue on GitHub. GitHub shows the App with its permissions and events filled in. Confirm it.
4. Back in Tares, choose Install on GitHub, pick the repositories, and install.

Tares stores the App (its id, private key and webhook secret) as a credential and creates a github source for its webhook. Nothing is pasted by hand.

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

Already have an App? Add it under Settings > GitHub through the API with its app id, private key, webhook secret and installation ids (POST /api/integrations/github with kind: app), then point the App’s webhook at the github source’s ingest URL.

The App asks for these permissions, which you can narrow on GitHub’s page:

and these events: pull request, pull request review, pull request review comment, push, issues, issue comment, release, workflow run.

With a 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. A classic token needs the repo scope for private repositories.
2. Open Settings > GitHub, choose Add a personal token, and paste it.
3. Add a source per repository: Sources > Add source > GitHub, pick the credential and the repository, and save.

Each source polls its repository’s commits and its pull requests. The first poll imports recent commits and no old pull requests. A pull request reopened between two polls is not reported. If the token cannot read pull requests, commits still arrive and the daemon log says why once.

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

Events and labels

Both ways produce the same events, so a trigger keeps working when you switch from a token to the App.

Every GitHub event carries these labels when they apply: repo, action (opened, synchronize, merged, closed, reopened, ready_for_review, submitted, created, published, completed, pushed), number, author, branch, base, state, draft, sha, url, title, conclusion (CI runs), release_tag, workflow, commits (pushes) and on_default_branch (pushes). A closed pull request that merged reads merged.

Example: every merged pull request in two repositories. A trigger on the github source with these filters, one firing per pull request:

- name: pr-merged
  sources: [github]
  filters:
    - { field: event_type, op: eq, value: pull_request }
    - { field: action, op: eq, value: merged }
    - { field: repo, op: in, value: [acme/checkout-api, acme/payments] }
  condition: { aggregate: count, predicate: "> 0", window: 5m }
  cooldown: 5m

In the console’s trigger editor, a filter on event_type or action over a GitHub source offers these values to pick from.

Agents on GitHub

In a Tares agent’s settings, the GitHub section picks a credential and what the agent may do: read repositories, or read and write (branches, files, pull requests, comments, reviews). Reads and writes go through GitHub’s MCP server, authenticated with that credential, so with the App every write shows as the App. Tares sets the server up the first time; there is nothing to register.

With the App, the agent can also post its verdict on a pull request as a check run: a pass, fail or neutral result in the pull request’s checks, with notes on the lines it is about. Ask for it in the agent’s instructions, for example “post your verdict as a check run on the pull request’s head commit”. Every GitHub call shows in the run’s record, and a check run appears in the run’s results.

Troubleshooting

• No deliveries from the App. Check that Tares is reachable at the address the App uses (a local Tares needs a tunnel) and that the App is installed on the repository. GitHub’s App settings list recent deliveries under Advanced, with their responses.
• Deliveries refused (401). The webhook secret on GitHub does not match the credential’s. A recreated App gets a new one; reconnect it from Settings > GitHub.
• A 403 from GitHub. The App or token lacks a permission; the error names the call. On the App, accept new permissions on GitHub after changing them.
• Pull requests do not arrive on a token source. The token lacks Pull requests read.