Pipeline as Code: YAML Pipelines Explained
On this page
What pipeline as code means
Older CI servers stored pipeline configuration in a web UI. Nobody reviewed changes, nobody knew who broke the build config, and every project's setup drifted. Pipeline as code puts the pipeline in a file in the repository, so it's versioned with the code it builds, changed through pull requests, and identical on every branch.
GitHub Actions (.github/workflows/*.yml), GitLab CI (.gitlab-ci.yml), Azure Pipelines, CircleCI and Jenkins (Jenkinsfile) all work this way.
Anatomy of a GitHub Actions workflow
name: Frontend CI # shown in the UI
on: # triggers
pull_request:
paths:
- "frontend/**"
- ".github/workflows/paths.yml"
permissions: # what the job's token may do
contents: read
jobs: # jobs run in parallel unless linked with needs
test:
runs-on: ubuntu-latest # the runner
steps: # steps run in order, sharing a workspace
- uses: actions/checkout@v7 # a reusable action
- run: echo "only runs when frontend files change" # a shell command- Triggers (
on): pushes, pull requests, schedules, manual runs, other workflows.pathsfilters skip runs when unrelated files change, which helps monorepos. - Jobs run on separate runners and share nothing unless you pass artifacts or outputs;
needsorders them. - Steps either
runa command orusean action. - Expressions like
${{ github.sha }}read context, inputs and secrets.
Reusable workflows
Twenty services each copying the same 60-line CI file drift apart within months. A reusable workflow in a shared repository defines it once:
# acme/ci-templates: .github/workflows/reusable-node-ci.yml
name: Reusable Node CI
on:
workflow_call:
inputs:
node-version:
type: string
default: "24"
working-directory:
type: string
default: "."
permissions:
contents: read
jobs:
build-test:
runs-on: ubuntu-latest
defaults:
run:
working-directory: ${{ inputs.working-directory }}
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: ${{ inputs.node-version }}
cache: npm
cache-dependency-path: ${{ inputs.working-directory }}/package-lock.json
- run: npm ci
- run: npm testEach service calls it in a few lines, pinned to a version of the template:
name: Service CI
on: [pull_request]
jobs:
ci:
uses: acme/ci-templates/.github/workflows/reusable-node-ci.yml@v3
with:
node-version: "24"Improve the template, release v4, and services upgrade by changing one line. GitLab's include and CI/CD components, and Azure's templates, do the same.
Linting workflows with actionlint
YAML errors in pipelines are found late: you push, wait, and the run fails on a typo. actionlint checks workflows locally: unknown keys, invalid expressions, wrong input names, shell script problems (via shellcheck), and security issues. All the workflows above pass:
actionlint && echo ACTIONLINT-CLEANACTIONLINT-CLEANRun it in a pre-commit hook and as a CI step. For GitLab, the pipeline editor's validation and glab ci lint do the same job.
Keeping pipelines simple
- Put real logic in scripts in the repository (
./scripts/deploy.sh), which you can run and test locally, and keep YAML as wiring. - Avoid deep conditional logic in YAML; it's hard to test and read.
- Review pipeline changes as carefully as code: a pipeline has access to secrets and production.
Check yourself
Version history, code review for pipeline changes, a pipeline that always matches each branch's code, and the ability to reuse definitions through templates. A pipeline configured by clicking in a UI has none of that.
A versioned reusable workflow or template in a shared repository, which each service calls with a few inputs. Fixes and improvements are made once, and services upgrade by changing a version reference.
Scripts can be run, tested and debugged on a laptop, and work on any CI system. Logic embedded in YAML expressions only runs inside CI, so every fix needs another push and pipeline run.
Errors in GitHub Actions workflows before they run: invalid syntax, wrong expression types, unknown inputs and common script injection risks.
A hung job, waiting on a network call or a test that never ends, otherwise runs until the platform's default limit, often six hours. That wastes runner minutes and blocks merges; a timeout close to the normal duration fails fast.