# Github Operations

> **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).

- Skill: `jonathan-vella/github-operations` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add jonathan-vella/github-operations`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jonathan-vella/github-operations/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: jonathan-vella (https://skillmd.com/u/jonathan-vella)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jonathan-vella/github-operations

---


# 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

```text
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

1. **Identify the operation** (issue, PR, search, Actions, release, etc.)
2. **Use `gh` CLI by default** — always available in this dev container; the more stable primitive
3. **Fall back to MCP only** when `gh` cannot satisfy the operation (rich PR review threads, bulk GraphQL, Copilot review requests)
4. **Validate branch name before any commit or PR** — `git rev-parse --abbrev-ref HEAD`; if invalid, stop and rename via `git branch -m`
5. **Conventional Commits are mandatory** — enforced by commitlint
6. **Devcontainer**: do not run `gh auth login`; `GH_TOKEN` is set via VS Code User Settings (`terminal.integrated.env.linux`)
7. **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`](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`](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`](references/issues-and-prs.md).
For PR lifecycle states, auto-labels, and auto-merge conditions, read
[`references/smart-pr-flow.md`](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`](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`](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        |