Catalog My learning Blog
CI/CD and DevOps Tutorial: Build a Delivery Pipeline · Phase 2 · Lesson 8 · 4 min read

Pipeline as Code: YAML Pipelines Explained

On this page
  1. What pipeline as code means
  2. Anatomy of a GitHub Actions workflow
  3. Reusable workflows
  4. Linting workflows with actionlint
  5. Keeping pipelines simple
  6. Check yourself

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

YAML
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. paths filters skip runs when unrelated files change, which helps monorepos.
  • Jobs run on separate runners and share nothing unless you pass artifacts or outputs; needs orders them.
  • Steps either run a command or use an 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:

YAML
# 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 test

Each service calls it in a few lines, pinned to a version of the template:

YAML
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:

Code
actionlint && echo ACTIONLINT-CLEAN
Code
ACTIONLINT-CLEAN

Run 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.