Git Workflow

Branch model

main          ← production gate; auto-deploys :prod image
  └── feat/*, fix/*, chore/* ← short-lived work branches

Rules:

• main is protected — no direct push
• Feature branches merge into main via PR
• Solo dev exception: feature branches may merge directly to main without a PR

Aspirational: develop branch

A develop staging gate is planned but not yet wired up in CI. Woodpecker only triggers on main. Until a staging pipeline is added, feature branches cut from and merge back to main directly.

---

Branch naming

{type}/{short-description}

Type	Use
feature/	New functionality
fix/	Bug fixes
chore/	Tooling, deps, config
docs/	Documentation only
refactor/	Code restructure without behaviour change
perf/	Performance work

Keep slugs lowercase, hyphen-separated, under 40 characters.

Examples:

• feature/woodpecker-agent-taxonomy
• fix/docker-widget-auth
• chore/update-dependencies

---

Commit message format

<type>: <description>

<optional body — explain WHY, not what>

Types: feat, fix, refactor, docs, test, chore, perf, ci

Rules:

• First line ≤ 72 characters
• Imperative mood: “add”, “fix”, “remove” — not “added”, “fixes”
• No trailing period
• Body separated from subject by blank line
• Body explains motivation / context, not mechanics

Examples:

feat: add Woodpecker agent persistent config volume

Without a named volume at /etc/woodpecker, the agent re-registers
as a new identity on every container restart, creating ghost entries
in the admin UI.

fix: correct docker widget session guard

The widget was returning data before auth() resolved;
wrap the handler so 401 is returned on missing session.

---

Solo dev workflow

For single-developer projects, the flow is:

1. Cut a feature branch from main
2. Implement and commit
3. Open a PR from feature/xyz → main as the prod gate
4. Merge — CI runs checks, smoke, build, and deploy automatically

The PR exists for: diff review before prod, audit trail, rollback reference point.

---

Tagging and releases

Tags are applied to main after merge. Format: v{major}.{minor}.{patch} (semver).

git tag -a v1.3.0 -m "Phase 1C: badges and cosmetics"
git push origin v1.3.0

Increment	Trigger
patch	Bug fixes, no schema changes
minor	New features, backwards-compatible schema changes
major	Breaking changes, major architectural shifts

---

.gitignore standards

Every project must gitignore:

.env
.env.*
!.env.example
*.local
node_modules/
dist/
.tmp/

Scratch files and temporary snippets go in .tmp/ — never in src/, scripts/, or project root.

---

Commit attribution

CI commits (automated, from pipeline scripts):

Co-Authored-By: Woodpecker CI <ci@level147.net>

Claude Code-assisted commits: no co-author attribution (disabled globally in ~/.claude/settings.json).