GitHub Actions skill for Claude Code

A good workflow runs only when relevant files change, cancels superseded runs, restores caches so the warm path is fast, uses a read-only token by default, authenticates to clouds with OIDC instead of stored keys, and passes actionlint and a security lint.

Ground rules

• Top-level permissions: contents: read; grant more per job only where needed.
• Pin third-party actions to a full commit SHA with the version in a comment, and let Dependabot update them. Examples below show tags for readability only.
• Never interpolate ${{ github.event.* }} user-controlled fields directly into run:; pass them through env:.
• Cloud credentials come from OIDC (id-token: write), not long-lived secrets.
• Deploy jobs run in a GitHub Environment with required reviewers for production.
• Every job sets timeout-minutes.

Workflow

- [ ] 1. Read existing workflows and recent run times (gh run list)
- [ ] 2. Define triggers, path filters, concurrency
- [ ] 3. Set permissions per job
- [ ] 4. Add caching and parallelism (matrix, job split)
- [ ] 5. Extract repetition into reusable workflows / composite actions
- [ ] 6. Wire deploys via OIDC + environments
- [ ] 7. Lint (actionlint, zizmor), run, and compare timings

1. Inspect

ls .github/workflows/
gh run list --limit 20 --json name,conclusion,createdAt,updatedAt,event
gh run view <run-id> --log-failed
gh workflow run ci.yml --ref my-branch     # if it has workflow_dispatch

2–4. Baseline CI workflow

name: ci
on:
  pull_request:
    paths-ignore: ["docs/**", "**/*.md"]
  push:
    branches: [main]
  merge_group:
  workflow_dispatch:

permissions:
  contents: read

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

jobs:
  test:
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        node: [20, 22, 24]
        include:
          - node: 22
            coverage: true
    steps:
      - uses: actions/checkout@v5
        with:
          persist-credentials: false
      - uses: actions/setup-node@v5
        with:
          node-version: ${{ matrix.node }}
          cache: npm
      - run: npm ci
      - run: npm test -- ${{ matrix.coverage && '--coverage' || '' }}
      - if: matrix.coverage
        uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage/
          retention-days: 7

Caching decisions:

Stack	Cache
npm / pnpm / yarn	setup-node with cache: (caches the package store, not node_modules)
Python pip / uv	setup-python with cache: pip; astral-sh/setup-uv with enable-cache: true
Go	setup-go caches modules and build cache by default
Gradle / Maven	setup-java cache: or gradle/actions/setup-gradle
Custom (tool binaries, build outputs)	actions/cache keyed on hashFiles(...) with restore-keys fallback
Docker images	docker/build-push-action with cache-from: type=gha and cache-to: type=gha,mode=max

Speed levers in order: skip irrelevant runs (paths, concurrency) -> cache -> split slow jobs and run them in parallel -> shard tests via matrix -> larger runners.

5. Reuse

Reusable workflow (whole jobs) — .github/workflows/deploy.yml:

on:
  workflow_call:
    inputs:
      environment: { type: string, required: true }
    secrets:
      SLACK_WEBHOOK: { required: false }

Caller:

jobs:
  deploy-staging:
    uses: ./.github/workflows/deploy.yml
    with: { environment: staging }
    secrets: inherit

Composite action (shared steps) lives in .github/actions/<name>/action.yml with runs: using: composite; every run step there needs an explicit shell: bash.

Need	Use
Share steps within jobs	Composite action
Share entire jobs with their own runners, environments, permissions	Reusable workflow
Share across repos	Either, referenced as org/repo/path@<sha>

6. Deploy with OIDC

jobs:
  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    environment: production
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v5
        with: { persist-credentials: false }
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/gha-deploy-prod
          aws-region: eu-west-1
      - run: ./scripts/deploy.sh

The IAM role trust policy must restrict the subject, e.g. "token.actions.githubusercontent.com:sub": "repo:acme/shop:environment:production" with aud = sts.amazonaws.com. A trust policy matching only the org (repo:acme/*) lets any repo’s workflow assume the role. GCP uses google-github-actions/auth with a Workload Identity Provider; Azure uses azure/login with federated credentials.

7. Lint and verify

actionlint                         # syntax, expressions, shellcheck on run: blocks
zizmor .github/workflows/          # security audit: injection, excessive permissions, unpinned actions
gh run watch                       # follow the triggered run

Compare total and per-job duration before and after on the same kind of event; report the warm-cache time, not the first run.

Security essentials

Read references/security-hardening.md before touching workflows that use pull_request_target, workflow_run, self-hosted runners, or that publish packages/releases. The short list:

• Script injection: unsafe run: echo "${{ github.event.pull_request.title }}"; safe env: { TITLE: "${{ github.event.pull_request.title }}" } then "$TITLE".
• pull_request_target runs with secrets and a write token in the context of the base repo. Never check out and execute the PR’s head code in it.
• persist-credentials: false on checkout unless a later step must push.
• Secrets are not passed to workflows triggered from forks; design fork CI to need none.

Useful expressions and files

- id: meta
  run: echo "version=$(jq -r .version package.json)" >> "$GITHUB_OUTPUT"
- run: echo "Deployed ${{ steps.meta.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
- if: failure() && github.ref == 'refs/heads/main'
  run: ./scripts/notify-failure.sh
- if: contains(github.event.pull_request.labels.*.name, 'run-e2e')
  run: npm run e2e

Gotchas

• paths/paths-ignore on a workflow used as a required status check leaves the check pending forever when skipped; use a job-level filter (e.g. a changes job) or make an always-running summary job the required check.
• cancel-in-progress: true on main pushes can cancel a deploy midway; scope it to PRs.
• Cache keys without the OS or lockfile hash restore incompatible caches.
• Artifacts v4 names must be unique per run; matrix jobs need name: cov-${{ matrix.node }}.
• schedule runs only on the default branch and is disabled after 60 days of repo inactivity.
• Workflows changed in a PR from a fork do not get secrets; test secret-dependent logic on a branch in the main repo.
• GITHUB_TOKEN pushes do not trigger other workflows (by design); use a GitHub App token if a chained trigger is required.
• ubuntu-latest moves to new images over time; pin ubuntu-24.04 when reproducibility matters.

Output

**Workflows changed:** ci.yml (rewritten), deploy.yml (new reusable)
**Permissions:** default contents:read; deploy job adds id-token:write
**Caching:** npm via setup-node, Docker via gha cache
**Timing (warm, PR):** 11m40s -> 4m05s (lint and test parallel, 3-way test shard)
**Security:** actionlint clean, zizmor 0 findings, all actions SHA-pinned, no AWS keys in secrets