Git Workflow Skill
Expert patterns for Git version control: branching, commits, collaboration, and CI/CD.
Expertise Areas
- •Branching: Git Flow, GitHub Flow, Trunk-based development
- •Commits: Conventional Commits, semantic versioning
- •Collaboration: PR workflows, code review, merge strategies, thread resolution
- •CI/CD: GitHub Actions, GitLab CI, branch protection
Reference Files
Detailed documentation for each area:
| Reference | When to Load |
|---|---|
references/branching-strategies.md | Managing branches, choosing branching model |
references/commit-conventions.md | Writing commits, semantic versioning |
references/pull-request-workflow.md | Creating/reviewing PRs, thread resolution, merging |
references/ci-cd-integration.md | CI/CD automation, GitHub Actions |
references/advanced-git.md | Rebasing, cherry-picking, bisecting |
references/github-releases.md | Release management, immutable releases |
Explicit Content Triggers
When creating pull requests, load references/pull-request-workflow.md for PR structure, size guidelines, and template patterns.
When reviewing PRs or responding to review comments, load references/pull-request-workflow.md for review comment levels (blocking/suggestion/nit) and the code review checklist.
When replying to PR review threads or resolving threads, load references/pull-request-workflow.md for the GraphQL API patterns for thread replies and resolution.
When merging PRs, load references/pull-request-workflow.md for the merge requirements checklist (resolved threads, Copilot review, rebased branch, CI checks).
When merging in repos requiring signed commits with rebase-only strategy, load references/pull-request-workflow.md for the local fast-forward merge workflow.
When handling merge conflicts, load references/pull-request-workflow.md for conflict resolution strategies.
When choosing a branching strategy, load references/branching-strategies.md for Git Flow, GitHub Flow, and Trunk-based patterns.
When writing commit messages, load references/commit-conventions.md for Conventional Commits format and semantic versioning rules.
When creating releases, load references/github-releases.md for immutable release warnings and recovery patterns.
Ticket ID Lookup
Before committing or creating branches, look up the ticket ID and GitHub issue from:
bmad/docs/sprint-status.yaml
Each story entry contains:
- story_id: "AOS-103" title: "Chart of Accounts Schema" github_issue: 50
Use format: <TICKET-ID>: prefix (e.g., AOS-103: Add feature) or Conventional Commits with ticket in scope (e.g., feat(AOS-103): Add feature).
Claude Code Session ID (Required)
When committing via Claude Code, include session ID as a Git trailer:
feat(auth): add OAuth2 login Implements OAuth2 flow with refresh token handling. AI-Session: a519c65f-7ed4-4265-90fa-42f116c1e8fd Refs #123
Use AI-Session: trailer (not bare UUID) because:
- •Parseable with
git interpret-trailers --parse - •Queryable:
git log --format='%(trailers:key=AI-Session,valueonly)' - •GitHub recognizes and displays trailers
- •Follows established conventions (Signed-off-by, Co-authored-by)
Conventional Commits (Quick Reference)
<type>[scope]: <description>
Types: feat (MINOR), fix (PATCH), docs, style, refactor, perf, test, build, ci, chore, revert
Breaking change: Append exclamation mark to type (e.g., feat!:) or add BREAKING CHANGE: in footer.
Branch Naming
Format: <type>/<TICKET-ID>-<description> or <type>/<description> (no ticket)
| Prefix | Purpose | Commit Type |
|---|---|---|
feature/ | New functionality | feat: |
bugfix/ | Bug fixes (with ticket) | fix: |
fix/ | General fixes | fix: |
hotfix/ | Urgent production fixes | fix: |
chore/ | Maintenance tasks | chore: |
docs/ | Documentation | docs: |
refactor/ | Code restructuring | refactor: |
test/ | Test improvements | test: |
ci/ | CI/CD changes | ci: |
Rules:
- •Ticket ID: UPPERCASE (e.g.,
AOS-123,GH-1) - •Description: lowercase-kebab-case
Examples:
feature/AOS-123-add-user-login bugfix/AOS-456-fix-null-response chore/update-dependencies docs/GH-1-contribution-guidelines
Validation regex:
^(feature|bugfix|fix|hotfix|chore|docs|refactor|test|ci)\/(([A-Z]+-[0-9]+)-)?[a-z0-9]+(-[a-z0-9]+)*$
GitHub Flow (Default)
git checkout main && git pull git checkout -b feature/AOS-123-my-feature # ... work ... git push -u origin HEAD gh pr create --title "feat(AOS-123): my feature description" && gh pr merge --squash
PR Title Format
PR titles must follow Conventional Commits:
<type>(<scope>): <description>
Examples:
feat(AOS-123): add cost center schema fix(AOS-111): resolve VAT calculation edge case docs(readme): update installation instructions
PR Description
Must include:
- •Summary with Ticket/Issue reference
- •Problem addressed and Solution applied sections
- •AI Assistance section with
AI-Session: <uuid>
Quality Checks Before PR
Run all checks before creating a PR:
uv run pytest uv run ruff check . uv run mypy .
Verification
./scripts/verify-git-workflow.sh /path/to/repository
GitHub Immutable Releases
CRITICAL: Deleted releases block tag names PERMANENTLY. Get releases right first time.
See references/github-releases.md for prevention and recovery patterns.