/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. |