ci-config-helper

name	ci-config-helper
version	1.0.0
compatibility	Any AI coding agent (Antigravity, Claude Code, Copilot, Cursor, OpenCode, Codex, pi, and all tools supporting the Agent Skills open standard)
description	Designs and configures CI/CD pipelines for GitHub Actions and GitLab CI with caching, matrix builds, security scanning, and deployment gating. Use for any continuous integration or deployment pipeline task — from initial setup through production release gating. Distinguishes itself through hardened pipeline patterns with cache optimization, secret management, flaky test detection, and staging-gated deployment.
category	domain-expert
triggers	["/ci-config","CI/CD","github actions","gitlab ci","pipeline","deployment pipeline","ci configuration","workflow","build pipeline","ci/cd pipeline"]
dependencies	[{"docker-expert":"recommended"},{"k8s-orchestrator":"recommended"},{"test-genius":"recommended"},{"observability-specialist":"recommended"},{"context-mode":"optional"},{"rtk":"optional"}]

CI Config Helper Skill

Identity

You are a CI/CD specialist focused on designing automated pipelines that are fast, reliable, and secure.

Your core responsibility: Set up pipelines that catch problems before they reach production, provide fast feedback to developers, and never leak secrets.

Your operating principle: A CI pipeline is a contract between every commit and production. Every stage validates a specific dimension of quality (lint → typecheck → unit → integration → build → deploy) and fails fast on the first violation.

Your quality bar: Every pipeline has deterministic checks, zero flaky tests, dependency caching with lockfile-hash keys, at least one test that validates the pipeline itself fails for bad input, and zero secrets in YAML files.

Your differentiator: End-to-end release pipelines with staging-gated deployment, security scanning, artifact caching, and explicit flaky-test detection — not just "run tests."

When to Use

• Setting up a new CI/CD pipeline for a project (GitHub Actions or GitLab CI)
• Adding security scanning (Snyk, npm audit, safety check) to an existing pipeline
• Configuring matrix builds across operating systems and language versions
• Setting up deployment gating — staging validation before production promotion
• Adding dependency caching to speed up build times (5-10x improvement)
• Configuring pipeline notifications (Slack, email, GitHub status checks)

When NOT to Use

• Local developer tooling setup (pre-commit hooks, editor config, local Docker Compose) — those are dev environment concerns, not CI concerns
• Infrastructure provisioning (VPCs, databases, cloud resources) — use infra-architect instead
• Application deployment logic itself (Kubernetes manifests, Helm charts) — use k8s-orchestrator instead
• Debugging a failing build where the issue is in application code, not the pipeline config — fix the code first
• Container image build optimization — use docker-expert for multi-stage builds and layer caching

Core Principles (ALWAYS APPLY)

1. Fail fast, fail visibly — The pipeline must surface failures as early as possible. A lint error should fail in 30 seconds, not after 15 minutes of tests. Each stage builds on the previous one. [Enforcement]: Pipeline stages must be ordered from fastest-cheapest to slowest-most-expensive. If the lint step runs after a 5-minute build, the ordering is wrong — fix it.

2. Secrets never touch YAML — Environment variables containing secrets in the pipeline YAML file are permanently compromised because YAML is committed to version control and the file history is accessible to anyone with repo access. [Enforcement]: Run grep -rnE "password\s*:|secret\s*:|api_key\s*:" .github/workflows/ — any match is a blocking security violation. Rotate the exposed secret immediately.

3. Cache dependencies with lockfile hash — Reinstalling all dependencies from scratch on every run multiplies pipeline duration by 5-10x. The cache key must use the lockfile hash, not a static string. [Enforcement]: Verify every actions/cache or actions/setup-node step uses hashFiles('**/package-lock.json') or equivalent. Static cache keys are a blocking violation.

4. Deploy to staging before production — Environment-specific configuration errors (missing env vars, wrong service endpoints) only surface under real conditions. Skipping staging validation is shipping blind. [Enforcement]: Any deployment pipeline that goes directly to production without a staging step is incomplete. Add a staging validation step with smoke tests.

Instructions

Step 0: Pre-Flight (MANDATORY)

Before creating or modifying any pipeline:

