CircleCI’s build artifacts are a bit like a treasure chest for your CI/CD pipeline, holding the compiled code, test reports, or anything else your build produces.
Let’s see how this plays out in a real workflow. Imagine a simple Node.js project. We want to build it, run tests, and then store the test results and a generated documentation file as artifacts.
version: 2.1
jobs:
build-and-test:
docker:
- image: cimg/node:18.12
steps:
- checkout
- run:
name: Install Dependencies
command: npm install
- run:
name: Run Tests
command: npm test
- run:
name: Generate Documentation
command: npm run docs # Assuming this creates a docs/ directory
- store_artifacts:
path: test-results.xml # Example: JUnit XML output from tests
destination: test-reports
- store_artifacts:
path: docs/
destination: api-docs
- store_artifacts:
path: dist/ # Assuming a build process outputs to dist/
destination: build-output
workflows:
version: 2
build-and-test-workflow:
jobs:
- build-and-test
In this configuration, the store_artifacts step is the key. When the build-and-test job successfully completes, CircleCI will collect the files or directories specified in the path parameter and upload them. The destination parameter dictates where these artifacts will be organized within the CircleCI UI. So, test-results.xml will appear under a "test-reports" folder, and the entire docs/ directory will be under "api-docs."
The primary problem this solves is making the outputs of your CI process accessible. Without artifacts, your build might succeed, but you’d have no easy way to download the generated application binaries, view detailed test reports, or inspect logs that were generated during the build. It bridges the gap between a successful build and actionable results.
Internally, CircleCI designates a specific storage location for your artifacts, typically tied to your project and build run. When store_artifacts is invoked, CircleCI identifies the specified files/directories on the build agent, packages them up, and uploads them to this designated storage. This storage is then accessible via the CircleCI web interface, allowing you to browse and download them. You control what gets stored via the path and destination parameters. path is relative to the project’s root directory on the build agent, and destination is a logical folder name within the artifact browser. You can store individual files, entire directories, or even multiple items by listing them.
A common misconception is that artifacts are automatically preserved indefinitely. While CircleCI retains artifacts for a period, their lifespan is tied to your plan and project settings. For long-term archival, you’ll often need to integrate with external storage solutions like S3, GCS, or Artifactory, downloading the artifacts first and then uploading them elsewhere.
Once you’ve mastered storing your build outputs, the next logical step is often automating the deployment of those artifacts to various environments.