github
Covers GitHub repository management and Git workflow governance: branching strategies (trunk-based, GitHub Flow, GitFlow), pull request and code review process, branch protection rulesets, CODEOWNERS,
SKILL.mdplugins/devops/skills/github/SKILL.md
GitHubGitHub Repository Management Expert
This skill covers GitHub repository governance — how teams organize branches, review and merge changes, and ship versioned releases. This is the process and policy layer that sits above CI/CD automation: branching models, pull request workflow, branch protection, semantic versioning, and tag-based releases. For the automation that runs on these triggers (workflows that fire on push/pull_request/release), see the github-actions skill.
How to Approach Tasks
Classify the request:
- Branching strategy — Choosing/operating a model (trunk-based, GitHub Flow, GitFlow). Load
references/branching.md. - Pull request & review process — PR lifecycle, required reviews, CODEOWNERS, status checks, merge strategy, protection/rulesets. Load
references/pull-requests.md. - Release management — SemVer, conventional commits, tagging, GitHub Releases, changelogs, hotfix flow, automation. Load
references/releases.md.
- Branching strategy — Choosing/operating a model (trunk-based, GitHub Flow, GitFlow). Load
Gather context — Team size, deploy frequency, whether the product is continuously deployed (SaaS) or shipped in discrete versions (libraries, on-prem, mobile), and existing conventions. The right answer differs sharply between a 3-person SaaS team and a versioned library with many supported releases.
Analyze — Apply the principle that the branching model, the review policy, and the release cadence must agree with each other. A team deploying 20×/day should not run GitFlow; a quarterly-shipped on-prem product should not pretend
mainis always releasable.Recommend — Concrete settings, commands, and file contents (rulesets, CODEOWNERS, commit conventions), not just principles. Show the
git/ghcommands.
Decision: Which Branching Model?
| Model | Long-lived branches | Best for | Avoid when |
|---|---|---|---|
| Trunk-based | main only (short feature branches < 1–2 days) |
High-frequency CI/CD, mature test suites, feature flags | Weak test coverage, no flag system, regulated manual QA gates |
| GitHub Flow | main + short feature branches; deploy from main |
SaaS / continuously deployed apps, small–mid teams | You must support multiple released versions simultaneously |
| GitFlow | main + develop + release/* + hotfix/* |
Versioned products: libraries, desktop/mobile apps, on-prem with scheduled releases | Continuous deployment — the ceremony is pure overhead |
| Release branches (on top of trunk/GitHub Flow) | main + release/x.y cut at release time |
You ship versions but want trunk simplicity day-to-day | Single always-latest deploy target |
Default recommendation: GitHub Flow for deployed services, trunk-based as the maturity target; GitFlow only for products with discrete, supported version lines. See references/branching.md for full diagrams and the cherry-pick/backport mechanics.
Branch Naming Convention
<type>/<short-description> feature/user-export, fix/null-pointer-login
<type>/<issue>-<description> feat/142-add-sso, bugfix/JIRA-88-timeout
release/<version> release/2.4
hotfix/<version> hotfix/2.3.1
Keep main (or main + develop) protected and authoritative. Everything else is disposable and deleted on merge.
Core Concepts
Pull Request Lifecycle
draft ──▶ ready for review ──▶ changes requested ──▶ approved ──▶ checks green ──▶ merged ──▶ branch deleted
- Draft PRs — open early for CI feedback and visibility without requesting review (
gh pr create --draft). - Small PRs — < ~400 lines changed review faster and more accurately. Split large work into stacked PRs.
- Link the issue —
Closes #142in the body auto-closes the issue on merge.
gh pr create --base main --head feat/142-add-sso \
--title "feat: add SAML SSO" \
--body "Closes #142"
gh pr view --web # open in browser
gh pr checks # watch required checks
gh pr merge --squash --delete-branch
CODEOWNERS
.github/CODEOWNERS auto-requests reviews and (with branch protection) requires owner approval for matching paths:
# Syntax: <path-pattern> <owner> [<owner>...] Last match wins.
* @org/maintainers
/infra/ @org/platform-team
/services/payments/ @org/payments @alice
*.tf @org/cloud
/docs/ @org/tech-writers
Merge Strategies
| Strategy | Result on main |
Use when |
|---|---|---|
| Squash & merge | One clean commit per PR | Default for most teams — tidy, linear history; PR title becomes the commit (pairs well with Conventional Commits) |
| Rebase & merge | Each commit replayed, no merge commit | You curate commits intentionally and want linear history with full granularity |
| Merge commit | Preserves branch + merge commit | You need the true branch topology (rare; noisy history) |
Pick one and enforce it (Settings → General → Pull Requests → allow only that option). Mixed strategies produce confusing history.
Semantic Versioning + Tags + Releases
MAJOR.MINOR.PATCH 2.4.1
│ │ └─ backward-compatible bug fixes
│ └─────── backward-compatible features
└───────────── breaking changes
pre-release / build: 2.5.0-rc.1 2.5.0+20260525
A tag marks a commit; a GitHub Release wraps a tag with notes and assets. Always use annotated tags:
git tag -a v2.4.1 -m "Release 2.4.1" # annotated (has author/date/message) — required
git push origin v2.4.1
gh release create v2.4.1 --generate-notes # auto release notes from merged PRs
gh release create v2.4.1 --notes-file CHANGELOG-2.4.1.md ./dist/*.tar.gz # with assets
Tag the merge commit on main (or on the release/* branch for GitFlow), never a feature branch.
Conventional Commits → Automated Versioning
Commit messages drive the next version and the changelog when you adopt the convention:
<type>[optional scope][!]: <description>
feat: add CSV export → MINOR bump
fix: handle null session token → PATCH bump
feat!: drop Node 18 support → MAJOR bump (! or "BREAKING CHANGE:" footer)
docs:, chore:, refactor:, test:, ci:, perf:, build: → no release
This is what tools like release-please, semantic-release, and changesets consume to compute versions, write CHANGELOG.md, tag, and create the Release — no manual version bumps. See references/releases.md.
Key Patterns
Branch Protection via Rulesets (preferred over legacy branch protection)
Rulesets are versioned, layerable, and support bypass lists. Configure in Settings → Rules → Rulesets, or as JSON via API/gh:
{
"name": "protect-main",
"target": "branch",
"enforcement": "active",
"conditions": { "ref_name": { "include": ["refs/heads/main"], "exclude": [] } },
"rules": [
{ "type": "deletion" },
{ "type": "non_fast_forward" },
{ "type": "required_linear_history" },
{ "type": "pull_request",
"parameters": {
"required_approving_review_count": 1,
"dismiss_stale_reviews_on_push": true,
"require_code_owner_review": true,
"required_review_thread_resolution": true
}
},
{ "type": "required_status_checks",
"parameters": {
"strict_required_status_checks_policy": true,
"required_status_checks": [{ "context": "build" }, { "context": "test" }]
}
}
]
}
gh api repos/:owner/:repo/rulesets --method POST --input ruleset.json
Baseline for main: require PR + ≥1 approval, require passing status checks (strict = branch up to date), block force-push and deletion, require linear history, dismiss stale approvals on new commits.
Tag-Triggered Release (handoff to CI)
The repo policy here defines when/what to tag; the build/publish runs in GitHub Actions. See the github-actions skill:
on:
push:
tags: ['v*.*.*'] # release job fires only on a semver tag
Hotfix Flow
- GitHub Flow: branch
fix/...offmain, PR, merge, tagvX.Y.Z+1, deploy. - GitFlow / release branches: branch
hotfix/2.3.1off thev2.3.0tag, fix, tagv2.3.1, then merge/cherry-pick back intomain/developso the fix isn't lost in the next release.
Anti-Patterns
- GitFlow on a continuously deployed app —
develop+release/*ceremony with nothing to gain; you deploymainconstantly. Use GitHub Flow. - Long-lived feature branches — Weeks-old branches cause merge hell. Integrate behind a feature flag instead.
- Lightweight tags for releases —
git tag v1.0(no-a) stores no author/date/message and behaves oddly withgit describe. Always annotate. - Reusing/moving a release tag — Tags must be immutable. To fix a bad release, cut a new patch version; never re-point a published tag.
- Protecting
mainbut allowing admin bypass silently — If everyone is an admin, protection is theater. Use explicit, audited bypass lists in rulesets. - Manual
versionbumps + hand-written changelogs — Drifts from reality. Drive both from Conventional Commits. - Mixed merge strategies — Squash for some PRs, merge commits for others — history becomes unreadable. Standardize one.
- Tagging a feature branch — A tag should point at the commit that actually landed on the release line.
Reference Files
references/branching.md— Branching models in depth (trunk-based, GitHub Flow, GitFlow, release branches), diagrams, backport/cherry-pick mechanics, monorepo vs polyrepo, feature-flag-driven integration.references/pull-requests.md— PR workflow, review etiquette, CODEOWNERS patterns, branch protection vs rulesets (full rule reference), required status checks, merge queue, stacked PRs, auto-merge.references/releases.md— Semantic versioning rules, Conventional Commits spec, annotated tags vs lightweight, GitHub Releases + assets, changelog generation, release automation (release-please, semantic-release, changesets), pre-releases and supported-version strategy.