Skip to content

EliasOulkadi/shokunin / .pack/skills/ci-cd

Design CI/CD pipelines for GitHub Actions, GitLab CI, and CircleCI with matrix builds, test sharding, caching, Docker layer caching, OIDC auth, deployment strategies (rolling, blue-green, canary), auto-rollback, self-hosted runners, and environment protection with manual approvals. Use when user asks to set up CI/CD, write a pipeline, configure GitHub Actions/GitLab CI/CircleCI, automate deployments, or set up build/test/deploy workflows. Do NOT use for Dockerfile authoring (use docker), K8s manifests (use kubernetes), or Terraform config (use terraform).

CI/CD Architect

Design fast, reliable, and secure CI/CD pipelines across GitHub Actions, GitLab CI, and CircleCI. Follows Google's DevOps capabilities and DORA metrics.

Decision Framework

Before building a CI/CD pipeline, answer:

  • Where is the code hosted? → If GitHub, start with GitHub Actions. If GitLab, use GitLab CI. On-prem? Consider self-hosted.
  • What's the deployment target? → Cloud (use OIDC), on-prem (use self-hosted runner), multi-cloud (use environment-specific jobs)
  • Is the team size 1-3? → Simple single-workflow. 10+? → Separate build, test, deploy workflows with artifact passing.
  • Do you need matrix builds (multiple OS/versions)? → Yes for libraries, no for single-platform apps.
  • Is the deploy target production? → Require manual approval gates. Non-prod: automatic on merge.

Workflow

Step 1: Choose platform

