GitHub integration

Tracemason connects to GitHub through a GitHub App — not a personal access token. Everything it stores arrives in signed webhook deliveries; it makes no GitHub API calls and holds no installation tokens.

What it records

For repositories you select when installing the App:

  • Commits (SHA, first line of the message, author, branch, changed file paths)
  • Pull requests (number, title, state, branches, head and merge SHAs)
  • Check status for a pull request's head commit
  • Deployments and their status

Only the first line of a commit message is stored, plus an Tracemason-Session: trailer if present.

Connect GitHub

Not yet available on the hosted service. The Tracemason GitHub App has not been registered yet, so Integrations → GitHub cannot install it at app.tracemason.com. Everything below it is built and tested against signed deliveries; a self-hosted server can use its own App today (see the end of this page).

Once it is available: Integrations → GitHub → Install the GitHub App, then choose repositories on GitHub. You are redirected back and the installation is bound to your organization.

The redirect carries a signed, expiring state value tied to the user and organization that started the install, so an installation cannot be attached to someone else's organization. An installation can belong to only one organization.

Security of webhooks

  • Every delivery's X-Hub-Signature-256 is verified against the raw request bytes in constant time. Unsigned, wrongly signed or modified deliveries get 401.
  • X-GitHub-Delivery ids are remembered, so a replayed delivery is acknowledged and ignored.
  • A delivery for an installation no organization has connected is dropped.

Correlation

When Git activity arrives, Tracemason re-examines recent sessions in that repository and records links with a provenance label and a reason — see Concepts → Provenance. Open a trace to see its linked commits, pull requests and deployments; open a repository to see which sessions each commit is linked to.

Git correlation requires the Team plan or above.

Self-hosted: set up your own GitHub App

On a self-hosted server you register the App yourself.

  1. Create a GitHub App in your organization.
    • Webhook URL: https://<your Tracemason host>/api/webhooks/github
    • Webhook secret: a random string; put the same value in GITHUB_WEBHOOK_SECRET.
    • Setup URL (post-install redirect): https://<your Tracemason host>/api/integrations/github/callback
    • Repository permissions (read-only): Metadata, Contents, Pull requests, Checks, Deployments, Commit statuses.
    • Subscribe to events: Push, Pull request, Check suite, Check run, Status, Deployment, Deployment status.
  2. Set GITHUB_APP_SLUG (the App's URL slug) and GITHUB_WEBHOOK_SECRET on the Tracemason API.
  3. In Tracemason: Integrations → GitHub → Install the GitHub App. Choose repositories on GitHub. You are redirected back and the installation is bound to your organization.

This flow has been exercised against the local harness below, not yet against a live GitHub App. The webhook path — verification, normalization, storage, correlation — is identical in both.

Self-hosted: local harness

On a development server without a GitHub App you can still exercise the whole path:

  1. Integrations → GitHub → Register test installation.
  2. Send signed deliveries:
pnpm github:simulate --org <slug> --repo acme/payments-api --session <session id>

The script signs payloads with your GITHUB_WEBHOOK_SECRET and posts a push, a pull request, a check suite and a deployment. They are verified and processed exactly like real deliveries. The harness is unavailable in production and when a real App is configured.

GitLab

Planned. The provider interface (GitProviderAdapter) is in place and GitLab will implement it; nothing GitLab-specific is built yet.