Imported from RNobre1/xp-stack (plugins/xp-stack/skills/optimizing-github-actions/SKILL.md). Install upstream with npx skills add RNobre1/xp-stack --skill optimizing-github-actions. Copyright stays with the author.

Pra engines sem skill loading (Cursor, Codex sem MCP): leia este file inteiro e siga as instrucoes como se fossem suas. Voce nao precisa "invocar" — apenas obedeca. Cursor e Codex que tem xp-stack instalado via npm leem este SKILL.md em .cursor/rules/ ou .codex/skills/.

Voce eh o Auditor de CI. Sua missao eh rodar 10-item pre-flight checklist em todo workflow alterado: SHA pinning, OIDC, pull_request_target risk, concurrency, trigger eficiente, artifact v4, coverage em shards, bash hardening, gate calibrado, persist-credentials. Bloqueie merge se algum item criticar falhar.

Optimizing GitHub Actions Workflows

Prescriptive skill for any edit in .github/workflows/*.yml. Encodes 2025-2026 state-of-the-art for performance, quality, and security, plus universal anti-patterns documented from real supply-chain incidents.

When to use

Auto-activated via the paths: .github/workflows/** frontmatter field — Claude loads this skill when you edit any workflow file. Also invocable manually via /xp-stack:optimizing-github-actions when discussing CI/CD without a workflow file open (e.g., SHA pinning, OIDC migration, runner cost analysis).

The Iron Law

1. Before merging any change to .github/workflows/*.yml, run the 10-point pre-flight checklist below.
2. Before suggesting a "speed up CI" optimization, MEASURE BASELINE first via `gh run view --log` or the Actions UI. No guesses.
3. Before adding a third-party action, SHA-pin it. No exceptions for "trusted org".

Violating these three rules has caused real production incidents documented across the industry: Docker cache corruption costing 5min/job with no hit, duplicate CI runs on the same SHA wasting minutes, eval gates without baseline failing every PR.

Pre-flight checklist (10 items — run on every workflow edit)

Copy this section when reviewing an edit. Each item has a one-line rationale + reference. Items without OK in your review = fix before proposing the PR.

1. SHA pinning of third-party actions. Does every third-party action (uses: org/action@...) use a 40-char full-length SHA + # vN.N.N comment? Official GitHub actions (actions/*) may use major version but should be marked # OK: official. Reason: tj-actions/changed-files (CVE-2025-30066, March 2025) — attacker rewrote 350+ tags to point at malicious commit, ~23k repos compromised. Git tags are mutable. → references/security.md

2. OIDC for cloud auth. Does the workflow authenticate to AWS/GCP/Azure? If yes, does it use permissions: id-token: write + aws-actions/configure-aws-credentials (or equivalent) instead of ${{ secrets.AWS_ACCESS_KEY_ID }}? Reason: OIDC = ephemeral JWT, no duplicated credential, automatic rotation, granular control via trust policy. Long-lived secrets are only justifiable for services without OIDC support. → references/security.md

3. pull_request_target hardening. If the trigger is pull_request_target, does the workflow NOT check out the PR head (ref: ${{ github.event.pull_request.head.sha }}) without extreme sandboxing? Reason: classic RCE vector — pull_request_target runs with base repo secrets; checkout PR head + run code (npm install, build) = attacker via fork gets shell on runner with secrets. → references/security.md

4. Concurrency. Do PR workflows have concurrency.group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true? Do deploy workflows have cancel-in-progress: false? Reason: PR cancels previous run (savings + faster feedback); deploy NEVER cancels in-progress (risk of inconsistent prod state). → references/concurrency-and-triggers.md

5. Trigger efficiency (two sub-items — both):

   • 5a. Duplicate trigger on the SAME SHA. Is the trigger pull_request: [main, dev] BUT NOT push: [main, dev]? Push to dev would run CI 2x when a feature PR → dev merges (PR already tested + push generates new event). Keep push only on main (covers direct hotfix + serves as deploy gate). Reason: universal duplication anti-pattern; same SHA paid twice in minutes and money.
   • 5b. Expensive workflow. Does an LLM/heavy-Docker/long-build workflow run PR-only (no push trigger)? Cost ($, minutes) scales linearly with triggers; same SHA was already evaluated in the PR. Reason: evals/builds costing real $ should not run twice on the same code.

6. Artifact naming (v4). Does each actions/upload-artifact@v4 have a UNIQUE name (including ${{ matrix.shard }} when applicable)? Does the consolidator job use pattern: ...-* + merge-multiple: true or the merge sub-action? Reason: v4 broke compat with v3 (Dec 2023): artifacts are immutable, unique names required, no automatic merge. → references/artifacts-v4.md

7. Coverage threshold in sharded tests. Is the coverage threshold NOT being applied on individual shards? Each shard sees partial coverage = false negative. Threshold only on the merge job (Vitest: COVERAGE_SKIP_THRESHOLDS=1 on shards + --merge-reports + real threshold on merge). Reason: math — 1/3 of files = 1/3 of absolute coverage. → references/sharding.md

8. Bash hardening. Do long run: | scripts (>5 lines) start with set -euo pipefail? Do loops (for ... in ...) have explicit set -e or || exit on critical commands? Reason: default GHA shell is bash -eo pipefail but pipefail doesn't work in all scenarios; silent failure inside a loop = one broken deploy doesn't stop the rest. → references/security.md (section "Bash hardening")

9. Calibrated blocking gate. Does any step that does exit 1 on a numeric metric (eval, coverage, perf budget) have an empirical PoC confirming the metric DISCRIMINATES between baseline and experiment? If not, is it an informative gate (echo "::warning::..." && exit 0) with sticky comment? Reason: a hard threshold without empirical data fails healthy PRs and trains devs to bypass. Use informative mode until baseline is established. → references/observability.md

10. Checkout hardening. Do actions/checkout calls in workflows that DON'T do a subsequent git push have persist-credentials: false? Reason: principle of least privilege. v6+ stores credentials in $RUNNER_TEMP (safer than .git/config of v3-v5), but if the step doesn't need to authenticate to Git remote, it shouldn't persist a credential at all. → references/security.md

Decision matrices

When to shard tests

Sweet spot: 2-3 shards. 4+ has diminishing return (setup overhead × N vs speedup). Sharding without blob reporter is also valid — each shard uploads a separate artifact on failure.

When to use OIDC vs long-lived secret

For mandatory long-lived secrets, mark with explicit comment: # OIDC not supported by <service>.

When to use actions/cache@v4 vs setup-node native cache

When to use dorny/paths-filter vs native paths

Consider step-security/paths-filter as a hardened drop-in for dorny/paths-filter — aligned with post-tj-actions hardening.

When to use reusable workflow vs composite action

When to cancel-in-progress

Red flags (STOP — fix before proposing PR)

1. uses: org/action@vN (tag) without SHA pin in workflow with secrets: or permissions: write → see item 1.
2. ${{ secrets.AWS_* }} / ${{ secrets.GCP_* }} / ${{ secrets.AZURE_* }} when OIDC is supported → see item 2.
3. on: pull_request_target + actions/checkout with ref: head.* → BLOCKING, see item 3.
4. Duplicate trigger: pull_request: [dev] + push: [dev] → see item 5a.
5. Expensive workflow (LLM, heavy Docker) with push trigger → see item 5b.
6. actions/upload-artifact@v4 without unique name in matrix → see item 6.
7. vitest run --coverage --shard=N/M without COVERAGE_SKIP_THRESHOLDS (global threshold applied to partial shard) → see item 7.
8. run: | with for loop without set -e or || exit → see item 8.
9. exit 1 on numeric-metric gate without empirical baseline PoC → see item 9.
10. actions/checkout without persist-credentials: false in read-only workflow → see item 10.
11. Cache of payload >500MB in parallel jobs under same key without measuring hit rate → see references/caching.md (parallel cache corruption section).
12. env: at top-level with ${{ secrets.X }} when only 1-2 steps use it → secret scope too wide, move to step level.

Common rationalizations (and what to do instead)

Quick reference

DO NOT hardcode SHA pins in this skill — they age within days. Use the audit script to resolve tag → current SHA:

# Resolve tag to current SHA (monthly rotation)
gh api repos/actions/checkout/git/refs/tags/v5.0.0 --jq '.object.sha'

# Audit all workflows in the repo
bash ${CLAUDE_PLUGIN_ROOT}/skills/optimizing-github-actions/scripts/audit-action-pins.sh

Useful gh commands for triage:

gh workflow list                                            # List workflows
gh run list --workflow=ci.yml --limit=10                    # Last 10 CI runs
gh run view <run-id> --log                                  # Logs of a run
gh run view <run-id> --json conclusion,jobs                 # Structured status
gh api /repos/{owner}/{repo}/actions/runs/{run-id}/timing   # Time per job

Essential official docs:

• GitHub Actions: https://docs.github.com/en/actions
• OIDC hardening: https://docs.github.com/en/actions/concepts/security/openid-connect
• Concurrency: https://docs.github.com/en/actions/using-jobs/using-concurrency
• Vitest sharding: https://vitest.dev/guide/reporters
• Playwright sharding: https://playwright.dev/docs/test-sharding

Evolving this skill

GitHub Actions evolves quickly (actions/upload-artifact@v4 breaking change in Dec 2023, free ARM in Jan 2025, supply-chain incident in March 2025, pull_request_target change in Nov 2025). To keep this skill current:

• Monthly: review the SKILL.md + sub-files for outdated SHA pins and recently announced changes.
• When GitHub announces a breaking change: update the relevant references/ file + bump the version footer.
• When a new incident class appears in your project: add it to the project's local CLAUDE.md "Lessons Learned" + add an item to the pre-flight checklist if recurring.
• SHA pins: DO NOT hardcode here — use scripts/audit-action-pins.sh.

Additional resources

Sub-files (loaded on demand):

• references/security.md — SHA pinning, OIDC, pull_request_target, persist-credentials, secret scoping, bash hardening, tj-actions postmortem.
• references/sharding.md — Vitest blob+merge (v2.0.0+), Playwright shard with/without blob, fail-fast semantics, coverage in shards.
• references/artifacts-v4.md — Breaking changes vs v3, merge patterns, naming.
• references/caching.md — actions/cache@v4 vs setup-node native, restore-keys hierarchy, parallel cache corruption anti-pattern.
• references/concurrency-and-triggers.md — Concurrency groups, paths-filter (native vs dorny), avoiding SHA duplication.
• references/observability.md — STEP_SUMMARY, sticky comments, dashboards, calibrated gates.
• references/reuse-patterns.md — Reusable workflows vs composite actions, decision matrix.

Examples:

• examples/good-workflow.yml — Annotated template with SHA pins, OIDC, concurrency, correct sharding.
• examples/bad-workflow.yml — Same workflow with red flags marked (# RED FLAG: ...).

Scripts:

• scripts/audit-action-pins.sh — Iterates workflows, classifies uses: lines into PIN/MAJ/TAG/BAD/LOC, exit 1 if red flags.

Version: 0.2.0 (2026-04-26) Last audited: 2026-04-26