---
name: github-actions-ci
description: Writes and fixes GitHub Actions workflows: triggers, caching, matrix builds, concurrency, least-privilege permissions, secrets, SHA-pinned actions, and log-based debugging. Use when the user adds, edits or debugs a CI workflow or a failing GitHub Actions run.
---

# GitHub Actions CI

Create or repair workflows in `.github/workflows/`. Keep them fast, deterministic and least-privilege. Read the existing workflows and the project's build/test commands first; reuse the commands developers already run locally.

## Workflow for a new or changed pipeline

1. Find the real commands: `package.json` scripts, `Makefile`, `pyproject.toml`, `tox.ini`. The CI should call the same commands.
2. Choose triggers deliberately (see below).
3. Write the smallest workflow that builds and tests. Add caching, matrix and extras only when they pay off.
4. Validate the YAML (`actionlint` if installed, otherwise a YAML parser) before pushing.
5. Do not push or open a PR without the user's go-ahead; report what to look at in the first run.

## Skeleton

```yaml
name: ci
on:
  pull_request:
  push:
    branches: [main]

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@<full-commit-sha> # v4.x.x
      - uses: actions/setup-node@<full-commit-sha> # v4.x.x
        with:
          node-version-file: .nvmrc
          cache: npm
      - run: npm ci
      - run: npm test
```

Look up the current commit SHA of each action's release tag; never invent one.

## Rules

### Triggers
- `pull_request` for checks on contributions; `push` to the default branch for post-merge work; `workflow_dispatch` for manual runs; `schedule` for nightly jobs.
- Use `paths:` / `paths-ignore:` to skip unrelated changes, but remember required checks that are skipped can block merging.
- Never use `pull_request_target` to run code from a fork. It runs with secrets and write access.

### Permissions
- Set top-level `permissions: contents: read` and widen per job only where needed (`pull-requests: write`, `packages: write`, `id-token: write`).
- Prefer OIDC (`id-token: write`) with a cloud role over long-lived cloud keys in secrets.

### Pinning actions
- Pin third-party actions to a full commit SHA with the version in a trailing comment. Tags can be moved by the action's owner.
- First-party `actions/*` may use a version tag if the team accepts that; say which policy you applied.
- Enable Dependabot/Renovate for `github-actions` so pins get updated.

### Caching
- Use the built-in `cache:` of the setup actions (npm, pip, gradle, go) keyed on the lock file.
- For custom caches use `actions/cache` with a key containing `hashFiles('**/lockfile')` and a `restore-keys` fallback.
- Never cache secrets, `.env` files or credentials.

### Matrix
- Use `strategy.matrix` for language versions or OS only when the project supports them. Set `fail-fast: false` when you want all results.
- Keep the matrix small; every cell costs minutes.

### Concurrency and cost
- Use a `concurrency` group so new pushes cancel stale PR runs. Do not cancel deploy jobs on the default branch.
- Set `timeout-minutes` on every job to avoid six-hour hangs.

### Secrets
- Reference secrets only through `${{ secrets.NAME }}` in `env:` of the step that needs them, not at workflow level.
- Never `echo` a secret or run with `set -x` around it. Never pass secrets in command-line arguments when an env var works.
- Secrets are not available to workflows from forks; design the check so it still passes without them or is skipped clearly.
- Untrusted input (`github.event.pull_request.title`, branch names) must not be interpolated directly into `run:`. Pass it through `env:` and quote it.

## Debugging a failing run

```bash
gh run list --limit 5
gh run view <run-id> --log-failed
gh run view <run-id> --json jobs --jq '.jobs[] | select(.conclusion=="failure") | .name'
gh run rerun <run-id> --failed      # only after the user agrees
```

1. Read the first real error in the failed step, not the last line of the log.
2. Decide: code bug, flaky test, environment difference (OS, Node/Python version, missing env var), cache poisoning, or permissions.
3. Reproduce locally with the same command and versions when possible.
4. For cache suspicion, change the cache key once and rerun rather than guessing.

## Output format

Report: the workflow files changed, what each change does and why, how it was validated (linter, local run), and the risks (for example "requires repository setting X" or "pins need SHAs verified").

## Pitfalls

- Do not add `continue-on-error: true` to hide a failure.
- Do not disable or delete tests to make CI green.
- Do not grant `write-all` permissions to fix a 403; find the one permission needed.
- `ubuntu-latest` changes over time; pin a version (`ubuntu-24.04`) if reproducibility matters.
- YAML gotchas: unquoted `on`, versions like `3.10` parsed as `3.1`; quote versions.

Source: [AnyModel skills catalog](https://anymodel.org/en/skills) · License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
