Lesson 3 of 8 in CI/CD pipelines
Build, test and artifacts
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
- 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.
- Commit to Build job: 1 checkout
- Build job to Artifact: 2 upload dist
- Artifact to Test job: 3 download dist
- 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.
- 1Add 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 pushThe test passes only if the downloaded file contains this run's commit hash, which proves the test job received the build job's output.
- 2Download 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 holdsbuild-info.txt. - 3Break 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, becausegrepreturns 1 when it finds nothing. Revert withgit revert HEADand push to go back to green.
What breaks, and where to look
The upload step warns
No files were found with the provided pathand no artifact appears.- WHY IT HAPPENS
- The
pathdoes 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 -Ron the folder you expect, and compare it with thepath:value.
The download step fails because it cannot find the artifact.
- WHY IT HAPPENS
- The
namediffers between upload and download, or the test job started before the upload because it has noneeds:. - CHECK FIRST
- Compare the two
name:values character by character and confirmneeds: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
.envfiles 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.
Keep going
Lesson 49 of 92 in the DevOps path