zuvo:ci-audit

Audit CI/CD pipelines for wasted time, insecure practices, and reliability gaps. Single-pass execution, no sub-agents needed.

Primary support: GitHub Actions (full coverage of all 10 dimensions). Detection-level: GitLab CI, CircleCI (adapted patterns, unsupported checks scored as N/A).

When to use: After changing CI workflows, when pipelines are slow, before release hardening, when CI costs are high, quarterly optimization. When NOT to use: Application security (/security-audit), test quality (/test-audit), test runner config (/tests-performance).

Mandatory File Loading

Read every file below before starting. Print the checklist.

CORE FILES LOADED:
  1. ../../shared/includes/codesift-setup.md   -- [READ | MISSING -> STOP]
  2. ../../shared/includes/env-compat.md        -- [READ | MISSING -> STOP]
  3. ../../shared/includes/run-logger.md        -- [READ | MISSING -> STOP]
  4. ../../shared/includes/retrospective.md        -- [READ | MISSING -> STOP]

If any file is MISSING, STOP. Do not proceed from memory.

Argument Parsing

Safety Gate

This audit is read-only. The only write target is zuvo/audits/.

FORBIDDEN:

• Modifying any workflow or pipeline file
• Running CI pipelines or triggering builds
• Modifying secrets or environment variables
• Installing CI plugins or actions

MANDATORY TOOL CALLS — CI Audit Validity Gate

INVALID if any tool below is skipped. "DEFERRED", "N/A" NOT valid reasons.

Forbidden: same as above (DEFERRED, codesift unavailable when deferred, retrospective skipped — all REJECTED).

POSTAMBLE: report on disk → retro appended → ~/.zuvo/append-runlog exit 0. Every CI finding needs path/to/file.ext:LINE (verify-audit gate).

Mandatory-tools-acknowledgment: I will run get_file_tree + search_text + search_patterns + scan_secrets + audit_scan for this CI audit. Every CI finding will cite a `path/to/file.ext:LINE` resolving in the current tree.

Use the deterministic preload helper FIRST. Run ~/.zuvo/compute-preload ci-audit "$PWD". Math gate enforced.

Phase 0: Detect and Scope

0.1 Platform Detection

Detect the CI platform and set scan targets.

If a [path] argument is provided:

• File: scan that file, detect platform from content
• Directory: find CI config within, detect platform

If no argument: auto-detect from project root.

If no CI config found: report error and suggest checking file locations.

0.2 Workflow Inventory

List all CI workflows/jobs with their trigger events.

Print:

CI PIPELINE INVENTORY
------------------------------------
Platform:    [GitHub Actions / GitLab CI / CircleCI]
Scope:       [auto-detected / user-specified path]
Workflows:   [N]
Total jobs:  [N]
Docker builds: [Y/N]
------------------------------------

Phase 1: Dimension Analysis (CI1-CI10)

Single-pass inline execution. No sub-agents required.

CI1: Caching Strategy -- Weight 15, Max 15

What to search for:

• GitHub Actions: actions/cache, setup-node with cache:, hashFiles, restore-keys
• GitLab CI: cache: sections, key: with $CI_COMMIT or lockfile reference
• CircleCI: save_cache / restore_cache, checksum

Score 0-15 based on coverage.

CI2: Parallelism and Job Structure -- Weight 12, Max 12

Dispatch follows ../../shared/includes/execution-policy.md through env-compat. Reuse existing authorization within that policy; session restrictions take precedence. Run each required gate and report its actual independence or an unmet requirement.

What to search for:

• needs: / dependencies: / requires: chains
• strategy: / matrix: / parallel: blocks

CI3: Conditional Execution -- Weight 8, Max 8

What to search for:

• paths: / paths-ignore:, only: / except: / rules:, filters:
• if: conditions, workflow_call (reusable)
• concurrency: with cancel-in-progress, interruptible:

CI4: Artifact Management -- Weight 5, Max 5

CI5: Secret Handling -- Weight 12, Max 12, Critical Gate

