AgentSkillsCN

git-workflow

设计涵盖分支策略、主干开发、堆叠变更、常规提交、CI/CD 流水线，以及仓库卫生管理的 Git 工作流。当您需要搭建分支模型、撰写提交信息、配置 GitHub Actions、管理堆叠 PR、清理过期分支、创建议题模板，或恢复丢失的提交时，可选用此工具。

SKILL.md
--- frontmatter
name: git-workflow
description: 'Designs git workflows covering branching strategies, trunk-based development, stacked changes, conventional commits, CI/CD pipelines, and repository hygiene. Use when setting up branching models, writing commit messages, configuring GitHub Actions, managing stacked PRs, cleaning stale branches, creating issue templates, or recovering lost commits.'
license: MIT
metadata:
  author: oakoss
  version: '1.0'

Git Workflow

Covers branching strategies, conventional commits, CI/CD automation, repository hygiene, and git internals. GitHub CLI usage is handled by a separate github-cli skill; this skill focuses on git workflow patterns and CI/CD configuration.

Quick Reference

AreaKey Practice
BranchingTrunk-based development with short-lived feature branches
CommitsConventional commits with imperative mood
HistoryLinear history via rebase; squash noisy commits
PRsSmall, stacked changes; no mega PRs
Main branchAlways deployable; broken main is an emergency
CI/CDModular GitHub Actions with reusable workflows
MergingGreen CI + review required before merge
VersioningSemantic Release or Changesets (never manual)
BranchesMax 48 hours lifespan; auto-prune stale/merged
SecretsOIDC Connect in pipelines; never hardcode tokens
SigningSign commits with SSH or GPG keys for verified authorship

Branch Naming

TypeUse ForExample
featNew featuresfeat/add-user-auth
fixBug fixesfix/login-redirect
choreMaintenancechore/update-deps
docsDocumentationdocs/api-reference
refactorCode restructuringrefactor/auth-module

Conventional Commit Types

TypePurposeVersion Bump
featNew featuresMinor
fixBug fixesPatch
docsDocumentation onlyNone
styleFormatting, no logic changesNone
refactorNeither fix nor featureNone
perfPerformance improvementsPatch
testAdding or correcting testsNone
buildBuild system or external dependenciesNone
ciCI configuration changesNone
choreTooling, maintenance, non-src changesNone
revertRevert a previous commitVaries

Append ! after type/scope for breaking changes (major version bump).

Pre-Merge Checks

All PRs require before merge:

  • •Lint
  • •Type check
  • •Tests
  • •Security scan
  • •Review approval (human or automated)

Auto-merge is acceptable for low-risk PRs when pipeline succeeds.

Troubleshooting

IssueResolution
Merge conflicts on long-running branchRebase onto main frequently; break remaining work into new branch if over 48 hours
Broken main branchTreat as emergency; revert offending commit, then fix forward on a branch
Lost commits or data recoveryUse git reflog and object inspection (git cat-file, git fsck)
CI pipeline failuresCheck reusable workflow versions; verify OIDC permissions
Stacked PR conflicts after rebaseRestack entire chain from base; Graphite handles automatically with gt restack
Large file accidentally committedUse git filter-repo to remove from history (not git filter-branch)

Common Mistakes

MistakeCorrect Pattern
Keeping feature branches alive longer than 48 hoursMerge or rebase daily; break large work into stacked PRs
Committing directly to main without branch protectionEnable branch protection rules requiring CI and review
Using merge commits that clutter historyRebase and squash to maintain linear history
Hardcoding tokens in GitHub Actions workflowsUse OIDC Connect for authentication in CI/CD pipelines
Creating monolithic CI workflows in a single fileSplit into reusable workflows and composite actions
Fix bug as commit messagefix(scope): correct bug description (conventional)
feat: Added feature (past tense)feat: add feature (imperative mood, lowercase)
Using git filter-branch for history rewritingUse git filter-repo (faster, safer, officially recommended)
Pushing to main directlyCreate feature branch first
Unsigned commits in shared repositoriesConfigure commit signing with SSH or GPG keys

Delegation

  • •Audit repository branch hygiene and stale branches: Use Explore agent to list and classify branch age and merge status
  • •Set up CI/CD pipelines with reusable workflows: Use Task agent to create modular GitHub Actions configurations
  • •Design branching strategy for a new project: Use Plan agent to evaluate trunk-based vs Git Flow based on team needs

References