GitHub Integration

Connect Catalio to GitHub to create traceability between your requirements and your development workflow. Link requirements to GitHub issues, get AI code review on pull requests, and run @catalio commands directly from GitHub comments.

Overview

Why Integrate GitHub with Catalio?

The GitHub integration bridges the gap between product requirements and engineering implementation.

Traceability

Track a linked issue’s title, status, and assignee as it changes on GitHub
Get automatic AI code review on pull requests that reference a linked issue, checked against that requirement’s acceptance criteria and covering-test coverage

Reduced Context Switching

See linked-issue status directly on the requirement, without opening GitHub
Create GitHub issues from requirements with AI-drafted content in one click
Run @catalio commands (review, resolve, explain, pause, resume, help) by replying to a PR comment, without leaving GitHub

Integration Capabilities

The Catalio-GitHub integration supports:

Issue Creation & Linking: Generate GitHub issues from requirements with AI-drafted content (title, description, and acceptance criteria), or link an existing issue by searching within a connected repository
AI Code Review: Every eligible pull request in a repository with reviews enabled gets automatic AI review; a PR that references a requirement (via Closes #N and similar GitHub closing keywords, or Catalio’s component graph) also gets its diff checked against that requirement’s acceptance criteria
Interactive Commands: Reply @catalio review, resolve, explain, pause, resume, or help on a PR comment to control the reviewer
Webhook Sync: Automatic updates to a linked issue’s cached title, status, and assignee when the issue changes on GitHub
Enterprise Support: Full compatibility with GitHub Enterprise Server

Prerequisites

GitHub Account Requirements

GitHub Cloud (github.com)

Personal account with repository access, or
Organization membership with appropriate permissions
Catalio connects as a single, prebuilt GitHub App with a fixed permission set, not a tiered read-only/standard/advanced scope you choose

GitHub Enterprise Server

GitHub Enterprise Server 3.0 or later
Network connectivity between Catalio and your GitHub Enterprise instance
Admin approval for the GitHub App installation
SSL certificate properly configured (self-signed certificates require additional setup)

Repository Access

Catalio’s GitHub App requests the permissions it needs to read and write issues, read pull request and review activity, and read repository metadata (labels, milestones, and file contents for code review context). There is no separate “OAuth App” product and no choice between authentication types: every connection installs the same App, and the user-to-server OAuth token created during installation is part of that same flow, not a distinct integration option.

Catalio Project Setup

Before connecting GitHub:

Have requirements to link: Create at least one requirement so you have something to test the integration against
Confirm admin access: Connecting, disconnecting, and removing a GitHub connection requires Catalio org-admin permissions
Know which repositories you’ll use: The GitHub App installation lets you pick specific repositories or grant access to all of them

Authentication

Catalio ships a single prebuilt GitHub App. You don’t register your own OAuth App, create a GitHub App, or paste callback URLs and client credentials, you install Catalio’s App and authorize it.

Connecting Catalio’s GitHub App

As an org admin, navigate to Settings → Integrations → GitHub
Click Install on GitHub
A modal explains what the App can access and offers two paths:
- Continue to GitHub: starts a new installation
- Connect an organization you’ve already installed on: reuses an installation you (or a teammate) already granted, without going through GitHub’s installer again
On GitHub, choose the account or organization to install to, and choose which repositories to grant access to (all repositories, or a selected set)
GitHub redirects back to Catalio’s setup callback, which creates the connection for your organization
If GitHub reports more than one organization available to the installing user, Catalio shows an account-selection step so you can pick which one this connection represents; you can add more organizations later from the same flow

Each connected account appears as a card showing its status (Active, Error, or Disconnected), the GitHub account or organization name, when it was connected, token expiration (for connections that carry a refreshable OAuth token), and who connected it. Admins can:

Disconnect: marks the connection disconnected. Existing issue links stay in Catalio but stop syncing until you reconnect.
Remove: permanently deletes the connection and, if it carries an OAuth token, best-effort revokes it. To fully remove Catalio’s access on GitHub’s side, also uninstall the App from GitHub Settings → Applications → Installed GitHub Apps.
Reconnect: available on a disconnected connection to restore it through the install flow again.

A Debug Information panel (collapsed by default) shows the OAuth callback URL and GitHub App setup URL for reference, and a short note on token lifecycle: GitHub App installation tokens are minted server-side and last about an hour; the legacy OAuth user token some connections carry expires after roughly 8 hours and is refreshed automatically in the background.

Security Note: Access tokens are encrypted at rest. Revoke access anytime from GitHub Settings → Applications → Installed GitHub Apps, in addition to disconnecting or removing the connection in Catalio.

Self-Hosted GitHub App

The steps below apply only to self-hosted Catalio deployments that register their own GitHub App instead of using the prebuilt hosted App. On Catalio Cloud, use the flow above.

Step 1: Create GitHub App

Navigate to GitHub Settings → Developer settings → GitHub Apps
Click “New GitHub App”
Configure the GitHub App:
- GitHub App name: “Catalio Integration”
- Homepage URL: https://your-catalio-instance.com
- Webhook URL: https://your-catalio-instance.com/api/github/webhook
- Webhook secret: Generate a strong random secret (save for later)
- Permissions (Repository permissions):
  - Issues: Read & write
  - Pull requests: Read & write
  - Contents: Read-only
  - Metadata: Read-only
- Permissions (Organization permissions):
  - Members: Read-only
- Subscribe to events:
  - Issues
  - Issue comment
  - Pull request
  - Pull request review comment
Click “Create GitHub App”
Note your App ID
Generate and download a private key (save securely)

Step 2: Install GitHub App

Navigate to your GitHub App settings
Click “Install App” in the left sidebar
Select the organization or personal account
Choose repository access: all repositories, or only selected ones
Click “Install”

Step 3: Configure the GitHub App in Catalio

Self-hosted deployments supply GitHub App credentials through environment configuration for the deployment — App ID, App name, OAuth client ID and secret, private key, and webhook secret. Contact your Catalio administrator or support@catalio.ai for the setup checklist.

Installation IDs are captured automatically when each organization installs the App in Catalio.

Step 4: Verify the Connection

In Catalio, navigate to Settings → Integrations → GitHub and click Install on GitHub
Complete the installation on GitHub
Confirm the connection appears with status “Active” after the redirect back to Catalio
Test by generating or linking an issue from a requirement, and confirm it appears on GitHub

Security Best Practices:

Store private keys in secure secrets management (e.g., HashiCorp Vault)
Rotate the webhook secret periodically (see Webhook Security below; Catalio checks against a single configured secret, so rotation is a cutover, not an overlap window)
Use separate GitHub Apps for development and production environments
Regularly audit GitHub App installations and repository access from GitHub’s side

GitHub Enterprise Configuration

Verify network connectivity between Catalio and your GitHub Enterprise instance
SSL certificates: valid certificates need no extra configuration; self-signed certificates require adding the certificate to Catalio’s trusted store
Set your GitHub Enterprise Server API URL in the deployment configuration for your Catalio instance
Configure firewall rules to allow webhook callbacks from GitHub Enterprise to Catalio

Creating and Linking Issues

Creating Issues from Requirements

Open a requirement in Catalio
Click “Generate GitHub Issue”
Catalio checks whether an existing GitHub issue already appears to cover the requirement. If it finds one with no material changes since, it warns you and lets you generate anyway; if it finds meaningful differences, it surfaces a short summary of what changed and proceeds
Review the AI-drafted title and description (both editable)
Select the target repository. Labels and a milestone from that repository are optional and loaded once you pick a repo
Click “Create Issue”

The issue is created in GitHub with the description plus an “Acceptance Criteria” section appended from the requirement, and linked back to the requirement automatically.

Linking Existing Issues

Open a requirement in Catalio and choose to link an existing GitHub issue
Select a repository, then search by title or number
Select the issue from the results to link it

Unlinking is available from the requirement’s issue list; it removes the link but does not affect the issue on GitHub.

Keeping Issues in Sync

Once linked, Catalio keeps a linked issue’s cached title, status, and assignee up to date via GitHub webhooks: opening, reopening, closing, editing, or reassigning the issue on GitHub updates the cached fields Catalio displays. As a fallback to webhooks, Catalio also periodically refreshes cached issue metadata directly from the GitHub API. Linking, unlinking, and the cached fields themselves are covered in more depth in the Issue Links documentation, since the same model backs Linear links as well.

Note that syncing updates the linked issue’s cached title/status/assignee. It does not automatically move the requirement’s own Catalio workflow status; requirement status changes stay a deliberate action in Catalio.

AI Code Review on Pull Requests

When a repository is connected to an Application for code context (see Repositories) and PR reviews are enabled for that repository, Catalio automatically reviews pull requests:

A review runs when a PR is opened, pushed to (synchronize), reopened, or marked ready for review. Draft PRs and PRs authored by other bots are skipped.
The review checks the diff against the acceptance criteria of any requirement the PR references, either through Catalio’s component graph or through a Closes #N / Fixes #N / Resolves #N reference to a linked GitHub issue.
For requirements it can trace, the review also reports acceptance criteria that ship without a covering test, based on Catalio’s requirement-to-test-case graph, not just the diff.
Nitpick-level comments (minor style and polish suggestions) can be toggled on or off per repository, alongside the PR-review toggle itself.

Interactive `@catalio` Commands

Reply to a PR comment or an inline review comment mentioning @catalio (or your configured App slug) followed by a command:

Command	Aliases	What it does
`review`	`re-review`, `rereview`	Re-runs the review
`resolve`	`resolved`	Marks a finding resolved
`explain`	`why`	Asks the reviewer to explain a finding
`pause`	`ignore`, `mute`	Pauses the reviewer on this PR
`resume`	`unpause`	Resumes a paused reviewer
`help`	`commands`	Lists available commands

Only commenters with OWNER, MEMBER, or COLLABORATOR standing on the repository can trigger a command; comments from other associations or from bots are ignored. Commands also require PR reviews to be enabled for the repository and GitHub PR commands to be enabled for your organization.

Review Learnings

When a human replies to one of the reviewer’s own inline findings (not a @catalio command, just a regular reply), Catalio can extract the correction as a “review learning” to improve future reviews. This only considers genuine replies to a bot-authored comment; edits to the reply and deleted replies are ignored.

Connecting Repositories

Repositories are connected from an Application’s Integrations tab in Catalio, not from GitHub Settings. Connecting a repository triggers a sync that reads the repository tree and builds the Component graph Catalio uses for traceability and PR review context, and lets you toggle PR review and nitpick comments per repository. See Repositories for the full connection and sync model, including incremental sync and path-based Application mapping for monorepos.

Webhook Security

Catalio validates every incoming GitHub webhook using HMAC-SHA256:

GitHub signs the payload with your webhook secret and sends it in the X-Hub-Signature-256 header
Catalio recomputes the signature from the raw request body and compares it
A missing or invalid signature is rejected with a 401 response before any event processing runs