Gh Setup

GitHub Setup

Make GitHub the enforceable shell around the repository's existing build, verification, release, and deployment contracts.

Inspect and Classify

Before changing files or live settings:

1. Read repository guidance, manifests, verification commands, release or deploy scripts, .github/, contributor/security docs, and any repository-owned delivery runbook.
2. Read live GitHub state: default branch, merge methods, effective branch rules, Actions policy, Environments, protected tags, security settings, and every human or automated default-branch writer affected by the change.
3. Record the relevant before-state and rollback path.
4. Classify the delivery shape:
   • Versioned artifact: read release workflows and only the matching section of publish targets.
   • Running app or service: read deploy workflows, then Environments or credentials when those boundaries change.
   • Both: publish one immutable payload, then deploy that payload instead of rebuilding it.

Use repo-local commands as authority. If the repository cannot reproducibly build, verify, package, observe, or roll back the claimed surface, report that prerequisite instead of hiding it in workflow YAML.

Shared Contract

• Pull requests execute untrusted code with read-only credentials.
• Trusted release and deploy jobs load credentials only after verification and input or ref validation.
• Workflow permissions default to read-only or {} and widen per job.
• High-trust remote Actions use reviewed immutable pins with an update path.
• Environment secrets and policy match the release or deployment blast radius.
• Release, publish, signing, promotion, and deploy critical sections are non-cancellable and reconcilable.
• One verified payload crosses build, test, publish, and deploy boundaries.
• Required checks use a stable final result when matrices, conditional lanes, or no-op paths make individual jobs unstable.
• A green workflow is not completion until live settings and downstream state are read back.

Read Actions security before workflows execute project code, load secrets, publish, sign, or deploy.

Runner Cost

Runner minutes are billed compute. Every trigger, runner size, and rerun is a cost decision; default to the cheapest shape that still proves the contract.

• Follow the target owner's runner policy. Compare live pricing, included minutes, repository visibility, and runner availability before choosing a provider or size. Preserve each job's required OS and architecture; reusable workflows must support the caller's policy and platform needs.
• Use Linux for portable checks. macOS and other large runners are reserved for platform-bound jobs (native apps, Darwin-only APIs, Homebrew taps) and must be gated behind path filters or restricted to pull_request + workflow_dispatch. Runner changes preserve required proof, scan coverage, triggers, permissions, and Environments.
• Provider requirements still apply to private repositories: npm trusted publishing requires GitHub-hosted runners; use the npm publish contract.
• Secret and history scans trigger on pull_request, a weekly schedule, and workflow_dispatch — never on push. The merge commit's tree was already scanned in the pull request; the weekly cron covers history and new detector rules. Reuse the target owner’s shared scanning workflow when available; keep its reference consistent with the repository’s pinning policy. Avoid copying scanner jobs or building scanner images per run.
• Every verification workflow declares workflow-level concurrency: group: ${{ github.workflow }}-${{ github.ref }}, cancel-in-progress: ${{ github.event_name == 'pull_request' }}. Release, publish, and deploy critical sections keep their own non-cancellable keys.
• A workflow triggered on both push: [main] and pull_request pays twice per merged change. Keep push-to-main lanes for release/deploy work and for repos whose policy allows direct pushes; do not add a push trigger to re-verify a tree a required PR check already verified.
• Jitter cron minutes away from :00/:30; weekly is the default scan cadence.
• Expensive-per-run jobs (simulators, cross-compiles, e2e) sit behind dorny/paths-filter lanes or workflow_dispatch, with an always() result job when branch protection needs a stable check.
• Watch failure rates: a workflow that fails half its runs bills full minutes for red. Fix or gate flaky jobs instead of rerunning them.

When implementing rather than only auditing, read maintained implementations and start from the closest tested shape. Reuse its contract, not its literal versions, identities, or provider details.

Repository Policy

Read repository settings for merge methods, rulesets, required checks, signed commits, tags, Actions policy, Environments, the cost-safe organization security baseline, CodeQL posture, and repository metadata.

Preserve existing approval, actor, signed-commit, tag, and status-check rules unless the requested change owns them. Running a check and enforcing it are separate operations. Before requiring pull requests or a check, inventory release bots, dependency bots, generated writebacks, and maintainers who still write the default branch.

Do not require pull requests by default. When repository policy permits direct updates and a reproducible local gate is mirrored by default-branch CI, allow verified fast-forward pushes. Require pull requests only for pre-merge review, untrusted contributions, merge queues, checks that must pass before the default branch moves, or an explicit owner policy. Post-push CI detects regressions after the branch moves, so run the local gate before pushing and monitor CI to completion.

Collaboration Files

Read templates when adding or aligning pull-request templates, issue forms, SECURITY.md, CONTRIBUTING.md, or shared community defaults.

• Prefer public owner-level defaults only for policy true across every repo.
• Keep templates short and evidence-oriented; avoid checklist theater.
• Public security guidance needs a working private reporting route. Private repos use an existing private maintainer channel.
• Read dependency updates before adding or migrating Dependabot or Renovate. Run one bot per repository; keep security updates on under either.

Release and Deploy Routes

Release work uses:

• release workflows for trust, publication, signed writeback, immutable releases, recovery, and completion proof
• publish targets for npm, Swift/CocoaPods, Go, Rust, GitHub Actions, Homebrew, and monorepos
• semantic-release only when that tool is selected
• release troubleshooting only after a concrete failure or inconsistent durable state

Deploy work uses:

• deploy workflows for triggers, lane detection, verified payloads, concurrency, and monitoring handoff
• Environments when target selection, protection, OIDC, or provider boundaries change
• credentials when secret ownership or logging changes
• deploy troubleshooting only after a concrete failure

Verify and Finish

Run repository gates plus actionlint and zizmor when workflows changed. Perform the narrowest safe live proof of the delivery contract. Dry-runs and static inspection cannot prove immutable publication, signed writeback, registry or tap parity, deployment, monitoring, or rollback.

After authorized live changes, read back every setting, Environment, rule, release, registry, tag, deployment, or downstream pointer in scope. On partial failure, reconcile durable state before retrying; never create a new version or mutate an immutable release merely to make a workflow green.

Output

files: changed GitHub and documentation surfaces
settings: live changes and readback, or not checked
delivery: target and immutable payload boundary
evidence: local, workflow, and live proof actually exercised
risks: remaining authority, recovery, or downstream gaps