13.1.1.1 Pipeline Source Checkout

Pipeline source checkout is the first step in most CI/CD pipelines, retrieving the actual source code from version control that subsequent steps — building, testing, deploying — will operate against, providing the foundation every later pipeline stage depends on.

The Basic Checkout Step

A pipeline's first step typically retrieves the relevant commit or branch from the source repository.

jobs:
  build:
    steps:
      - uses: actions/checkout@v4
      - run: docker build -t myapp .

This checkout step ensures the subsequent docker build operates against the actual, current source code for whatever commit triggered this pipeline run.

Why Checkout Behavior Affects What Actually Gets Built

The specific commit, branch, or tag checked out directly determines what code the rest of the pipeline will build and test — getting this step wrong means every subsequent step operates against unintended source.

- uses: actions/checkout@v4
  with:
    ref: ${{ github.event.pull_request.head.sha }}

For a pull request pipeline specifically, checking out the PR's actual head commit (rather than some other reference) ensures the pipeline tests exactly what's being proposed for merge.

Why Checkout Depth Matters for Certain Build Processes

Some build or versioning tools need access to a repository's git history (for generating a changelog or version number based on commit history, for instance), requiring a checkout that includes more than just the latest commit.

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

This retrieves the complete git history, rather than the shallow, single-commit checkout that's the default and sufficient for most other purposes.

Why Submodules Sometimes Need Explicit Checkout Configuration

A project using git submodules needs this explicitly configured, since a default checkout typically doesn't automatically retrieve submodule content.

- uses: actions/checkout@v4
  with:
    submodules: true

Why Pipeline Source Checkout Matters

As the foundational first step every subsequent pipeline stage depends on, correctly configuring source checkout — the right reference, appropriate depth, submodule handling if needed — is essential for ensuring the rest of the pipeline operates against exactly the intended source code.