cicd-pipelines

CI/CD Pipelines

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

<!-- dual-compat-start -->

Use When

• Use when designing or implementing a release pipeline that turns every commit into a release candidate progressing through automated stages with clear pass/fail gates.
• Use when picking GitHub Actions vs GitLab CI, federating CI to cloud or Vault via OIDC, or wiring blue/green / canary deploys into a workflow.
• Use when adding pipeline observability (DORA metrics, queue time, stage duration) or fixing anti-patterns like cache poisoning, mega-workflows, or rebuild-per-environment.

Do Not Use When

• Jenkins-on-Debian operations, plugin governance, or controller hardening — load references/cicd-jenkins-debian.md.
• Vault server architecture, PKI, exception governance, or compliance controls — load references/cicd-devsecops.md.
• High-level pipeline shape and stage-boundary design from a blank slate — start with references/cicd-pipeline-design.md, then return here for the engine-specific implementation.

Required Inputs

• Source-control engine (GitHub, GitLab CE, both) and runner story (self-managed Debian/Ubuntu, hosted, mix).
• Target deploy surface (Debian VPS, Kubernetes, ECS, mobile stores) and the chosen deployment strategy.
• Secret-management posture (Vault, AWS Secrets Manager, env secrets) and whether OIDC federation is already wired.

Workflow

• Read this SKILL.md first; load only the referenced files needed for the engine and deploy surface in front of you.
• Apply the stage-gate model in §1 before writing YAML — pipelines without explicit gates rot into mega-workflows.
• Produce the deliverable (workflow YAML, trust policy, deploy record schema) with assumptions and rollback plan made explicit.

Quality Standards

• Build once, deploy many: a single artefact (digest-pinned image, signed AAB, .ipa) is promoted through every environment.
• Least-privilege permissions: per workflow and per job; no static cloud keys when OIDC is available.
• Every production deploy emits a deployment record (git SHA, image digest, environment, actor, timestamp, run URL) to an append-only sink.

Anti-Patterns

• Echoing constructed strings containing secrets; pinning third-party actions to mutable tags; one mega-workflow per repo.
• Cache keys without a lockfile hash; rebuilding per environment; deploying without a concurrency: group on production.
• Long-lived static AWS_ACCESS_KEY_ID in repo secrets when OIDC federation is available.

Outputs

• Reusable workflow with versioned inputs/outputs; environment-specific deploy workflows; rollback workflow.
• OIDC trust policy, least-privilege IAM/Vault role binding, deployment-record schema and sink.
• Pipeline-observability dashboard spec (DORA quad + queue time + stage p95) wired into SigNoz/Prometheus.

Evidence Produced

Category	Artifact	Format	Example
Release evidence	Pipeline configuration record	Markdown doc covering build, test, deploy stages plus secret references	docs/ci/pipeline-config.md
Release evidence	Latest release run evidence	CI URL plus archived log of the most recent successful release	docs/ci/release-run-2026-04-16.md
Release evidence	Deployment record sink schema	JSON schema + sample row	docs/ci/deployment-record.md

References

• references/oidc-federation.md — OIDC → AWS, GCP, and Vault with bound-claim trust policies.
• references/pipeline-observability.md — DORA metrics, queue time, scraper sketch, dashboards.
• references/reference-architectures.md — three end-to-end pipelines (PHP/MySQL SaaS, Node.js/TS service, container library).
• references/anti-patterns.md — broken vs fixed examples.
• references/github-vs-gitlab.md — engine comparison and migration notes.
• references/github-actions-workflows.md, references/mobile-pipelines.md, references/ios-fastlane-pipeline.md, references/android-pipeline.md — domain templates.

<!-- dual-compat-end -->

Load Order

1. Load world-class-engineering and git-collaboration-workflow for the baseline.
2. Load references/cicd-pipeline-design.md for the high-level pipeline shape.
3. Load this skill for engine-specific implementation (GitHub Actions primary, GitLab CI secondary).
4. Pair with references/cicd-devsecops.md for secrets policy, references/cicd-jenkins-debian.md when the engine is Jenkins, deployment-release-engineering for rollout, observability-monitoring for post-deploy verification, cloud-architecture for traffic-shifting plumbing.

§1 What a CI/CD pipeline is and is not

