Link GitHub Commits to Tasks | Auto-Traceability
Auto-link commits and PRs to GitScrum tasks using task IDs (GS-123). Task status updates on PR merge. Works with GitHub and GitLab integrations.
5 min read
Without automatic linking, developers must manually update tasks when code is committed, leading to outdated task status and missing context. GitScrum's GitHub integration automatically connects commits and PRs to tasks, providing real-time visibility into code progress.
Integration Benefits
| Without Integration | With Integration |
|---|---|
| Manual status updates | Auto-update on PR |
| No code visibility | Commits on task |
| Duplicate information | Single source of truth |
| Lost context | Full history |
Setup Process
GitHub App Installation
GITHUB INTEGRATION SETUP
════════════════════════
STEP 1: Install GitHub App
─────────────────────────────────────
GitScrum Settings → Integrations → GitHub
Click "Install GitHub App"
Select organization/repos
Authorize permissions
STEP 2: Configure Repositories
─────────────────────────────────────
Choose repositories to connect
Map repos to GitScrum projects
Set default behaviors
STEP 3: Set Linking Rules
─────────────────────────────────────
Task ID pattern: GS-[0-9]+
Branch pattern: feature/GS-[0-9]+-*
Auto-transition: Enabled
PERMISSIONS REQUIRED:
├── Read repository contents
├── Read/write issues
├── Read/write pull requests
├── Read commit status
└── Webhooks
Project Mapping
REPOSITORY → PROJECT MAPPING
════════════════════════════
┌────────────────────────────────────────────────────────┐
│ GitHub Repository │ GitScrum Project │
├────────────────────────────────────────────────────────┤
│ acme/frontend │ Acme Website │
│ acme/backend-api │ Acme Website │
│ acme/mobile-app │ Acme Mobile App │
│ acme/shared-libs │ (All projects) │
└────────────────────────────────────────────────────────┘
MULTI-REPO PROJECT:
├── Multiple repos → one project
├── PRs show on related tasks
└── Context across codebase
Commit Linking
Commit Message Format
COMMIT MESSAGE PATTERNS
═══════════════════════
STANDARD FORMAT:
GS-123: Brief description
EXAMPLES:
─────────────────────────────────────
GS-456: Add user authentication flow
GS-456: Fix token refresh bug
GS-789: Update dashboard styles
─────────────────────────────────────
MULTIPLE TASKS:
GS-123, GS-124: Shared refactoring
CONVENTIONAL COMMITS + TASK:
feat(auth): GS-123 add OAuth support
fix(api): GS-456 handle null response
PATTERNS RECOGNIZED:
├── GS-123
├── GS-123:
├── [GS-123]
├── (GS-123)
└── Fixes GS-123
What Gets Linked
LINKED DATA ON TASK
═══════════════════
TASK VIEW:
┌─────────────────────────────────────────────────┐
│ Task: GS-456 Implement user login │
├─────────────────────────────────────────────────┤
│ Status: In Review │
├─────────────────────────────────────────────────┤
│ CODE │
│ ───── │
│ Branch: feature/GS-456-user-login │
│ │
│ Commits (3): │
│ ├── abc123: Initial auth setup │
│ ├── def456: Add password validation │
│ └── ghi789: Fix edge cases │
│ │
│ Pull Request: │
│ ├── #234: Add user authentication │
│ ├── Status: Review requested │
│ ├── Checks: ✓ All passing │
│ └── Reviews: 1/2 approved │
└─────────────────────────────────────────────────┘
Branch Integration
Branch Naming Convention
BRANCH NAMING PATTERNS
══════════════════════
RECOMMENDED FORMAT:
type/GS-[task-id]-brief-description
EXAMPLES:
├── feature/GS-123-user-authentication
├── fix/GS-456-login-bug
├── chore/GS-789-update-dependencies
└── hotfix/GS-999-critical-fix
AUTO-DETECTED PATTERNS:
├── GS-123-*
├── feature/GS-123-*
├── */GS-123-*
└── GS-123/*
BRANCH → TASK LINK:
├── Auto-creates link when pushed
├── Shows branch on task
├── Tracks branch status
└── Links to repo
Branch Creation Workflow
BRANCH FROM TASK
════════════════
FROM GITSCRUM:
1. Open task
2. Click "Create Branch"
3. Select repository
4. Branch auto-named: feature/GS-123-task-title
5. Copy git command
6. Checkout locally
GIT COMMAND PROVIDED:
git checkout -b feature/GS-123-task-title
BENEFITS:
├── Consistent naming
├── Auto-linked immediately
├── No manual formatting
└── Less typos
Pull Request Integration
PR Linking
PULL REQUEST LINKING
════════════════════
AUTO-LINK WHEN:
├── PR title contains GS-[id]
├── PR branch contains GS-[id]
├── PR description contains GS-[id]
└── Commits reference GS-[id]
PR TEMPLATE (recommended):
─────────────────────────────────────
## Related Task
GS-123
## Changes
- Description of changes
## Testing
- How to test
## Screenshots (if applicable)
─────────────────────────────────────
Status Automation
PR → TASK STATUS AUTOMATION
═══════════════════════════
RULE 1: PR Opened
─────────────────────────────────────
Trigger: PR opened with GS-[id]
Action: Move task to "In Review"
Assign: Add PR reviewers as watchers
RULE 2: PR Approved
─────────────────────────────────────
Trigger: Required reviews approved
Action: Add label "approved"
Update: Task shows approval status
RULE 3: PR Merged
─────────────────────────────────────
Trigger: PR merged to main
Actions:
├── Move task to "Done"
├── Add label "shipped"
├── Close task (optional)
└── Notify stakeholders
RULE 4: PR Closed (not merged)
─────────────────────────────────────
Trigger: PR closed without merge
Action: Move task back to "In Progress"
Alert: Notify task owner
CI/CD Integration
Build Status
CI STATUS ON TASK
═════════════════
TASK VIEW SHOWS:
┌─────────────────────────────────────────────────┐
│ Build Status │
├─────────────────────────────────────────────────┤
│ PR #234: Add authentication │
│ ├── ✓ lint (passed) │
│ ├── ✓ test (passed) │
│ ├── ✓ build (passed) │
│ └── ✓ deploy-preview (ready) │
│ │
│ Preview: https://preview-234.app.dev │
└─────────────────────────────────────────────────┘
FAILURE HANDLING:
├── Build fails → Task flagged
├── Notification to assignee
├── Auto-label "build-failed"
└── Blocks merge automation
Best Practices
For Git Integration
Anti-Patterns
INTEGRATION MISTAKES:
✗ Forgetting task IDs in commits
✗ Multiple tasks per branch
✗ Manual status updates
✗ Not using PR templates
✗ Ignoring CI integration
✗ Not mapping all repos