GitHub Integration

Link pull requests, sync issues, and auto-update status from commits.

Setup

Go to Settings → Integrations and click Connecton the GitHub card. You will be redirected to GitHub to authorize the Velocity OAuth app. Select the repositories you want to connect.

After authorization, a webhook secret is automatically generated for verifying incoming events. You can view this secret on the integration settings page.

Agent branches and pull requests

Local and cloud Claude agents can use create_branch and open_prthrough your workspace GitHub connection. MCP connections need write scope for both tools. Configure repository mappings and Agent pull requests under Settings → Integrations → GitHub.

The issue's project mapping takes priority over its team mapping. Without a mapping, one selected repository can be used; multiple matches require an explicit mapping. Branch names default to agent/{identifier}-{slug}. Use {identifier} and {slug} in the branch template. PR templates support {summary}, {identifier}, {title}, {issue_url}, {branch}, {base}; Velocity always includes a link to the issue detail panel.

Call create_branch with the issue identifier and, optionally, a base or branch name. Commit and push your changes using your code execution environment, then call open_prwith the issue identifier, returned branch name, summary and optional draft flag. The tools create branches and PRs; they do not edit files, commit code, push changes, force-update refs or merge PRs. Existing branches and open PRs are reused on retries. Successful PRs use the same issue-link path as link_pr.

Set an optional team status name such as In Review to transition the issue after linking. Completed or cancelled issues keep their status, and a status changed during the request is preserved. Leave this setting blank to disable the transition. If linking or transition fails after GitHub creates the PR, the error includes its URL; retry open_pr to complete the remaining step.

The GitHub credential needs repository access and write permission for Contents (branches) and Pull requests (PRs). OAuth connections need repo for private repositories orpublic_repo for public repositories. Reconnect GitHub if access is missing or expired, and check organization SSO and repository rules if GitHub refuses creation.

PR Linking

When a pull request title, body, or branch name contains a Velocity issue identifier (e.g., ENG-42), Velocity automatically links the PR to the issue. The link appears in the issue's activity feed with the PR title, author, and branch information.

Commit Mentions

Commit messages that mention issue identifiers are also tracked. Include the identifier anywhere in the commit message:

git commit -m "Fix pagination bug ENG-42"

Auto-Create Issues

When enabled, new GitHub issues are automatically imported into Velocity with a [GitHub] prefix. The imported issue includes:

  • Rich Tiptap description with author, labels, and milestone
  • Direct link back to the GitHub issue
  • Assignment to the configured default team

Repository-to-team mapping lets you route issues from different repos to different Velocity teams.

Auto-Close on Merge

When a PR is merged, Velocity automatically moves the linked issue to the team's completed status. This is enabled by default and can be toggled from the settings page.

Bidirectional Status Sync

Enable Sync resolved status to keep GitHub issues and Velocity issues in sync:

  • Closing a GitHub issue moves the linked Velocity issue to completed
  • Reopening a GitHub issue resets the Velocity issue to its default status
  • Completing a Velocity issue closes the linked GitHub issue via the API

Issue Import

The settings page includes a bulk import wizard. Select a repository, filter by open or closed state, pick individual issues, and import them into a Velocity team in one click.

Repository Mapping

Map GitHub repositories to specific Velocity teams and projects. When events arrive from a mapped repository, auto-created issues are routed to the correct team automatically.

Webhook Events

The GitHub integration processes the following webhook events:

EventAction
pull_request.openedLinks PR to mentioned issues
pull_request.mergedRecords merge, auto-closes linked issue
pull_request.closedRecords closure event
pull_request.reopenedReopens linked Velocity issue
pull_request.synchronize, edits and draft changesRecords the current PR head and state for issue monitors, including when AI enrichment is off
check_run, check_suite, statusRecords check callbacks for an already linked exact repository/PR or repository/commit
pushScans commits for issue mentions
issues.openedAuto-creates Velocity issue (if enabled)
issues.closedSyncs status to completed (if enabled)
issues.reopenedReopens linked Velocity issue
pingAcknowledges webhook configuration

Include check runs, check suites and commit statuses in your GitHub webhook subscriptions to receive these callbacks. Unknown PRs/commits are ignored; check names cannot link an issue. Agents can use issue monitoring and check waits to resume after changes. Live check waits read GitHub directly and work independently of callback delivery.

Deduplication

Events are deduplicated by GitHub URL. If a PR or issue event fires multiple times, the existing event record is updated rather than creating duplicates. An occurrence counter tracks how many times the event has been seen.

Security

All incoming webhooks are verified using HMAC-SHA256 signature validation via the X-Hub-Signature-256 header. The webhook secret is generated during setup and stored securely. Invalid signatures are rejected with a 401 response.