Workflow

Step 1 — Complete CI + build + deploy pipeline (updated)

Notes in this template:

• Use minimal permissions and enable id-token: write when you intend to use OIDC to obtain short-lived cloud credentials (see OpenID Connect docs).
• Pin actions to full SHAs for supply-chain safety where you cannot accept tags.
• Use actions/cache@v5 (or the latest v5.x) and avoid excessive unique keys to prevent hitting the cache upload rate limit. actions/cache@v5 requires a minimum Actions Runner version (self-hosted) of 2.327.1 — update runners before upgrading. See the action repo: https://github.com/actions/cache

name: CI
on:
  push: { branches: [main] }
  pull_request: { branches: [main] }
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true
# Minimal permissions + id-token for OIDC when needed
permissions:
  contents: read
  id-token: write

jobs:
  quality:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - uses: pnpm/action-setup@fe02b34f77f8bc703a5f83169411f1f62a0633a0
      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm tsc --noEmit
      - run: pnpm test -- --coverage

  build:
    needs: quality
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - uses: pnpm/action-setup@fe02b34f77f8bc703a5f83169411f1f62a0633a0
      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - uses: actions/cache@v5
        with:
          path: .next/cache
          key: nextjs-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('**/*.ts','**/*.tsx') }}
          restore-keys: |
            nextjs-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
            nextjs-${{ runner.os }}-
      - run: pnpm build

  deploy-preview:
    needs: build
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    environment:
      name: preview
      url: "${{ steps.d.outputs.url }}"
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - id: d
        run: |
          URL=$(npx vercel deploy --token=${{ secrets.VERCEL_TOKEN }})
          echo "url=$URL" >> "$GITHUB_OUTPUT"

  deploy-prod:
    needs: build
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: { name: production, url: "https://example.com" }
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - run: npx vercel deploy --prod --token=${{ secrets.VERCEL_TOKEN }}

OIDC / Secrets guidance

