homericintelligence/.claude-plugin/skills/github-actions-ci-speedup

Skill: github-actions-ci-speedup

Overview

| Field | Value | |-----------|-------| | Date | 2026-02-20 | | Issue | #787 | | PR | #835 | | Objective | Reduce GitHub Actions CI from 7+ minutes to ~2 minutes by fixing broken pixi caching, caching pre-commit environments, and running pre-commit on changed files only for PRs | | Outcome | Success — all changes committed and pushed; expected 5–6 min savings per job on cache hits |

When to Use

• CI/CD pipeline is taking 5+ minutes on dependency installation
• setup-pixi built-in cache: true is failing with HTTP 400 or Saved cache with ID -1
• Every CI run shows "Cache miss" with no successful restore or save
• Pre-commit runs --all-files even on PRs that touch only a few files
• Codecov step failing with 429 rate-limit errors

Root Cause: Broken setup-pixi Built-in Cache

The prefix-dev/setup-pixi action's built-in cache: true option is unreliable in some environments. Symptoms:

##[warning]Failed to restore: Cache service responded with 400
Cache miss
...
##[warning]Failed to save: Our services aren't available right now
Saved cache with ID `-1`

This causes a full pixi install (~6 minutes) on every single run. The fix is to remove cache: true and use actions/cache@v4 explicitly.

Verified Workflow

1. Identify the problem

Look for these patterns in CI logs:

• Install pixi step taking 5–7 minutes
• Failed to restore: Cache service responded with 400
• Saved cache with ID -1
• Total CI time dominated by dependency install (>80% of runtime)

2. Fix pixi caching (both jobs)

Remove cache: true from setup-pixi and add an explicit actions/cache@v4 step after setup-pixi:

- name: Install pixi
  uses: prefix-dev/[email protected]
  with:
    pixi-version: v0.62.2
    # DO NOT use: cache: true  (broken — always fails with 400)

- name: Cache pixi environments
  uses: actions/cache@v4
  with:
    path: |
      .pixi
      ~/.cache/rattler/cache
    key: pixi-${{ runner.os }}-${{ hashFiles('pixi.lock') }}
    restore-keys: |
      pixi-${{ runner.os }}-

Key points:

• Cache key uses pixi.lock hash — invalidated only when dependencies change
• restore-keys prefix allows partial cache hits when the lock changes
• Both .pixi (environments) and ~/.cache/rattler/cache (package cache) must be cached
• The pre-commit and test jobs can share the same cache key since they use the same pixi.lock

For the pre-commit job, also add environments: lint to setup-pixi:

- name: Install pixi
  uses: prefix-dev/[email protected]
  with:
    pixi-version: v0.62.2
    environments: lint

3. Cache pre-commit hook environments

Pre-commit downloads and installs hooks (Node.js for markdownlint, yamllint, shellcheck) on every run. Add a second cache step:

- name: Cache pre-commit environments
  uses: actions/cache@v4
  with:
    path: ~/.cache/pre-commit
    key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
    restore-keys: |
      pre-commit-${{ runner.os }}-

4. Run pre-commit on changed files only for PRs

- name: Run pre-commit
  env:
    EVENT_NAME: ${{ github.event_name }}
    BASE_REF: ${{ github.base_ref }}
  run: |
    pixi install --environment lint
    if [ "$EVENT_NAME" = "push" ]; then
      pixi run --environment lint pre-commit run --all-files --show-diff-on-failure
    else
      pixi run --environment lint pre-commit run --from-ref "origin/$BASE_REF" --to-ref HEAD --show-diff-on-failure
    fi

Security note: github.base_ref must go through an env: variable (not inline ${{ }} in run:). This is the safe pattern per GitHub's injection guidance.

5. Fix Codecov rate limiting

- name: Upload coverage
  if: matrix.test-group.name == 'unit'
  uses: codecov/codecov-action@v3
  with:
    files: ./coverage.xml
    flags: ${{ matrix.test-group.name }}
    token: ${{ secrets.CODECOV_TOKEN }}
    fail_ci_if_error: false

6. Verify

After pushing:

1. First run: cache miss, but Cache saved successfully appears (not Failed to save)
2. Second run (same PR): cache hit, pixi install completes in <30s
3. All tests pass, coverage ≥ 72%
4. All pre-commit hooks pass

Failed Attempts

1. Keeping cache: true and just upgrading setup-pixi version

What happened: The cache: true option in setup-pixi calls the GitHub Actions cache service under the hood, and the 400 error comes from the cache service itself, not the action version. Upgrading the action doesn't fix it.

Fix: Remove cache: true entirely and replace with explicit actions/cache@v4.

2. Using github.base_ref directly inline in run: step

What happened: The security pre-tool-use hook blocked the edit with a warning about using ${{ github.base_ref }} directly inside a run: block (potential injection risk if the ref were attacker-controlled in a fork PR).

Fix: Move it to an env: block and reference via $BASE_REF. This is the safe and correct pattern regardless of actual injection risk.

3. Caching only .pixi without ~/.cache/rattler/cache

What happened: The rattler package cache (~/.cache/rattler/cache) contains downloaded conda packages. Without caching it, pixi must re-download packages even with a valid environment, reducing the cache hit benefit.

Fix: Always cache both paths together.

Results & Parameters

| Metric | Before | After (cache hit) | |--------|--------|-------------------| | pixi install (test job) | ~6m21s | ~10-20s | | pixi install (pre-commit job) | ~6m16s | ~10-20s | | pre-commit hook setup | ~32s | ~3-5s | | Total CI wall-clock | ~7m30s | ~2 min | | Percentage wasted on install | 85% | ~10% |

Configuration used:

# Cache key pattern
key: pixi-${{ runner.os }}-${{ hashFiles('pixi.lock') }}
restore-keys: |
  pixi-${{ runner.os }}-

# Pre-commit cache key pattern
key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
restore-keys: |
  pre-commit-${{ runner.os }}-

Diagnosis Checklist

When CI is slow due to dependency installation:

• [ ] Check Install pixi step duration — if >2 min, caching is broken
• [ ] Look for Failed to restore: Cache service responded with 400
• [ ] Look for Saved cache with ID -1
• [ ] Check whether cache: true is set on setup-pixi (remove it)
• [ ] Confirm actions/cache@v4 is being used (not v3 or v2)
• [ ] Verify both .pixi AND ~/.cache/rattler/cache are in the cache path:
• [ ] Confirm cache key includes pixi.lock hash