cicd-pipeline-author

name	cicd-pipeline-author
description	Designs and hardens CI/CD pipelines across GitHub Actions, GitLab CI, Jenkins, and CircleCI — caching, matrix builds, least-privilege tokens, pinned actions, and OIDC instead of long-lived secrets. Triggers when writing or fixing a pipeline/workflow file, speeding up CI, or securing a build.
when_to_use	เขียน/แก้ .github/workflows, .gitlab-ci.yml, Jenkinsfile; CI ช้า/แพง; ต้อง harden pipeline หรือเปลี่ยนไป OIDC

When to Use

Use this skill when the task touches a pipeline definition file or its performance/security:

• Authoring or editing .github/workflows/*.yml, .gitlab-ci.yml, Jenkinsfile, or .circleci/config.yml.
• CI is slow or expensive — reduce wall-clock time and runner minutes.
• Hardening a build: removing long-lived secrets, pinning third-party actions, scoping token permissions.
• Migrating cloud auth from static keys to OIDC (federated identity).
• Splitting a monolithic pipeline into reusable workflows/templates.

Skip if the change is a one-line tweak whose diff you can state in a sentence (bump a runner image tag, fix a typo in a step name) — just make it.

Steps

1. Detect platform and read the existing pipeline first. Match the file: .github/workflows/* → Actions, .gitlab-ci.yml → GitLab, Jenkinsfile → Jenkins, .circleci/config.yml → CircleCI. Never rewrite blind — read the current file, note language/build tool, where secrets are consumed, and which steps dominate runtime.

2. Lay out stages as a DAG, not a straight line. Target order: lint+typecheck → build → test → security-scan → deploy (gated). Run independent stages in parallel; only serialize on real data dependencies. In Actions use needs:; in GitLab stage: + needs: for out-of-order DAG; in CircleCI requires: under workflows.

3. Cache the dependency layer, key it on the lockfile. Cache key = hash of the lockfile, with a restore-key fallback for partial hits. Cache the package dir, not node_modules-style install output that must stay in sync with the runner.

   • Actions: actions/cache with key: deps-${{ runner.os }}-${{ hashFiles('**/lock*') }} and restore-keys: deps-${{ runner.os }}-. For common ecosystems prefer the built-in cache (e.g. setup-* with cache: input) which keys the lockfile for you.
   • GitLab: cache: { key: { files: [lockfile] }, paths: [...], policy: pull-push }; set policy: pull on jobs that only read.
   • Never cache build artifacts that change every commit — that just thrashes the cache. Pass those between stages as artifacts instead.

4. Add a matrix only where it earns parallelism. Fan out across versions/OS that you actually support. Set fail-fast: false when you need the full failure map (e.g. compatibility testing); leave it true (default) to abort early and save minutes on normal PR runs. Shard a large test suite across N parallel jobs and merge results.

5. Pin third-party actions/images by full commit SHA, not a tag. Tags (@v4) are mutable and a supply-chain hole. Pin uses: owner/action@<40-char-sha> # v4.1.2 and keep the version in a trailing comment so a bot can bump it. Pin container/runner images by digest where the platform allows. First-party actions/* may use a major tag if your policy permits, but SHA is the safe default.

6. Scope token permissions to least privilege. In Actions, set top-level permissions: { contents: read } (default-deny everything else) and widen per-job only for what that job needs (e.g. id-token: write for OIDC, packages: write to publish). In GitLab, prefer job tokens with limited scope over project access tokens. Never give a test job write access.

7. Replace static cloud secrets with OIDC. Stop storing long-lived AWS_*/GCP_*/AZURE_* keys. Have the pipeline mint a short-lived token via the provider's federated identity:

   • Job needs permissions: id-token: write (Actions) or the platform's OIDC equivalent.
   • Configure a trust policy on the cloud side scoped to this repo + this branch/environment + this workflow (don't trust repo:*).
   • Use the provider's official auth action to exchange the OIDC token for temporary credentials. Remove the old secrets after the OIDC path is verified — not before.

8. Factor shared logic into reusable workflows/templates. Actions: reusable workflow called via uses: ./.github/workflows/x.yml or a composite action. GitLab: include: + extends: + !reference. CircleCI: orbs/commands. Jenkins: shared library. One source of truth beats copy-pasted YAML across services.

9. Make failures fast and required. Put cheap checks (lint, typecheck) before expensive ones so a bad PR fails in seconds. Add timeout-minutes to every job so a hung step can't burn an hour. Wire the gating jobs into branch protection / required status checks so deploy literally cannot run on a red build. Gate deploy on a protected environment with manual approval for prod.

10. Validate locally and report the diff. Lint the file, dry-run if possible (see Verify), then report before/after wall-clock and estimated runner-minutes, plus the security delta (secrets removed, permissions narrowed, actions pinned). A pipeline change without a measured result is unfinished.

Common Errors

• permissions block at top level silently kills the whole-workflow grant. The moment you add any permissions: key, every unlisted scope becomes none. A push/comment step that worked before will now 403. Add back exactly what each job needs at job level.
• Cache restored but the install step still runs full. Usually the cache path is wrong, or the key changes every run (you hashed a file that mutates). Verify with the cache-hit output, and cache the package manager's store dir, not the project-local install dir.
• OIDC Error: Not authorized to perform sts:AssumeRoleWithWebIdentity / audience mismatch. The cloud-side trust condition doesn't match the token's sub/aud. Check the exact subject string format (it differs for branch vs tag vs environment vs pull_request) and that the audience matches what the auth step requests.
• Pinned SHA points at a tag that was force-moved → action runs different code than reviewed. Always re-verify the SHA belongs to the version in your comment; don't copy a SHA from an untrusted PR.
• fail-fast cancels sibling matrix jobs and you lose the failure you needed. For compatibility/flake debugging set fail-fast: false; for normal PRs keep it on to save minutes — they're opposite goals, pick deliberately.
• Secrets passed into a reusable workflow vanish. Reusable workflows don't inherit secrets implicitly — pass them with secrets: inherit or map each one explicitly.
• pull_request from a fork can't read secrets / OIDC. That's by design (untrusted code). Don't "fix" it by switching to pull_request_target with checkout of the PR head — that's a known privilege-escalation footgun. Run untrusted PR builds without secrets.
• No timeout-minutes → a hung network call burns the full default timeout (often 6h) of paid minutes. Set an explicit per-job timeout always.
• Caching across untrusted PRs can poison the cache. Scope/segregate caches so a fork PR can't write a cache a trusted branch later reads.

Verify

• Syntax/lint: Actions → actionlint (catches expression and context errors a YAML linter misses). GitLab → CI Lint API/UI. CircleCI → circleci config validate. Jenkins → jenkins-cli declarative-linter. Any platform → a plain YAML linter as a floor.
• Dry run where supported: run the workflow locally (e.g. act for Actions) for fast iterate-on-failure before pushing; if the job has external/cloud deps that can't run locally, push to a throwaway branch and read the live run.
• Security checklist passes: no secrets.* for cloud creds remaining (OIDC instead); top-level permissions is read-only with per-job widening; every third-party action pinned to a full SHA; every job has timeout-minutes; deploy gated by required checks + protected environment.
• Performance proven: capture wall-clock and runner-minutes before vs after on a real run; confirm the cache reports a hit on the second run and parallel jobs actually overlap. Report the numbers — "should be faster" is not verification.
• Branch protection enforced: confirm the gating jobs are listed as required status checks so a red build blocks merge/deploy.