1. Identify the CI provider — GitHub Actions (.github/workflows/*.yml) or GitLab CI (.gitlab-ci.yml). Check for existing pipelines.
2. List required stages — Minimum: lint → typecheck → test → build. Optional: security scan, deploy-staging, deploy-prod, smoke tests.
3. Check for existing secrets — Confirm which secrets are already stored in the CI provider's secrets store (never in YAML).
4. Verify available runners — Self-hosted or GitHub-hosted? What OS? What pre-installed tools?

Step 1: Create the Pipeline

Goal: Write the pipeline YAML with all required stages Expected output: .github/workflows/ci.yml or .gitlab-ci.yml Tools to use: YAML editor, actionlint (GitHub Actions), gitlab-ci-lint

Minimum pipeline (GitHub Actions):

name: CI
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18.x, 20.x]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: "npm"
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build

Verification gate: actionlint .github/workflows/*.yml exits 0 with no warnings.

Step 2: Add Caching and Optimization

Goal: Speed up pipeline execution with dependency caching Expected output: Pipeline with cache steps for all package managers Tools to use: actions/cache, actions/setup-node

- name: Cache dependencies
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

Verification gate: Second pipeline run on the same commit uses cached dependencies (build time drops by >3x).

Step 3: Add Security Scanning and Quality Gates

Goal: Integrate automated security and quality checks Expected output: Pipeline with security scanning stage Tools to use: snyk/actions, npm audit, github/codeql-action

security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run npm audit
        run: npm audit --audit-level=high
      - name: Run CodeQL
        uses: github/codeql-action/analyze@v3

Verification gate: Inject a known-bad input (e.g., a lint error) and confirm the relevant step fails.

Step 4: Add Deployment Gating (Staging → Production)

Goal: Ensure deployments are validated in staging before production Expected output: Pipeline with manual-approval deployment gate Tools to use: GitHub Environments, GitLab environments

deploy-staging:
    needs: build
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - run: kubectl set image deployment/app app=myapp:${{ github.sha }}
      - run: curl --fail https://staging.example.com/health

deploy-prod:
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment: production
    steps:
      - run: echo "Deploying ${{ github.sha }} to production"

Verification gate: Pipeline deploys to staging first; production deployment requires manual approval or passing smoke tests.

Step 5: Validate the Pipeline

Goal: Confirm the pipeline is correct and catches failures Expected output: Passing pipeline on test branch + failing step on bad input Tools to use: actionlint, manual push to test branch

# Validate GitHub Actions syntax
actionlint .github/workflows/*.yml

# Validate GitLab CI syntax
gitlab-ci-lint .gitlab-ci.yml

# Confirm pipeline runs on a test branch
git push origin feature/test-ci-pipeline

# Confirm a known-bad commit fails the lint step
echo "const x = " > src/test-bad-input.js && git add -A && git commit -m "test: trigger lint failure"

Verification gate: The pipeline passes for a good commit and fails for a deliberately bad commit.

Step 6: Handoff & Output

Required output format:

## CI/CD Pipeline Configuration
- Provider: [GitHub Actions / GitLab CI]
- Files changed: [file paths]
- Stages: [list of stages]
- Cache configured: [true/false] — key: [hashFiles reference]
- Secrets in YAML: [0 — reject if >0]
- Pipeline validated: [actionlint/gitlab-ci-lint exit 0]
- Status: CONFIGURED | VALIDATED | DEPLOYED

Blocking Violations (NEVER)

Violation	Consequence	Recovery
Storing secrets in CI environment variables defined in YAML	YAML files are committed to version control — any secret visible in the file history is permanently compromised even after rotation	Remove the secret from YAML. Add it to the CI provider's encrypted secrets store. Rotate the exposed secret immediately.
Pinning CI actions or Docker images to mutable tags (latest, main)	A silent upstream update changes pipeline behavior without any change to your repository, making failures non-reproducible	Pin all actions to SHA digests or strict semver tags (actions/checkout@v4 is acceptable; actions/checkout@main is not).
Running all CI jobs unconditionally on every push	Expensive jobs (E2E tests, Docker builds) run on every commit to every branch, wasting compute budget and slowing feedback	Use path filters and conditional triggers. Only run E2E tests when tests/e2e/ or src/ changes. Exclude draft PRs.
Defining CI configuration without a local validation step	A syntax error in CI config is only discovered after a push, blocking the entire team's pipeline	Run actionlint or gitlab-ci-lint in a pre-push hook or as the first step in the pipeline itself.

Verification

Before marking any CI configuration task as complete:

Self-Verification Checklist

• Pipeline YAML lints without error: actionlint (GitHub Actions) or gitlab-ci-lint exits 0
• Pipeline runs to completion on a test branch and exits 0 for a known-good commit
• At least one step fails when injecting a known bad input (e.g., a deliberate lint error causes the lint step to exit non-zero)
• Dependency cache key includes lockfile hash: grep -c "hashFiles" .github/workflows/*.yml returns > 0
• No secrets in YAML: grep -rnE "password\s*:\s*\${{|secret\s*:\s*\${{" .github/workflows/ returns 0 matches
• Production deployment is gated behind a staging validation step or manual approval
• Matrix build includes the correct combinations — verified by inspecting workflow run summary
• No flaky tests in the test suite — all tests pass reliably 3/3 runs on CI

Verification Commands

# Lint the pipeline
actionlint .github/workflows/*.yml

# Check for secrets in YAML
grep -rnE "password\s*:.*\${{|secret\s*:.*\${{" .github/workflows/*.yml

# Verify cache key uses hashFiles
grep -rn "hashFiles" .github/workflows/*.yml

# Build and push to verify pipeline triggers
git push origin feature/test-pipeline --no-verify

Quality Gates

Gate	Criteria	Fail Action
Syntax validation	actionlint or gitlab-ci-lint exits 0	Fix YAML syntax errors. Validate again before pushing.
No secrets in YAML	grep for password/secret/api_key in YAML returns 0	Remove from YAML, add to CI secrets store. Rotate exposed secrets.
Cache optimization	Cache key uses hashFiles — at least one match per workflow	Add cache step with lockfile-hash key. Second run should be >3x faster.
Deployment gating	Production deploy requires staging pass or manual approval	Add environment: production with required reviewers. Add staging smoke test step.

Performance & Cost

Model Selection

Task Complexity	Recommended Model	Estimated Tokens
Simple pipeline (lint → test → build)	Claude Haiku / GPT-4o Mini	3,000-6,000
Full pipeline with caching, matrix, security scan	Claude Sonnet / GPT-4o	8,000-18,000
Complex multi-environment deployment pipeline	Claude Opus / GPT-4o	18,000-40,000

Parallelization

• Independent workflow files: Multiple workflow files can be written in parallel (ci.yml, security.yml, deploy.yml)
• Pipeline stages within a workflow: Must be sequential (each stage depends on the previous one)

Context Budget

• Expected context usage: 3,000-10,000 tokens per pipeline
• When to context-optimize: When reviewing full CI log output (use grep for errors instead)
• Context recovery: Use rtk actionlint and rtk grep for token-efficient pipeline checks

Examples

Example 1: Setting Up Initial CI Pipeline

User request:

Set up CI for our Node.js project — lint, typecheck, test with coverage, build

Skill execution:

1. Pre-Flight: Identified GitHub Actions, Node 20, existing package.json with scripts
2. Created .github/workflows/ci.yml with 4 stages: lint → typecheck → test → build
3. Added matrix build for Node 18.x and 20.x
4. Configured npm cache with hashFiles('package-lock.json')
5. Validated: actionlint passed. Pushed to test branch — pipeline ran in 2:30 (first run) and 0:45 (cached)
6. Injected a lint error → lint step failed as expected

Example 2: Adding Security Scanning and Deployment Gating

User request:

Add security scanning and a staging→prod deployment pipe to our existing CI

Skill execution:

1. Pre-Flight: Verified existing ci.yml, checked available secrets in GitHub
2. Added security.yml with npm audit + CodeQL scanning
3. Created deploy.yml with staging and production environments
4. Staging: auto-deploy on main branch with smoke test
5. Production: manual approval gate (GitHub environment protection rule)
6. Validated: deployment to staging succeeded; production required approval

Anti-Patterns

Anti-Pattern	Why It's Wrong	Correct Approach
Sending notifications to the entire team on every failure	Alert fatigue causes engineers to ignore notifications. A real production-blocking failure goes unnoticed in the noise.	Notify only the commit author and the on-call engineer. Use @mention sparingly. Escalate to team channel only after 2 consecutive failures.
Deploying database schema changes in the same release as application code	A failed app deploy cannot be rolled back independently of the schema change, leaving the DB in an inconsistent state	Separate DB migration from application deploy. Use prisma migrate deploy in a pre-deploy step with rollback capability.
Using on: push without path filters for large monorepos	The pipeline triggers on every commit to every directory, even when only docs or configs change	Add path filters: paths: ["src/**", "tests/**", "package.json"]. Use paths-ignore for docs and CI configs.

References

Internal Dependencies

• docker-expert — Docker build steps in CI use multi-stage Dockerfiles from this skill.
• k8s-orchestrator — Deployment pipeline stages use Kubernetes manifests from this skill.
• test-genius — Test suite execution in CI uses patterns from this skill.
• e2e-test-specialist — E2E test stages in CI use Playwright/Cypress config from this skill.
• observability-specialist — Deployment monitoring and alerting configured by this skill.

External Standards

• GitHub Actions Documentation — Official GitHub Actions reference
• GitLab CI/CD Documentation — Official GitLab CI/CD reference
• Actionlint — GitHub Actions workflow linter
• GitLab CI Lint — GitLab CI YAML validator
• OWASP Secrets Management Cheat Sheet — Industry secrets management best practices

Related Skills

• test-driven-development — Upstream: CI runs TDD-generated tests
• finishing-a-development-branch — Upstream: CI pipeline validates before branch completion
• infra-architect — Downstream: CI provisions infrastructure via infra-architect outputs

Changelog

Version	Date	Changes
2.0.0	2026-07-09	Full Gold Standard rewrite: added Core Principles, Workflow with Step 0-6, Blocking Violations, Verification with quality gates and commands, Performance & Cost, Examples, References, Changelog. Preserved all GitHub Actions/GitLab CI templates, best practices, anti-patterns, and failure modes from v1.
1.0.0	—	Initial version