GitHub Operations
Full contribution lifecycle — from branch creation to PR merge.
gh CLI preferred (always available in this dev container); MCP tools as
fallback for operations with no gh equivalent (rich PR review thread
management, bulk GraphQL queries).
Steps
1. Create branch (naming convention) →
2. Make changes →
3. Commit (conventional commits) →
4. Push (pre-push hooks validate branch + scope) →
5. Create PR (gh CLI) →
6. Review + Merge
Rules
- Identify the operation (issue, PR, search, Actions, release, etc.)
- Use
gh CLI by default — always available in this dev container; the more stable primitive
- Fall back to MCP only when
gh cannot satisfy the operation (rich PR review threads, bulk GraphQL, Copilot review requests)
- Validate branch name before any commit or PR —
git rev-parse --abbrev-ref HEAD; if invalid, stop and rename via git branch -m
- Conventional Commits are mandatory — enforced by commitlint
- Devcontainer: do not run
gh auth login; GH_TOKEN is set via VS Code User Settings (terminal.integrated.env.linux)
- Never skip hooks (
--no-verify) unless the user explicitly asks
Branch Naming Quick Reference
| Type |
Prefixes |
File Scope |
| Domain-scoped |
docs/, agents/, skills/, infra/, scripts/, instructions/ |
Restricted to domain paths |
| Cross-cutting |
feat/, fix/, chore/, ci/, refactor/, perf/, test/, build/, revert/ |
Any files |
For scope tables, validation commands, and enforcement layers, read
references/branch-strategy.md.
Conventional Commits Quick Reference
Format: <type>[optional scope]: <description>.
Types: feat, fix, docs, refactor, perf, test, build, ci,
chore, revert.
Scopes: agents, skills, instructions, bicep, terraform, mcp,
docs, scripts.
For staging, breaking changes, and safety protocol, read
references/commit-conventions.md.
Issues & Pull Requests
gh issue ... and gh pr ... are the default for both. MCP tools are
available as a fallback for operations the CLI does not cover well (rich
PR review threads, Copilot review requests, bulk GraphQL).
Default merge method: squash unless the user specifies otherwise.
For tool tables, creation pre-flight checks, and the gh-vs-MCP decision
lattice, read references/issues-and-prs.md.
For PR lifecycle states, auto-labels, and auto-merge conditions, read
references/smart-pr-flow.md.
CLI Commands
For complete gh CLI commands covering repos, Actions, releases, secrets,
API, and auth, read
references/detailed-commands.md.
IMPORTANT: gh api -f does not support object values. Use multiple
-f flags with hierarchical keys and string values instead.
Global Flags
| Flag |
Description |
--repo OWNER/REPO |
Target specific repository |
--json FIELDS |
Output JSON with fields |
--jq EXPRESSION |
Filter JSON output |
--web |
Open in browser |
--paginate |
Fetch all pages |
Smart PR Flow Quick Reference
| Condition |
Label Applied |
| CI passes |
infraops-ci-pass |
| CI fails |
infraops-needs-fix |
| Review approved |
infraops-reviewed |
| Auto-merge (all gates pass) |
PR merged via MCP |
Full state machine, watchdog pattern, and auto-merge gates in
references/smart-pr-flow.md.
Reference Index
| Reference |
File |
Content |
| Branch Strategy |
references/branch-strategy.md |
Naming convention, scope tables, enforcement layers |
| Commit Conventions |
references/commit-conventions.md |
Format, types, staging workflow, safety protocol |
| Issues & PRs |
references/issues-and-prs.md |
gh-vs-MCP decision lattice, tool tables, pre-flight |
| Smart PR Flow |
references/smart-pr-flow.md |
PR lifecycle states, auto-labels, auto-merge |
| CLI Commands |
references/detailed-commands.md |
Repos, Actions, Releases, Secrets, API, Auth |
1---2name: github-operations3description: **WORKFLOW SKILL** — Full GitHub contribution lifecycle: branches, conventional commits, issues, PRs, Actions, releases. gh CLI-first with MCP fallback. WHEN: "commit", "push", "open PR", "create branch", "create issue", "cut release", "GitHub operation". DO NOT USE FOR: Azure infrastructure, Bicep/Terraform code, architecture decisions. INVOKES: gh CLI (primary), GitHub MCP (fallback).4license: MIT5---67# GitHub Operations89Full contribution lifecycle — from branch creation to PR merge.10`gh` CLI preferred (always available in this dev container); MCP tools as11fallback for operations with no `gh` equivalent (rich PR review thread12management, bulk GraphQL queries).1314## Steps1516```text171. Create branch (naming convention) →182. Make changes →193. Commit (conventional commits) →204. Push (pre-push hooks validate branch + scope) →215. Create PR (gh CLI) →226. Review + Merge23```2425## Rules26271. **Identify the operation** (issue, PR, search, Actions, release, etc.)282. **Use `gh` CLI by default** — always available in this dev container; the more stable primitive293. **Fall back to MCP only** when `gh` cannot satisfy the operation (rich PR review threads, bulk GraphQL, Copilot review requests)304. **Validate branch name before any commit or PR** — `git rev-parse --abbrev-ref HEAD`; if invalid, stop and rename via `git branch -m`315. **Conventional Commits are mandatory** — enforced by commitlint326. **Devcontainer**: do not run `gh auth login`; `GH_TOKEN` is set via VS Code User Settings (`terminal.integrated.env.linux`)337. **Never skip hooks** (`--no-verify`) unless the user explicitly asks3435## Branch Naming Quick Reference3637| Type | Prefixes | File Scope |38| ------------- | ------------------------------------------------------------------------------------ | -------------------------- |39| Domain-scoped | `docs/`, `agents/`, `skills/`, `infra/`, `scripts/`, `instructions/` | Restricted to domain paths |40| Cross-cutting | `feat/`, `fix/`, `chore/`, `ci/`, `refactor/`, `perf/`, `test/`, `build/`, `revert/` | Any files |4142For scope tables, validation commands, and enforcement layers, read43[`references/branch-strategy.md`](references/branch-strategy.md).4445## Conventional Commits Quick Reference4647Format: `<type>[optional scope]: <description>`.4849Types: `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`,50`chore`, `revert`.5152Scopes: `agents`, `skills`, `instructions`, `bicep`, `terraform`, `mcp`,53`docs`, `scripts`.5455For staging, breaking changes, and safety protocol, read56[`references/commit-conventions.md`](references/commit-conventions.md).5758## Issues & Pull Requests5960`gh issue ...` and `gh pr ...` are the default for both. MCP tools are61available as a fallback for operations the CLI does not cover well (rich62PR review threads, Copilot review requests, bulk GraphQL).6364> **Default merge method**: `squash` unless the user specifies otherwise.6566For tool tables, creation pre-flight checks, and the gh-vs-MCP decision67lattice, read [`references/issues-and-prs.md`](references/issues-and-prs.md).68For PR lifecycle states, auto-labels, and auto-merge conditions, read69[`references/smart-pr-flow.md`](references/smart-pr-flow.md).7071## CLI Commands7273For complete `gh` CLI commands covering repos, Actions, releases, secrets,74API, and auth, read75[`references/detailed-commands.md`](references/detailed-commands.md).7677> **IMPORTANT**: `gh api -f` does not support object values. Use multiple78> `-f` flags with hierarchical keys and string values instead.7980### Global Flags8182| Flag | Description |83| ------------------- | -------------------------- |84| `--repo OWNER/REPO` | Target specific repository |85| `--json FIELDS` | Output JSON with fields |86| `--jq EXPRESSION` | Filter JSON output |87| `--web` | Open in browser |88| `--paginate` | Fetch all pages |8990## Smart PR Flow Quick Reference9192| Condition | Label Applied |93| --------------------------- | -------------------- |94| CI passes | `infraops-ci-pass` |95| CI fails | `infraops-needs-fix` |96| Review approved | `infraops-reviewed` |97| Auto-merge (all gates pass) | PR merged via MCP |9899Full state machine, watchdog pattern, and auto-merge gates in100[`references/smart-pr-flow.md`](references/smart-pr-flow.md).101102## Reference Index103104| Reference | File | Content |105| ------------------ | ---------------------------------- | --------------------------------------------------- |106| Branch Strategy | `references/branch-strategy.md` | Naming convention, scope tables, enforcement layers |107| Commit Conventions | `references/commit-conventions.md` | Format, types, staging workflow, safety protocol |108| Issues & PRs | `references/issues-and-prs.md` | gh-vs-MCP decision lattice, tool tables, pre-flight |109| Smart PR Flow | `references/smart-pr-flow.md` | PR lifecycle states, auto-labels, auto-merge |110| CLI Commands | `references/detailed-commands.md` | Repos, Actions, Releases, Secrets, API, Auth |
jonathan-vella