# Git Workflow Design

> Skill — Git Workflow Design

- Skill: `sairam0424/git-workflow-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sairam0424/git-workflow-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sairam0424/git-workflow-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: sairam0424 (https://skillmd.com/u/sairam0424)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sairam0424/git-workflow-design

---


# Skill — Git Workflow Design

## When this skill activates
Any task involving git branching strategies, merge policies, commit standards,
release workflows, or repository governance.

## Mandatory actions when this skill is active

### Before recommending a workflow
1. Assess team size and release cadence.
2. Identify deployment model (continuous vs scheduled releases).
3. Consider CI/CD maturity and test coverage levels.

### Trunk-Based Development

**Characteristics:**
- Main branch is always deployable.
- Short-lived feature branches (< 2 days).
- CI runs on every commit to main.
- Feature flags for incomplete work.

**Best for:** small-to-medium teams, continuous deployment, high CI maturity.

**Rules:**
- Branch from main, merge back to main.
- No long-lived branches (except main).
- Feature flags decouple deploy from release.
- Revert fast if main breaks — don't "fix forward" under pressure.

### GitFlow

**Characteristics:**
- develop branch for integration.
- release/* branches for stabilization.
- hotfix/* branches from main for urgent fixes.
- Longer release cycles (weekly/monthly).

**Best for:** teams with scheduled releases, multiple versions in production, regulatory requirements.

**Rules:**
- Feature branches from develop.
- Release branch cut when ready — only bug fixes after cut.
- Hotfix from main, merge back to both main AND develop.
- Tag every release on main.

### Merge strategies

**Squash merge:**
- Produces clean, linear history on main.
- One commit per PR — easy to revert entire features.
- Loses granular commit history from the branch.
- Best for: feature branches with messy/WIP commits.

**Rebase merge:**
- Linear history, preserves individual commits.
- Requires clean, meaningful commits on the branch.
- Best for: teams that enforce atomic commits.

**Merge commit:**
- Preserves branch topology (merge bubbles visible).
- Easy to see "this group of commits was one PR."
- Best for: teams that value traceability over linearity.

### Branch naming conventions

**Format:** `type/ticket-description`

**Examples:**
- `feat/PROJ-123-add-oauth-login`
- `fix/PROJ-456-null-pointer-checkout`
- `chore/upgrade-react-19`
- `hotfix/payment-timeout`

**Rules:**
- Lowercase, hyphen-separated.
- Include ticket number when applicable.
- Keep descriptions short but meaningful.
- No personal names or dates in branch names.

### Protected branch rules

- **Require pull request** — no direct pushes to main/develop.
- **Require CI pass** — all status checks green before merge.
- **Require review** — at least 1 approval (2 for critical paths).
- **Require up-to-date branch** — must be rebased on latest main.
- **Restrict force-push** — disabled on main, develop, release/*.
- **Require signed commits** — for regulated environments.

### Merge queue

- Batches multiple approved PRs together.
- Tests the combined result before merging.
- Automatically reverts PRs that break the batch.
- Prevents "works individually, breaks together" scenarios.
- Available: GitHub merge queue, Mergify, Bors.

### Commit standards

**Conventional Commits format:**
```
type(scope): description

[optional body]

[optional footer]
```

**Types:** feat, fix, refactor, docs, test, chore, perf, ci, build, revert.

**Rules:**
- Subject line < 72 characters.
- Imperative mood ("add" not "added").
- Body explains WHY, not WHAT (the diff shows what).
- Footer for breaking changes: `BREAKING CHANGE: description`.
- Enforce with commitlint + husky pre-commit hook.

## Self-check before task completion
- [ ] Did I follow the mandatory actions for this skill?
- [ ] Did I apply the patterns appropriate to the context?
- [ ] Did I verify the implementation meets the criteria above?
- [ ] Did I document decisions and trade-offs made?