PlatformBest forConfig location
GitHub ActionsOSS, GitHub ecosystem.github/workflows/*.yml
GitLab CISelf-hosted, monorepos.gitlab-ci.yml
CircleCIPerformance, Docker.circleci/config.yml

Decision: If the project is on GitHub.com, use GitHub Actions. If self-hosted GitLab, use GitLab CI. If maximum performance needed, use CircleCI.

Step 2: Generate pipeline

Use the scaffold script with your platform and stack:

scripts/generate-pipeline.sh --platform github --language node --e2e --docker
scripts/generate-pipeline.sh --platform gitlab --language python --docker
scripts/generate-pipeline.sh --platform circle --language go --e2e

This generates a production-ready pipeline with:

  • Lint → typecheck → test (sharded) → build → docker → deploy
  • Caching (npm/pip/go, Docker layers)
  • OIDC auth (no static secrets)
  • Environment gates (staging → production)

Step 3: Configure caching

Cache typeGitHub ActionsGitLab CICircleCI
npm/pip/goactions/cache with lockfile hashcache:key: with lockfile hashsave_cache / restore_cache
Docker layersdocker/build-push-action GHA cacheDocker layer caching on self-hostedRemote Docker engine cache
Playwright browsersnpx playwright install chromiumbefore_script cacheCustom Docker image with browsers
Build artifactsupload-artifact / download-artifactartifacts: sectionpersist_to_workspace

If the build is consistently >15 min: add more shards or parallelize independent jobs.

Test sharding

# GitHub Actions: split tests across N parallel runners
strategy:
  matrix:
    shard: [1, 2, 3, 4]
steps:
  - run: npx vitest --shard=${{ matrix.shard }}/${{ strategy.job-total }}

In GitLab CI, use the parallel: key: parallel: 4 and CI_NODE_INDEX / CI_NODE_TOTAL env vars.

Decision: Use sharding when test suite >5 min. Start with 2 shards, increase until each shard runs in <3 min. For Playwright, shard by spec file weight with playwright test --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL.

Monorepo strategies

PatternTrigger ruleCache key
Path-basedpaths: ['packages/web/**'] (GHA) / rules:changes: (GitLab)${{ hashFiles('packages/web/package-lock.json') }}
Label-basedif: contains(github.event.pull_request.labels.*.name, 'web')Per-package cache restore
Full rebuildMonorepo tools (Nx, Turborepo) use their own remote cachingN/A — tool-managed

For large monorepos, use Nx or Turborepo for task orchestration. Let the tool handle --since, affected projects, and remote cache. Reference the tool's CI recipe — don't hand-roll matrix logic when the tool already solves it.

Environment protection rules

# GitHub Actions — manual approval gate before production
deploy-prod:
  needs: [deploy-staging]
  environment:
    name: production
    # Enforces: required reviewers, wait timer, restricted branches, deployment history
  steps: [...]
  • Required reviewers: Minimum 2 for production, 1 for staging
  • Wait timer: Force 5-minute buffer before deploy (catch last-minute reverts)
  • Deployment branches: Only main or release/* can trigger production
  • Auto-inactive: Mark deployments inactive after 30 days, prevent stale environment clutter
  • GitLab equivalent: environment: production with deploy: free or protected environments
  • CircleCI equivalent: approval job type with restricted contexts

Secret rotation

Never store long-lived secrets in CI/CD. Prefer:

  1. OIDC (preferred): No secrets at all — federated identity with short-lived tokens
  2. Short-lived credentials: Clouds offer 1-hour max tokens via OIDC
  3. Secret rotation schedule: Rotate all static secrets every 90 days, documented in playbook
  4. CI/CD secret scanning: Enable GitHub secret scanning push protection or GitLab secret detection

For legacy systems requiring static secrets, store them only in the CI/CD platform's encrypted variables (not in repo), audit access via audit logs, and set expiration reminders via automation.

Step 4: Set up OIDC (no static secrets)

# GitHub Actions
permissions:
  id-token: write
  contents: read
steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456:role/github-actions
      aws-region: us-east-1

Step 5: Configure deployment strategy

See references/deployment-strategies.md for full details.

StrategyRollbackUse when
Rolling updateManual (undo)Stateless apps
Blue-greenInstant (LB switch)Zero-downtime required
CanaryGradual (traffic % adjust)High-risk, gradual rollout

Always implement healthcheck verification after deploy:

- name: Healthcheck
  run: |
    for i in {1..30}; do
      STATUS=$(curl -so /dev/null -w '%{http_code}' https://app.example.com/health)
      if [ "$STATUS" = "200" ]; then exit 0; fi
      sleep 2
    done
    echo "Healthcheck failed, rolling back..."
    kubectl rollout undo deployment/app
    exit 1

Step 6: Set up self-hosted runners (if needed)

See references/self-hosted-runners.md for K8s runners, autoscaling, caching, and security configurations.

Decision: Use GitHub-hosted runners for standard builds. Self-hosted if you need:

  • Custom hardware (GPU, large memory)
  • Docker-in-Docker performance
  • Private network access

Error Handling

ErrorCauseFix
Resource not accessible by integrationMissing permissions: block in GHA workflowAdd permissions: contents: read, id-token: write at job or workflow level
fatal: unable to access ... The requested URL returned error: 403Expired or missing git credentialsUse actions/checkout with token: ${{ secrets.GITHUB_TOKEN }} or deploy key
Error response from daemon: manifest for ... not foundDocker image tag doesn't exist in registryVerify tag was built and pushed; check registry path matches exactly
Job failed: runner disconnectedSelf-hosted runner crashed or network flakedAdd timeout-minutes per job, configure runner auto-restart, use spot instance rebalancing
No space left on deviceBuild artifacts filling runner diskAdd cleanup step: rm -rf /tmp/* or use actions/upload-artifact with retention; reduce Docker image size
deploy job requires a unique deployment_idConcurrent deploys to same environmentAdd concurrency: group: ${{ github.workflow }}-${{ github.ref }} to prevent race conditions
Cache not found (restore) / Cache already exists (save)Cache key mismatch or cache hit on locked keyUse restore-keys fallback for partial matches; include hashFiles('lockfile') in primary key
OIDC token fetch failedMissing id-token: write permission or IAM trust relationship misconfiguredVerify IAM trust policy allows token.actions.githubusercontent.com + correct repo/subject claim

Production Checklist

  • Lint + typecheck before tests
  • Tests parallelized (matrix/sharding)
  • Build artifacts cached or uploaded
  • Docker build uses layer caching
  • Plan/apply separation for IaC
  • Production deployment requires manual approval
  • Concurrency prevents simultaneous deploys
  • OIDC auth (no static cloud keys)
  • Rollback tested and documented
  • Notifications on failure (Slack/Discord/email)
  • Build time under 15 min

Anti-Patterns

Anti-patternFix
terraform apply from laptopCI/CD with plan/apply separation
Deploying from latest tagUse commit SHA or semver
No cacheCache deps, Docker layers, artifacts
Sequential testsParallel matrix or sharding
Static cloud creds in secretsOIDC or short-lived tokens
Secrets in pipeline YAMLCI/CD secret variables
Monolithic jobSplit: lint → test → build → deploy
No healthcheck after deployAuto-rollback on failure
Deploy on every main pushGated approval + environment protection

Pipeline Review Format (Required)

When reviewing CI/CD pipelines, use Before | After | Why format:

BeforeAfterWhy
Static cloud credentials in secretsOIDC with id-token: write permissionStatic credentials never expire. OIDC issues short-lived tokens per workflow run.
Sequential test jobsMatrix build + test sharding (strategy: matrix: shard: [1/4, 2/4, 3/4, 4/4])Sequential tests bottleneck the pipeline. Sharding parallelizes across runners.
terraform apply from laptopCI plan → manual approval → CI applyLaptop applies bypass audit trail and state locking. CI enforces process.
No cache on dependenciesactions/cache for node_modules/, pip cache, go mod cacheUncached dependencies add 2-5 minutes per run. Caching cuts this to seconds.

Matrix Build Optimization

# GitHub Actions: parallel test shards
strategy:
  matrix:
    shard: [1, 2, 3, 4]
steps:
  - run: npx vitest --shard=${{ matrix.shard }}/${{ strategy.job-total }}

# Parallel OS/version testing
strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [18, 20, 22]

Canary Deployment with Flagger

# Canary resource (Flagger CRD)
apiVersion: flagger.app/v1beta1
kind: Canary
spec:
  service: myapp
  analysis:
    interval: 30s; threshold: 5; maxWeight: 50; stepWeight: 10
    metrics:
    - name: request-success-rate; threshold: 99
    - name: request-duration; threshold: 500

Flow: deploy canary (10% traffic) → analyze metrics → if healthy, increase to 20%, 30%, 50% → promote to 100%.

Pipeline Approval Gates

# GitHub Environments with protection rules
deploy-prod:
  needs: deploy-staging
  environment: production
  steps: [ - run: ./deploy.sh ]

# Environment settings (GitHub UI):
# - Required reviewers: 2
# - Wait timer: 0 minutes
# - Deployment branches: main only

Sources

  • GitHub Actions docs (docs.github.com/actions)
  • GitLab CI docs (docs.gitlab.com/ee/ci)
  • CircleCI docs (circleci.com/docs)
  • DORA metrics (Google Cloud DevOps)
  • Docker BuildKit cache type
  • AWS IAM OIDC identity providers
  • Flagger documentation (flagger.app)

Pre-Deploy Checklist

Before merging to production:

  • All tests pass (unit, integration, E2E)
  • Security scan passes (no HIGH/CRITICAL vulnerabilities)
  • Lint and type checks pass with zero errors
  • Build artifact produced and validated
  • Deploy plan reviewed (IaC plan output, migration plan)
  • Rollback plan documented and tested
  • Environment protection rules active (require approvals for production)
  • Concurrency control enabled (prevent simultaneous deploys)
  • Healthcheck endpoint verified post-deploy
  • Monitoring alerts configured for the new version
  • Database migrations tested with a copy of production data

Checklist

  • Skill loads without errors in the AI agent
  • YAML frontmatter is valid (description, compatibility, audience)
  • Workflow section provides clear step-by-step instructions
  • Error handling section covers common failure modes
  • All referenced files (references/, scripts/, assets/) exist
  • Skill triggers correctly for intended use cases
  • No broken links or missing resources
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall