maintain-ci

Maintain GitHub Actions CI

Companion Guidance

Use karpathy-guidelines alongside this skill for implementation or review work. Keep changes scoped, surface assumptions, and define focused validation before editing.

Use this skill when a change touches .github/workflows/*.yml or .github/workflows/*.yaml, or when reviewing CI behavior for security, reliability, or reproducibility.

Standards

• Put permissions: on each job that needs token access.
• Avoid workflow-level permissions unless the repository intentionally centralizes them and the inheritance tradeoff is documented.
• Keep third-party actions pinned to full commit SHAs and preserve the readable version comment after the SHA.
• Prefer action-native or ecosystem-native caching over generic actions/cache.
• Use lockfiles or dependency manifests to drive cache invalidation.
• Keep deploy and publish permissions isolated to the jobs that need them.
• Publish the TypeScript contract from the dedicated publish_typescript.yml workflow through the protected npmjs environment. Grant id-token: write for npm trusted publishing, and do not provide an npm write token that could mask an OIDC configuration failure.
• Read both caller and callee when a workflow uses workflow_call.
• Keep documentation publish and preview credentials isolated to the Fern docs workflow.
• Keep local commands aligned with the corresponding justfile recipes when they provide equivalent behavior.
• Keep tag filters, prerelease normalization, and publication behavior aligned with RELEASING.md.

Permission Model

• contents: read is the default minimum for checkout-based build, test, docs, and packaging jobs.
• pull-requests: read is required for PR metadata lookup jobs.
• pages: write should be limited to Pages deployment jobs and any caller that invokes them through a reusable workflow.
• id-token: write should be limited to jobs that exchange a GitHub OIDC token with a protected deployment target, including Pages deployment and the protected npm publication job.
• For reusable workflows, the caller must grant every permission the called jobs require. The callee cannot elevate beyond what the caller provides.

Caching

• Prefer astral-sh/setup-uv cache support with cache-dependency-glob anchored to uv.lock.
• Prefer Swatinem/rust-cache with explicit shared-key and workspaces instead of ad hoc target-directory caching.
• Avoid caching generated outputs that can hide stale behavior unless the repo already relies on them deliberately.

Review Checklist

• Each job has the minimum permissions it needs
• Reusable workflow callers grant only the scopes their callees require
• Every external action is pinned to a full SHA
• Cache settings are tied to lockfiles, manifests, or explicit tool versions
• Secrets are only passed to the jobs that consume them
• Python, Rust, and documentation jobs remain aligned with their lockfiles and justfile recipes
• Concurrency, branch filters, and documentation publish guards still reflect repository intent

Validation

Start with the narrowest useful checks:

just --fmt --check

Use ripgrep to inspect the workflow graph before editing:

rg -n "uses:|permissions:|secrets:|concurrency:|cache|just " .github/workflows

If local lint passes but the question is whether GitHub will authorize the run, inspect GitHub's permission model and the upstream action or reusable workflow source instead of assuming local success proves remote success.

Canonical References

• .github/workflows/ci_python.yml
• .github/workflows/ci_rust.yml
• .github/workflows/fern-docs.yml
• .github/workflows/nightly-alpha-tag.yml
• .github/workflows/publish_rust.yml
• .github/workflows/publish_typescript.yml
• scripts/ci/publish_typescript_package.py
• .gitlab-ci.yml
• RELEASING.md
• Cargo.lock
• uv.lock
• docs/package-lock.json
• justfile
• maintain-packaging
• validate-change