The deployment pipeline is the canonical model: every commit produces a release candidate that progresses through automated stages, and any failed stage stops the candidate. Continuous Delivery (Humble & Farley, Addison-Wesley, 2010, ISBN 978-0-321-60191-9) frames the pipeline as the mechanism by which you build quality in rather than testing it in afterwards. The DevOps Handbook (2nd ed., Kim, Humble, Debois, Willis, IT Revolution, 2021, ISBN 978-1-950508-40-2) reinforces this with the First Way (flow from development to operations) and Second Way (fast feedback via short-lived automated pipelines).

Stage-gate convention used throughout this skill, derived from the canonical 5-stage model:

Stage	Purpose	Target duration
Commit	Compile, unit tests, lint, type-check	< 5 min
Build artefact	Reproducible artefact (image digest, jar, signed AAB, .ipa)	< 5 min
Acceptance / integration	Service-level tests against real dependencies	< 15 min
Security scan	SAST, dependency scan, container scan, secret scan	parallel with acceptance
Deploy to staging	Automated, no human gate	< 5 min
Deploy to production	Gated (manual approval or progressive delivery)	minutes

Pipeline-as-code, deploy-on-green, and a single artefact promoted across environments are the three load-bearing principles. Branch-based release calendars (cut a branch, freeze, manually QA) are the failure mode this model replaces.

§2 GitHub Actions production patterns

Workflow files live under .github/workflows/*.yml and are triggered by on: events: push, pull_request, schedule, workflow_dispatch, workflow_call, release. Filename is the stable reference; name: is human-readable. Jobs run in parallel by default; use needs: to serialise.

The two reuse primitives:

• Reusable workflow (on: workflow_call) — job-level reuse. Accepts inputs: and secrets:; callers can pass secrets: inherit to forward all secrets without listing each one. Up to 10 levels of nesting.
• Composite action (action.yml in a directory) — step-level reuse. Bundles multiple steps as a single uses:.

Use composite actions for "set up the build toolchain", reusable workflows for "the standard CI job for a Node service".

Matrix, concurrency, permissions:

strategy:
  fail-fast: false
  matrix:
    node: ['18', '20', '22']
    os: [ubuntu-24.04, macos-14]

concurrency:
  group: deploy-${{ github.ref }}-${{ matrix.environment }}
  cancel-in-progress: false

permissions:
  contents: read
  id-token: write
  packages: read

fail-fast: false is the platform-engineering default — see all matrix-leg failures, not just the first.

Environments wrap a deploy target with policy: required reviewers, wait timer, deployment-branch policy, environment-scoped secrets. Production deploys always run inside an environment:

jobs:
  deploy-prod:
    environment: { name: production, url: https://app.example.com }
    runs-on: ubuntu-24.04

GitLab CI dialect differences live in references/github-vs-gitlab.md; the patterns here apply to both engines.

§3 Secret injection without long-lived credentials

GITHUB_TOKEN is automatically issued per workflow run with permissions the workflow specifies; grant the least required access. Pin per job and never rely on legacy write-all defaults.

id-token: write enables OIDC federation — the workflow exchanges a short-lived OIDC token for a cloud or Vault credential. No static AWS_ACCESS_KEY_ID anywhere.

Minimal AWS pattern:

permissions: { id-token: write, contents: read }
steps:
  - uses: actions/checkout@v4
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
      aws-region: eu-west-1
  - run: aws sts get-caller-identity

Bind the IAM trust policy to the exact sub (repo:acme/api:environment:production), never repo:*. Vault's JWT auth method consumes the same OIDC token; the Vault role binds the same sub claim and a short token TTL. GCP uses Workload Identity Federation with the same shape. Full trust-policy JSON, GCP WIF binding, and Vault role config live in references/oidc-federation.md.

Secret scoping:

• Repository secrets — unscoped; reuse across workflows (e.g., CODECOV_TOKEN).
• Environment secrets — scoped to a GitHub Environment (dev, staging, production). Production secrets never leak into PR builds.
• Organisation secrets — shared across repos; use sparingly, prefer environment scoping.

§4 Artifact and dependency management

Lockfile-keyed dependency caches:

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

Targets: ~/.npm, ~/.cache/pnpm, ~/.cache/composer, ~/.gradle/caches + ~/.gradle/wrapper, Pods/ (keyed on Podfile.lock), ~/.cargo/registry + target/, ~/.cache/pip (keyed on requirements*.txt). The setup-node / setup-python / setup-java actions have a built-in cache: parameter — prefer it when the lockfile is at the repo root.

Docker BuildKit cache via type=gha with mode=max stores all intermediate layers. Order Dockerfile instructions

---

Content truncated.