• Prefer OIDC over long-lived cloud secrets when your cloud provider supports it (AWS, Azure, GCP, others). OIDC issues short-lived tokens per job run and removes the need to store long-lived cloud credentials in GitHub secrets. (Docs: https://docs.github.com/actions/concepts/security/openid-connect)
• If you enable OIDC in workflows, add permissions: id-token: write at workflow or job level so jobs can request the token. (See configuration guides for cloud providers.)
• Use repository custom properties as OIDC claims to limit which repos can assume cloud roles (GA Apr 2, 2026). This enables attribute-based access control: define properties like environment: production or team: payments on repositories and reference those claims in your cloud provider trust policy (AWS, Azure, GCP). Changelog: https://github.blog/changelog/2026-04-02-github-actions-early-april-2026-updates/

Step 2 — Reusable workflow pattern

# .github/workflows/reusable-ci.yml
name: Reusable CI
on:
  workflow_call:
    inputs:
      node-version: { type: string, default: "20" }
      run-e2e: { type: boolean, default: false }
    secrets:
      VERCEL_TOKEN: { required: false }
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - uses: pnpm/action-setup@fe02b34f77f8bc703a5f83169411f1f62a0633a0
      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af
        with:
          node-version: "${{ inputs.node-version }}"
          cache: pnpm
      - run: pnpm install --frozen-lockfile && pnpm lint && pnpm tsc --noEmit && pnpm test
      - if: inputs.run-e2e
        run: pnpm test:e2e

Consume: uses: ./.github/workflows/reusable-ci.yml with with: { node-version: "20", run-e2e: true }.

Examples

Example 1 — Matrix builds across Node versions

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix: { node: [18, 20, 22] }
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - uses: pnpm/action-setup@fe02b34f77f8bc703a5f83169411f1f62a0633a0
      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af
        with: { node-version: "${{ matrix.node }}", cache: pnpm }
      - run: pnpm install --frozen-lockfile && pnpm test

Example 2 — Monorepo with path filters

on:
  pull_request:
    paths: ["packages/api/**", "packages/web/**", "pnpm-lock.yaml"]
jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      api: ${{ steps.f.outputs.api }}
      web: ${{ steps.f.outputs.web }}
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36
        id: f
        with:
          filters: |
            api: ["packages/api/**"]
            web: ["packages/web/**"]
  test-api:
    needs: changes
    if: needs.changes.outputs.api == 'true'
    uses: ./.github/workflows/reusable-ci.yml
  test-web:
    needs: changes
    if: needs.changes.outputs.web == 'true'
    uses: ./.github/workflows/reusable-ci.yml

Example 3 — Service container entrypoint override (new)

Use entrypoint / command to override an image's defaults when your integration tests need custom flags or a different startup mode. The syntax mirrors Docker Compose.

jobs:
  integration:
    runs-on: ubuntu-latest
    services:
      redis:
        image: redis:7
        entrypoint: ["redis-server"]
        command: ["--save", "", "--appendonly", "no"]
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - run: pnpm install && pnpm test:integration

(Reference: https://github.blog/changelog/2026-04-02-github-actions-early-april-2026-updates/ and https://docs.github.com/actions/tutorials/use-containerized-services/use-docker-service-containers)

Caching — rate limits & recommendations (revised)

• GitHub introduced a rate limit for new cache uploads: 200 uploads/minute per repository. This limit only affects uploads of new cache entries; cache restores/downloads are not rate limited. (Changelog: https://github.blog/changelog/2026-01-16-rate-limiting-for-actions-cache-entries/)
• actions/cache@v5 is the recommended major version. Important compatibility notes from the action maintainers:
  • v5 runs on Node.js 24 and requires a minimum Actions Runner version of 2.327.1 for self-hosted runners. Update self-hosted runners before switching to v5. (Repo: https://github.com/actions/cache)
  • The action integrates with the new cache service (v2) APIs; review the action's release/migration notes before upgrading.
• Recommendations to avoid rejections and reduce churn:
  • Prefer stable cache keys derived from lockfiles (e.g. hashFiles('pnpm-lock.yaml')) and use restore-keys to broaden matches instead of creating a new key every run.
  • Consolidate cache uploads: upload a single, combined cache per logical artifact (e.g., one for node_modules / pnpm store or .next/cache) rather than per-matrix axis when possible.
  • Avoid per-commit unique keys and per-job keys that differ only by runner metadata.
  • Use conditional if: checks to skip cache save steps when the cache hit indicates no change.
  • Monitor for 429 responses or rejected cache uploads in job logs; the upload limit is per-repository, so cross-repo patterns can also hit limits on popular mono-repos.

Security & supply chain

• Pin critical actions to full commit SHAs when reproducible builds and supply-chain guarantees are required. The tag @vX is convenient but mutable.
• Use least-privilege permissions: entries at workflow or job level — the default token grants write across many scopes. Explicitly set only what you need.
• Prefer OIDC-based cloud access instead of long-lived secrets where supported; configure cloud trust to accept OIDC claims (including repository custom properties for organization-scoped policies).
• Beware forked PRs: they cannot access secrets. For PRs from forks, use read-only checks or require maintainer-initiated runs.

New guidance: rerun limits & automated retries

• GitHub now limits a workflow run to 50 reruns (including partial reruns of job subsets). Avoid automated approaches that repeatedly trigger reruns (scripts that loop on failure) — they can exhaust the quota and cause failures. (Changelog: https://github.blog/changelog/2026-04-10-actions-workflows-are-limited-to-50-reruns/)
• Alternatives to repeated reruns:
  • Implement retries at the step level with exponential backoff inside your job (e.g., a small retry loop around flaky network calls) rather than rerunning the whole workflow.
  • Use concurrency with cancel-in-progress: true to avoid redundant runs stacking up while diagnosing flakiness.
  • For flaky test suites, invest in test isolation / stabilization and rerun only failing tests locally or in a targeted job instead of the full workflow.

Edge cases and gotchas (updated)

• Cache thrashing & rate limits — overly specific keys both miss caches and risk hitting the upload rate limit; layer with restore-keys and avoid per-commit keys.
• Service container entrypoint — previously many workarounds were needed; use entrypoint / command now.
• Rerun quota — repeated reruns beyond operational test loops will fail after 50 attempts; partial reruns count toward the same quota.
• Concurrency races — without concurrency groups, pushes to the same PR queue redundant runs
• Fork secret exposure — pull_request from forks cannot access secrets; pull_request_target has write access on the base — use with caution
• Action supply-chain — @v4 tags can be moved; pin to full SHA when security matters
• Timeout waste — default 360-min timeout burns runner minutes on hung jobs
• pnpm store path — differs on self-hosted runners, breaking cache restore

Evaluation criteria

Decision tree

1. Have tests? → Yes: CI workflow. No: lint + type-check only.
2. Monorepo? → Yes: path filters + --filter. No: single job.
3. Multiple Node versions? → Yes: matrix. No: pin to LTS.
4. Deploying from CI? → Yes: environments with secrets or OIDC (prefer OIDC). No: skip deploy jobs.
5. Shared CI across repos? → Yes: reusable workflow. No: keep local.
6. Long builds? → Yes: cache .next/cache + turbo remote cache, avoid excessive key churn. No: default cache.
7. Security-sensitive? → Yes: SHA-pinned actions, restricted perms, scheduled audit.

Edge experiments / follow-ups

• Monitor cache upload rejections across popular marketplace actions and document concrete workarounds (e.g., consolidated upload patterns).
• Publish recommended mappings and examples for repository custom properties → cloud trust policies (AWS, Azure, GCP) and measure adoption.
• Evaluate usage patterns of consolidated caches across large monorepos to quantify upload reduction and hit-rate improvement.