Artifacts

Artifacts are files a workflow keeps after it ends, such as test reports or built binaries. You can download them from the pipeline page, the CLI or the API until they expire.

Unlike a build cache, an artifact is immutable, is never restored into a run, and is never evicted to make room.

Setup

1. Enable artifacts on the server

   Artifacts are off by default and need a cache backend, because they share its instance-wide local directory or S3 bucket:

   CROW_CACHE_BACKEND=local
   CROW_CACHE_LOCAL_PATH=/var/lib/crow/cache
   CROW_ARTIFACT_ENABLED=true

   See the artifact environment variables for limits.

2. Add an artifacts section to the workflow

   artifacts:
     - name: dist
       paths: [dist]
       retention_days: 30
     - name: reports
       paths: [reports, coverage.xml]
       if_missing: warn
   
   steps:
     build:
       image: golang:1.27
       commands: [go build -o dist/app ./...]

If artifacts are disabled, an artifacts section produces a linter warning and is ignored.

Options

Option	Required	Description
name	Yes	Up to 128 ASCII letters, digits, dots, underscores or hyphens, unique within the workflow
paths	Yes	String or list of paths relative to the workspace
retention_days	No	Days the artifact is kept, 14 by default. More than CROW_ARTIFACT_MAX_RETENTION_DAYS is an error
if_missing	No	error (default) fails the step when a path is missing, warn logs a warning and uploads the other paths

Execution

The compiler adds an upload-artifacts step after all other steps. It uses the same image as the cache steps.

The step also runs after a failed step, so test reports of a failed run are kept. If the step itself fails, the workflow fails: an artifact is a result of the run, not an optimization. Failed transfers and server errors are retried three times with backoff first. Cancelled pipelines do not upload.

Each artifact is one tar archive compressed with zstd. Symlinks are stored as links, and a symlink pointing outside the workspace fails the step.

Artifacts are stored as they are. Log masking does not cover them, so do not put secrets into the declared paths.

Pull requests from forks

Pull requests from forks may upload artifacts only once they are approved, through Approve once or Always approve (approval requirements). This is stricter than running the pipeline: if a repository requires no approval, a fork’s pipeline runs without anyone approving it, so it does not upload. Restarting an approved pipeline keeps the approval.

Without approval, the step logs a warning and succeeds, so the pipeline does not fail for something the contributor cannot change.

Limits

Artifacts have their own limits, separate from those of the cache. A full quota fails the upload: artifacts are never evicted, so nothing is removed to make room. Lowering a limit only refuses new uploads.

Pending uploads count towards the limits. With several server replicas, concurrent uploads can overshoot a limit slightly, as they can for caches.

Admins can see size and egress per user and organization under Admin Settings > Caches, and override the limits there or from the CLI:

crow admin cache set <org> --artifact-max-size 100GiB --artifact-max-egress unlimited

Downloading and deleting

The pipeline page has an Artifacts tab if the pipeline declares artifacts. Anyone who can read the repository can download them, which includes anonymous visitors of public repositories. Repository admins can delete them there too.

# list the artifacts of a repository
crow repo artifact ls <repo>
# download one
crow repo artifact download --output dist.tar.zst <repo> <artifact-id>
# delete one
crow repo artifact rm <repo> <artifact-id>

The API endpoints are GET /api/v1/repos/{repo_id}/artifacts, GET /api/v1/repos/{repo_id}/artifacts/{artifact_id}/download and DELETE /api/v1/repos/{repo_id}/artifacts/{artifact_id}. Pass pipeline_id to the list endpoint to get the artifacts of one pipeline. With S3 storage, the download endpoint redirects to a presigned URL.

Extract an archive with tar --zstd -xf dist.tar.zst.

Each artifact lists a SHA-256 digest of its archive. The uploading step reports it: uploads to S3 go straight to the bucket, so the server only verifies the size.

Deleting a pipeline, repository or organization deletes its artifacts. Deleting the caches of a repository does not.

Storage

Artifacts are kept in the storage of CROW_CACHE_BACKEND, in a separate artifacts/ folder, and always in the server’s storage: an organization’s own bucket only holds its caches.

If a bucket lifecycle rule expires your caches, exclude <CROW_CACHE_S3_PREFIX>/artifacts/ from it, or artifacts disappear before their retention ends. Artifacts need S3 storage with multiple server replicas: a local directory has to be shared between them.