circleci-config

CircleCI Config

Overview

Use this skill to improve CircleCI performance and stability without changing product behavior. Focus on measured bottlenecks first, then implement the smallest safe config changes with clear validation criteria.

Read references/cache-optimization.md when the request involves save_cache, restore_cache, persist_to_workspace, attach_workspace, cache key design, dependency caching, lockfiles, or complaints about low cache hit rates, oversized caches, or wasted persistence steps. Read references/persisting-data.md when the request involves choosing between caches, workspaces, and artifacts, or when data is being moved between jobs inefficiently. Read references/test-results-and-splitting.md when the request involves slow test jobs, parallelism, flaky test visibility, missing JUnit XML, or circleci tests run. Read references/patterns.md when the request involves approvals, branch/tag filters, schedules, deploy flow structure, or environment promotion patterns.

Inputs To Gather

• .yaml and .yml files in .circleci/ and any reusable config fragments
• Current pain points: duration, flakiness, cost, or maintainability
• Baseline metrics: slowest jobs, most frequent retries/failures, queue and run times
• Risk tolerance for structural changes

Workflow

1. Build a baseline.
   • Identify top 1-3 longest jobs and top flaky jobs.
   • Capture before metrics (duration, pass rate, retries).
2. Remove pipeline waste.
   • Eliminate duplicate jobs/workflows.
   • Tighten branch/tag filters and workflow triggers.
3. Improve dependency and artifact flow.
   • Fix cache keys to include deterministic lockfile checks.
   • Use workspaces/artifacts to avoid rebuilding identical outputs.
   • Prefer cache scopes that are narrow, reproducible, and cheap to restore.
4. Apply safe parallelism.
   • Parallelize only proven bottlenecks.
   • Keep fan-out/fan-in readable and deterministic.
5. Validate impact.
   • Define expected metric changes and acceptance criteria before finalizing.