Pipeline as Code

Pipeline as Code (PaC) is the practice of defining CI/CD pipeline configuration entirely in version-controlled files — rather than through a graphical UI or a database-backed configuration system — so that the pipeline is subject to the same engineering discipline as the application it builds. Every change to the pipeline is a code change: it goes through a pull request, gets reviewed, is tracked in Git history, and can be rolled back. A pipeline defined in a UI is invisible to version control, unreviewed, and unauditable. A pipeline defined as code is a first-class software artefact.

Pipeline as Code vs UI-Based Configuration

Older CI platforms — notably early Jenkins — defined pipelines through web interfaces. A team member would click through forms to configure build steps, set up triggers, and define post-build actions. This worked at small scale but created serious problems as pipelines grew: changes were made without review, there was no history of who changed what and when, the configuration could not be tested before deployment, and recreating a pipeline after a server failure required manual recreation from memory or documentation.

Modern platforms — GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines — define pipelines as YAML files committed to the repository. The pipeline lives alongside the code it builds. A PR that changes the application can also change the pipeline in the same commit. The pipeline's history is Git's history. This is not a cosmetic improvement; it is a fundamental shift in how the delivery system is governed and maintained.

GitHub Actions Anatomy — The Structure of a Workflow File

A GitHub Actions workflow is a YAML file stored in .github/workflows/. Understanding its structure is essential for writing pipelines that are readable, maintainable, and correct. Every workflow has four top-level concerns: when it runs, what it runs on, what permissions it has, and what jobs it contains.

name: CI Pipeline                        # Display name shown in GitHub Actions UI

on:                                      # Trigger definition — when does this workflow run?
  push:
    branches: [main]                     # On every push to main
  pull_request:
    branches: [main]                     # On PRs targeting main
    paths:
      - 'src/**'                         # Only if files in src/ changed (path filtering)
  workflow_dispatch:                     # Allow manual trigger from the GitHub UI

permissions:                             # Minimum permissions for the entire workflow
  contents: read                         # Read the repo — no write access needed
  packages: write                        # Write to GitHub Container Registry

env:                                     # Workflow-level environment variables
  NODE_VERSION: '20'
  REGISTRY: ghcr.io

jobs:
  build:                                 # Job ID — referenced by other jobs in needs:
    name: Build Application              # Human-readable job name in the UI
    runs-on: ubuntu-latest               # Runner type — GitHub-hosted Ubuntu

    outputs:                             # Values this job exposes to downstream jobs
      image-tag: ${{ steps.meta.outputs.tags }}

    steps:
      - name: Check out source
        uses: actions/checkout@v4        # Always pin actions to a specific version

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci                      # Clean install — respects lock file

      - name: Build
        run: npm run build

      - name: Set image metadata
        id: meta                         # Step ID — used to reference outputs
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ github.repository }}
          tags: |
            type=sha                     # Tag with commit SHA for traceability

Triggers and Contexts — Controlling When and With What

The on: block is one of the most powerful and most misused parts of a workflow file. Overly broad triggers — running on every push to every branch — produce unnecessary pipeline runs, waste runner minutes, and slow down the feedback teams actually care about. Precise triggers produce a pipeline that runs exactly when needed and nowhere else.

Contexts are the runtime data available to workflow steps — information about the trigger event, the repository, the runner, and the job. The github context exposes the commit SHA, the branch name, the actor who triggered the run, and the event type. The secrets context exposes encrypted secret values. The env context exposes environment variables. Understanding contexts is what separates a pipeline that works for one scenario from one that adapts correctly to every scenario it was designed for.

Composite Actions — Reusable Step Groups

Composite actions are a lighter-weight alternative to reusable workflows — they group a sequence of steps into a named, callable unit that can be referenced from any workflow in the same repository or from other repositories. Where reusable workflows are full jobs, composite actions are step groups: they run within the calling job's runner rather than on their own runner, and they do not require secrets to be explicitly passed.

A common use case is grouping the standard setup steps — checkout, setup-node, cache restore, clean install — into a composite action called setup-environment. Every job that needs those four steps calls the composite action in one line rather than repeating all four steps. When the Node version changes, one file changes. When a caching strategy improves, one file improves. The rest of the workflow files are untouched.

Pipeline Quality — Treating the Pipeline Like Production Code

If pipeline code is treated as a first-class software artefact, it deserves the same quality practices applied to application code. This means several things in practice: pipeline changes go through code review just like application code; YAML linting tools like actionlint run in CI to catch syntax errors and logic problems before they reach the main branch; and pipelines are tested — by running them in a branch environment before merging — rather than discovered to be broken only when they land on main.

Practice Questions

Answer in your own words — then check against the expected answer.

Lesson Quiz