github-manager

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.
- **Receipts are delivery evidence.** Both CI and an explicitly approved controlled
  runner must retain candidate/artifact-bound commands, results and provenance. A green
  label or local success claim alone does not establish release readiness.
- **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

Resolve the approved release ADR and profile first. The following CI layout is the
default recommendation; audit and configure the mode the team actually approved.
Do not silently reinstate retired CI, substitute a runner during an outage, or treat
local execution as equivalent without review of the required evidence.

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

- In `tag-ci` mode, version tags trigger CI builds. Promotion needs its own evidence
  and release-owner approval boundary, even if the same tag starts that pipeline.
- In `approved-alternative` mode, follow the ADR's trigger and controlled executor.
  Validate the same candidate/artifact, review, rollback and observation requirements.
- Reconcile the effective pipeline with the profile; invoke `release-manager` and its
  [structural contract check](../operating-model-bootstrap/references/release-contract.md).
- Verify version/changelog alignment and protect tags with tag rules, not merely branch
  protection. Neither a label nor a successful build authorises deployment.

## 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 substitute an unapproved build path.** Reproducibility and provenance must
  be demonstrated for the declared executor, whether hosted or locally controlled.

## 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" | The approved mode and evidence requirements decide whether that executor is allowed. |

From jpantsjoha/ai-native-developer-experience, Apache-2.0.

More from jpantsjoha/ai-native-developer-experience