Critical gate: hardcoded secrets or secrets likely logged → triggers FAIL. The gate fires on that FINDING; a CI5 score of 0 also fires it but is not required.

Verification: For each secret reference found, read the surrounding step to check whether it is set via env: block (safe) or inlined in run: script (can leak to logs).

CI6: Action Pinning -- Weight 10, Max 10, Critical Gate

GitHub Actions only. GitLab CI / CircleCI: score N/A.

Critical gate: unverified actions from unknown sources → triggers FAIL. The gate fires on that FINDING; a CI6 score of 0 also fires it but is not required.

CI7: Timeout and Resource Config -- Weight 8, Max 8

CI8: Docker Optimization -- Weight 8, Max 8, N/A if no Docker

CI9: Test Integration -- Weight 12, Max 12, Critical Gate

Coverage gate detection: Finding codecov or coveralls alone is NOT a gate -- it is just reporting. A gate requires a threshold that fails the build (e.g., --coverageThreshold, fail_under, Codecov threshold in config).

Critical gate: no tests in CI → triggers FAIL. The gate fires on that FINDING; a CI9 score of 0 also fires it but is not required.

CI10: Pipeline Speed -- Weight 10, Max 10

Evaluated from workflow structure analysis, not by running pipelines.

Critical path estimation: Trace the longest chain of needs: dependencies. Each link adds one sequential step.

Phase 2: Scoring

CI1  = [0-15]   Caching Strategy
CI2  = [0-12]   Parallelism
CI3  = [0-8]    Conditional Execution
CI4  = [0-5]    Artifact Management
CI5  = [0-12]   Secret Handling              (critical gate)
CI6  = [0-10]   Action Pinning               (critical gate, N/A if not GHA)
CI7  = [0-8]    Timeout & Resources
CI8  = [0-8]    Docker Optimization          (N/A if no Docker)
CI9  = [0-12]   Test Integration             (critical gate)
CI10 = [0-10]   Pipeline Speed

N/A handling: CI6 = N/A if not GitHub Actions. CI8 = N/A if no Docker. Excluded from both score and max.

Score = sum / applicable_max x 100

Critical gates — any ONE of these findings triggers FAIL, whatever the numeric score:

These gates fire on the FINDING, not on an aggregate score of zero. Read as "the dimension scored 0" they are nearly unreachable, because every one of them spreads several checks over its weight: CI5 spreads its checks across its full weight, so one hardcoded secret beside several passing checks scores well above zero. The named condition in each parenthesis IS the trigger — a dimension score of 0 remains sufficient to fire the gate, it is simply not necessary.

Phase 3: Report

Save to: zuvo/audits/ci-audit-[YYYY-MM-DD].md — at the project root (zuvo/ resolves via git rev-parse --show-toplevel; override $ZUVO_OUTPUT_DIR. See ../../shared/includes/report-output-location.md).

Report Structure

# CI/CD Pipeline Audit Report

## Metadata
| Field | Value |
|-------|-------|
| Project | [name] |
| Date | [YYYY-MM-DD] |
| Platform | [GitHub Actions / GitLab CI / CircleCI] |
| Scope | [auto / user path] |
| Workflows | [N] |
| Total jobs | [N] |

## Executive Summary

**Score: [N] / 100** -- [HEALTHY / NEEDS ATTENTION / AT RISK / CRITICAL]

| Metric | Count |
|--------|-------|
| CRITICAL findings | N |
| HIGH findings | N |
| MEDIUM findings | N |

[2-3 sentence summary]

## Dimension Scores

| # | Dimension | Score | Max | Notes |
|---|-----------|-------|-----|-------|
| CI1 | Caching | [N] | 15 | |
| CI2 | Parallelism | [N] | 12 | |
| CI3 | Conditional Execution | [N] | 8 | |
| CI4 | Artifacts | [N] | 5 | |
| CI5 | Secret Handling | [N] | 12 | |
| CI6 | Action Pinning | [N] | 10 | |
| CI7 | Timeouts & Resources | [N] | 8 | |
| CI8 | Docker | [N] | 8 | |
| CI9 | Test Integration | [N] | 12 | |
| CI10 | Pipeline Speed | [N] | 10 | |
| **Total** | | **[N]** | **[M]** | |

