Lesson 3 of 8 in CI/CD pipelines

Build, test and artifacts

Core9 minWritten for actions/upload-artifact v4, actions/download-artifact v5

A build step turns source code into something runnable, such as a bundle, a binary or a container image. An artifact is a file or folder that a job saves so that later jobs, or you, can download it after the runner is gone.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: Writing a GitHub Actions workflow, Containers with Docker

The problem this solves

If every job rebuilds the code for itself, the thing you tested may not be byte-for-byte the thing you deploy. A different dependency version or a changed timestamp can slip in between.

The safer pattern is to build once, save the result as an artifact, then test and deploy that same saved result. For container projects the artifact is often an image pushed to a registry instead of a file, but the rule is the same: build once, promote the same output.

How it works

Build once, test the same files
Build once, test the same filesThe build job checks out the commit and uploads its output, the test job downloads exactly that output and reports pass or fail.1 checkout2 upload dist3 download dist4 exit codeCommitsource codeBuild jobproduces dist/Artifactnamed distTest jobneeds: buildResultpass or fail
  • Other
  • Runs code
  • Data
  • Control

The build job checks out the commit and uploads its output, the test job downloads exactly that output and reports pass or fail.

  1. Commit to Build job: 1 checkout
  2. Build job to Artifact: 2 upload dist
  3. Artifact to Test job: 3 download dist
  4. Test job to Result: 4 exit code

The build job runs first and uses actions/upload-artifact to save a folder under a name. Artifacts are stored by GitHub and tied to the run. Once saved, an artifact is immutable, so to change it you upload a new one under a different name.

The test job declares needs: build, so it starts after the upload finished. It then uses actions/download-artifact with the same name. If the names differ, nothing is found.

Because the test job runs on a different machine, it works on exactly the files the build produced. The same artifact can later be handed to a deploy job, which is the idea behind promoting one build through several stages.

Try it yourself

Use the ci-demo repository from the previous concept. The build here is a fake one that writes a text file, so the example runs without any language toolchain.

  1. 1
    Add a build job and a test job joined by an artifact
    cat > .github/workflows/build-test.yml <<'EOF'
    name: build-test
    on:
      push:
        branches: [main]
    permissions:
      contents: read
    jobs:
      build:
        runs-on: ubuntu-latest
        timeout-minutes: 5
        steps:
          - uses: actions/checkout@v4
          - name: Build
            run: |
              mkdir dist
              echo "built from $GITHUB_SHA" > dist/build-info.txt
          - uses: actions/upload-artifact@v4
            with:
              name: dist
              path: dist/
      test:
        needs: build
        runs-on: ubuntu-latest
        timeout-minutes: 5
        steps:
          - uses: actions/download-artifact@v5
            with:
              name: dist
              path: dist/
          - name: Test the downloaded files
            run: grep "$GITHUB_SHA" dist/build-info.txt
    EOF
    git add .
    git commit -m "Add build and test jobs"
    git push

    The test passes only if the downloaded file contains this run's commit hash, which proves the test job received the build job's output.

  2. 2
    Download the artifact yourself

    Open the finished run in the Actions tab and scroll to the Artifacts section at the bottom of the summary. You will see dist. Download and unzip it to confirm it holds build-info.txt.

  3. 3
    Break the test on purpose
    sed 's/grep "$GITHUB_SHA"/grep "not-a-real-hash"/' .github/workflows/build-test.yml > /tmp/bt.yml && cp /tmp/bt.yml .github/workflows/build-test.yml
    git commit -am "Make the test fail"
    git push

    The test job turns red with Process completed with exit code 1, because grep returns 1 when it finds nothing. Revert with git revert HEAD and push to go back to green.

What breaks, and where to look

  • The upload step warns No files were found with the provided path and no artifact appears.

    WHY IT HAPPENS
    The path does not match where the build wrote its output. The runner's working directory is the repository root, and a typo or a build that wrote elsewhere produces an empty upload.
    CHECK FIRST
    Add a step before the upload that runs ls -R on the folder you expect, and compare it with the path: value.
  • The download step fails because it cannot find the artifact.

    WHY IT HAPPENS
    The name differs between upload and download, or the test job started before the upload because it has no needs:.
    CHECK FIRST
    Compare the two name: values character by character and confirm needs: lists the uploading job. The run summary shows which artifacts exist.
  • Tests are green in CI but the deployed app behaves differently.

    WHY IT HAPPENS
    The deploy job rebuilt the code instead of using the tested artifact, so the shipped files were never the tested files.
    CHECK FIRST
    Make the deploy job download the same artifact or image tag that the test job used, and avoid a second build.

When not to use this

  • Artifacts are stored for a limited time and count against storage limits. Use a package or image registry for outputs you need to keep long term.
  • Never upload secrets or .env files as artifacts. Anyone who can read the run can download them.

Check yourself

Why build once and reuse the output instead of rebuilding in each job?

So the files you deploy are exactly the files you tested.

Why can the test job not just read the build job's dist/ folder directly?

Each job runs on its own clean runner, so the folder only reaches it through an uploaded and downloaded artifact.

What links an upload step to a download step?

The artifact name, plus needs: so the download runs after the upload.

Lesson 49 of 92 in the DevOps path

Search

Search cheat sheets and projects