Skip to content

DocsIntegrations

GitHub

Link branches, commits and pull requests to tickets, move tickets automatically, and backfill lines changed.

How it works

  • Each project has its own webhook URL, secret and list of allowed repositories.
  • A repository can belong to only one project.
  • Branches, commits and pull requests that mention a ticket key link to that ticket.
  • Configured events can move tickets forward automatically.

An organization admin sets this up in the project's Settings › GitHub integration.

Connect a repository

  1. 01In Praxis, open the project's Settings and expand GitHub integration.
  2. 02Under GitHub repositories, enter each repository as owner/repository, one per line.
  3. 03Enter a webhook secret, or choose Generate secret. Save the project.
  4. 04Copy the Payload URL shown in Praxis.
  5. 05On GitHub, open the repository's Settings › Webhooks › Add webhook. You need admin access to the repository.
  6. 06Paste the payload URL, set content type to application/json and enter the same secret.
  7. 07Select the events Branch or tag creation, Pushes and Pull requests. Keep SSL verification on and the webhook Active.
  8. 08Check Recent deliveries on GitHub for a successful response.

The payload URL has the form https://praxis.theorem-labs.com/api/github/org/<organization>/<PROJECT-KEY>. Always copy it from Praxis.

How tickets are matched

Put the ticket key in a branch name, commit message, or pull request title or body.

  • PROJ-123, proj-123 and proj123 all match.
  • So feat/PROJ-123-thing and chore/docs-proj586 both work.
  • Matching is per project. A key from another project matches nothing.

Automatic moves

EventDefault move
Branch created or first pushIn Progress
Pull request opened or reopenedUnder Review
Pull request mergedDone
Pull request closed without mergingIn Progress
  • Moves only go forward. A late push to an old branch links the commit but never moves a Done ticket back.
  • Under Automation rules, keep the organization defaults or choose Customize this project.
  • Each event can move to In Progress, Under Review or Done, or be set to Do nothing.

Lines changed and Backfill

Praxis records additions, deletions and changed files for linked pull requests. Flow uses these numbers.

  • New pull requests arrive with their counts through the webhook.
  • For older ones, add a GitHub API token in GitHub integration. Use a fine-grained token for the selected repositories with Pull requests: Read-only.
  • Save, then choose Backfill lines changed. Each click checks up to 200 pull request records.
  • The result reports updated, remaining and skipped records. If GitHub rate-limits you, wait and try again.