## Findings (sorted by severity)
[Per finding: dimension, severity, file:line, description, fix]

## Optimization Roadmap

### Quick Wins (< 1 hour)
### Short-term (1 day)
### Medium-term (1 week)

Report Validation

After writing, verify:

• Dimension scores sum to total in Executive Summary
• Finding counts match Executive Summary
• All workflow files from inventory are covered

Phase 4: Next-Step Routing

RECOMMENDED NEXT ACTION
------------------------------------
CI5 CRITICAL (secrets)    -> /security-audit --static
CI9 = 0 (no tests)       -> add test step to pipeline
CI6 = 0 (unpinned actions)-> pin all actions to SHA + add Dependabot
CI1 < 5 (no caching)     -> add dependency + build caching
Score < 60%              -> prioritize quick wins, re-audit in 1 week
Score >= 80%             -> schedule next audit in 3 months
------------------------------------

CI-AUDIT COMPLETE

Score: [N] / 100 -- [grade] Platform: [GitHub Actions / GitLab CI / CircleCI] Dimensions: [N scored] | Critical gates: [PASS/FAIL] Findings: [N critical] / [N total]

Validity Gate (REQUIRED — print BEFORE Run line, AFTER retro append + append-runlog)

VALIDITY GATE
  triggers_held: platform=<github|gitlab|circle>
  required_tool_calls:
    get_file_tree: [<N> CI configs found | NOT_CALLED — VIOLATES_TRIGGER]
    search_text: [<N> yaml refs | NOT_CALLED — VIOLATES_TRIGGER]
    search_patterns: [<N> hits | NOT_CALLED — VIOLATES_TRIGGER]
    scan_secrets: [<N> hits | NOT_CALLED — VIOLATES_TRIGGER]
    audit_scan: [<N> findings | NOT_CALLED — VIOLATES_TRIGGER]
  postamble:
    retros_log_appended: [yes(bytes_added=N) | NOT_APPENDED]
    retros_md_appended: [yes(entry_count=N) | NOT_APPENDED]
    verify_audit_pass: [yes(<verified>/<total>) | NOT_RUN | REJECTED]
  gate_status: [PASS | FAIL — <which gates missing>]

If gate_status = FAIL → VERDICT = INCOMPLETE.

Append the Run line via the retro-gated wrapper (NOT direct >> runs.log):

printf '%b\n' "$RUN_LINE" | ~/.zuvo/append-runlog

Run: <ISO-8601-Z> ci-audit <project> <N-critical> <N-total> <VERDICT> - <N>-dimensions <NOTES> <BRANCH> <SHA7> <INCLUDES> <TIER>

Retrospective (REQUIRED)

Follow the retrospective protocol from retrospective.md. Gate check → structured questions → TSV emit → markdown append. If gate check skips: print "RETRO: skipped (trivial session)" and proceed.

After printing this block, append the Run: line value (without the Run: prefix) to the log file path resolved per run-logger.md.

VERDICT: PASS (0 critical findings), WARN (1-3 critical), FAIL (4+ critical).

Execution Notes

• Single-pass inline execution, no sub-agents required
• All search commands use the resolved CI target path from Phase 0
• GitHub Actions: full coverage of all 10 dimensions
• GitLab CI: CI1-CI5, CI7-CI10 supported; CI6 = N/A
• CircleCI: CI1-CI5, CI7-CI10 supported; CI6 = N/A
• Dimensions checking project-root files (Dockerfile, .dockerignore, dependabot.yml) reference the project root explicitly
• If gh run list is accessible, pipeline speed analysis can be supplemented with actual run durations
• CodeSift is not heavily used in this skill (CI files are YAML, not code), but codesift-setup.md is still loaded for consistency with other audit skills