Github Manager

---
name: github-manager
description: Use when configuring or optimising GitHub repositories for cost-effective, consistent operations — CI triggers, Actions billing, issue tracking, labelling, branch protection, or release workflow.
---

# GitHub Manager

> **CI validates what cannot be cheaply verified locally. It is not a remote test runner for every commit.**

This skill enforces disciplined, cost-aware GitHub operations. It turns GitHub from a free-for-all into a governed delivery surface: selective automation, traceable issues, consistent labels, and protected mainlines.

## When to use

- Setting up or revising a repository's CI/CD workflow
- Investigating unexpected GitHub Actions spend
- Creating or triaging issues and defining acceptance criteria
- Designing a label taxonomy or branch-protection policy
- Preparing a release process or tag strategy

## Operating model context

This skill governs the GitHub surfaces that enforce the harness contract at the repository
level. It is not general DevOps housekeeping — each procedure below maps to a harness
invariant:

- **Branch protection + required status checks** are the enforcement mechanism for the
  PR review gate and the exact-candidate binding rule. A CI check that passes on an
  unprotected branch is a claim; a passing check required by branch rules is evidence.
- **CI receipts are delivery evidence.** "It worked locally" is not an artefact. A CI
  run tied to a commit SHA is. Structure your workflow so evidence is machine-readable
  and SHA-bound, not dependent on a contributor's local environment.
- **Modifying branch protection, CI pipelines, or billing settings is an R2 action.**
  These changes affect all contributors and shared infrastructure. Classify risk, confirm
  authority, and record the decision before any write.

Use `release-readiness` to gate a specific deployment. Use this skill to configure and
audit the repository surfaces that make those gates trustworthy.

## Procedure

### 1. Rightsize CI triggers

- **Push to default branches** should run lightweight gates only (lint, typecheck, unit tests).
- **Pull requests and version tags** run the full pipeline, including packaging and cross-platform smoke tests.
- **Feature branches** do not fire CI on every push; open a PR when ready for validation.
- **Path filters** skip irrelevant jobs: docs-only changes should not rebuild the extension, code-only changes should not re-render documentation.

### 2. Minimise Actions billing

- Know the runner multipliers: Linux ×1, Windows ×2, **macOS ×10**.
- Gate expensive runners (macOS, Windows) behind PRs and releases, not every push.
- Cache dependency stores (`cache: 'pnpm'`, `cache: 'npm'`, pip, etc.).
- Do not run local-integration or exploratory tests in CI; keep them local or on-demand.
- Set a spending limit and billing alert before usage surprises you.

### 3. Structure issues and tracking

- Every issue states a **problem or outcome** and has **acceptance criteria**.
- Link PRs to issues (`Closes #123` or `Refs #123`).
- Close issues with a concise note explaining what changed and where.
- Use milestones or projects for release-scope tracking, not long-lived catch-all issues.

### 4. Label consistently

Adopt a namespaced taxonomy and avoid one-off labels:

| Namespace | Examples | Purpose |
|---|---|---|
| `kind/` | `kind/bug`, `kind/feature`, `kind/docs` | Type of work |
| `area/` | `area/ci`, `area/ui`, `area/security` | Component or domain |
| `priority/` | `priority/p0`, `priority/p1` | Triage urgency |
| `status/` | `status/blocked`, `status/needs-review` | Workflow state |

### 5. Protect the mainline

- Require PR reviews before merging to `main`.
- Require status checks to pass (lint, typecheck, test).
- Use squash or rebase merges for a linear history; avoid merge commits unless the project explicitly allows them.
- Restrict force-push and deletion on default branches.

### 6. Define the release workflow

- Tags (`v*`) trigger release builds and deployments, not manual uploads.
- A release checklist verifies version alignment, changelog entry, and rollback plan.
- Generated artifacts (VSIX, containers, packages) are produced by CI, not a local workstation.

## Outputs

- CI trigger matrix: event → jobs that run
- Monthly Actions cost estimate with runner-multiplier breakdown
- Issue template with acceptance criteria
- Label taxonomy
- Branch-protection policy
- Release checklist

## Guardrails

- **Local testing is not CI.** If a check belongs on a developer's machine, do not run it on every push.
- **macOS minutes are the silent budget killer.** A one-minute macOS job costs ten billable minutes.
- **Unconditional full pipelines scale badly.** Every unconditional job is a tax on every future commit.
- **Labels without a taxonomy become noise.** Delete or consolidate labels that do not fit the scheme.
- **Never deploy from a local build.** Release artifacts must come from CI to be reproducible.

## Anti-rationalization table

| Excuse | Counter |
|---|---|
| "Run everything on every push to be safe" | Safety is selective gates, not redundant burn. Run full checks on PRs and tags. |
| "It's only a few CI minutes" | At 10× for macOS, "a few minutes" becomes hundreds of dollars per cycle. |
| "We'll clean up labels later" | Label debt compounds fast and breaks automation that depends on them. |
| "Force-push is fine, we're a small team" | Force-push on `main` destroys recovery options. Protect the branch. |
| "I'll build the release artifact locally" | Local builds are not reproducible or auditable. CI produces release artifacts. |