github-actions-artifact-budget-audit_skill

Overview

This skill audits GitHub Actions artifact storage usage from JSON exports to find oversized or stale artifacts before they increase CI costs. It groups artifacts by repository and name, applies configurable warn/critical thresholds, and produces text or JSON reports for human review or automation. Use it to prioritize cleanup and to fail CI when configured thresholds are exceeded.

How this skill works

The skill reads one or more GitHub Actions artifact JSON exports (the gh api output or combined payloads) and calculates sizes in MB per artifact and aggregated totals by repository and artifact name. It applies configurable WARN_MB and CRITICAL_MB thresholds, flags artifacts that will soon expire, and supports filters for repositories and artifact name patterns. Output is emitted as concise text for terminal use or as structured JSON for dashboards and automation; it can also return a nonzero exit when critical artifacts exist if enabled.

When to use it

• You want to find oversized or duplicated artifacts inflating storage costs.
• You maintain many repos and need a quick, repeatable audit of artifact volumes.
• You need to prioritize cleanup by near-expiry and size impact.
• You want machine-readable reports to feed dashboards or CI gating.
• You need to fail CI when artifact budgets are breached.

Best practices

• Export artifacts per repo using gh api --paginate so each JSON contains an artifacts array.
• Set WARN_MB and CRITICAL_MB sensible to your org’s cost profile and iterate thresholds after initial runs.
• Use REPO_MATCH / ARTIFACT_MATCH to scope audits to high-risk projects to reduce noise.
• Run with OUTPUT_FORMAT=json for automation and dashboards, and text for one-off inspections.
• Include soon-expiry threshold (SOON_EXPIRES_DAYS) to focus cleanups that free space quickly.

Example use cases

• Run against nightly exports to generate a weekly artifact cost report and top offenders.
• Gate CI teardown: fail pipeline when FAIL_ON_CRITICAL=1 and a new artifact crosses CRITICAL_MB.
• Targeted cleanup: filter to a single repo and artifact family to remove stale test-results or coverage bundles.
• Feed JSON output to a dashboard that tracks artifact volume trends and expiration risk.
• Run with bundled fixtures during development to validate threshold and filter behavior.