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.
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:
| Event | Action |
|---|---|
pull_request.opened | Links PR to mentioned issues |
pull_request.merged | Records merge, auto-closes linked issue |
pull_request.closed | Records closure event |
pull_request.reopened | Reopens linked Velocity issue |
push | Scans commits for issue mentions |
issues.opened | Auto-creates Velocity issue (if enabled) |
issues.closed | Syncs status to completed (if enabled) |
issues.reopened | Reopens linked Velocity issue |
ping | Acknowledges webhook configuration |
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.