Artifacts

Keep immutable build outputs with explicit retention, verified downloads, and a lifecycle separate from cache.

Keep build outputs beyond a job

Artifacts are immutable outputs such as binaries, test reports, coverage bundles, static sites, and deployment packages. They share the workspace's managed or BYOC storage configuration, but their storage allowance, retention, and cleanup are separate from cache. Their storage requests count toward the plan's shared build-storage request allowance.

Use cache for reusable state

Dependencies and intermediate build state may be reclaimed by unused-cache retention or capacity pressure.

Use artifacts for outputs

Each upload gets an immutable art_... ID and stays available until its selected expiry or an explicit delete.

Native CLI

Push one or more files, directories, or quoted glob patterns. Multiple roots use one deterministic tar archive. Automatic compression samples a file's bytes and compresses archives; choose --compression zstd or --compression none to override it. Dot-prefixed paths are excluded by default, and --include-hidden is explicit.

boringcache artifact push dist/ --name release-linux
boringcache artifact push "dist/*.whl" checksums.txt --name python-release
boringcache artifact list
boringcache artifact show art_0123456789abcdef01234567
boringcache artifact pull art_0123456789abcdef01234567 ./release
boringcache artifact delete art_0123456789abcdef01234567

Upload and download bodies go directly between the CLI and object storage. Large archives are produced while their parts upload; rerunning the same command resumes provider-confirmed parts after an interruption. Rails handles authorization and metadata, and the CLI verifies the representation SHA-256 before atomically publishing a file or extracted directory. One artifact may store at most 10 GiB.

Publish files at public paths

Any workspace can publish one file at an immutable path on its public HTTPS origin. Configure the origin in Workspace storage settings, then publish with an admin token or a publish-capable workload identity.

boringcache artifact publish dist/tool-linux-amd64   --path releases/tool/v1.2.3/tool-linux-amd64   --content-type application/octet-stream   --workspace team/releases

The CLI computes the SHA-256 before reservation, uploads the file once with a provider checksum and create-only condition, verifies the signed publication receipt, then checks the public object's size and immutable cache headers. Add --verify-download to download and hash the public object. Rerunning the same command recovers the same path when the bytes and media type match. A different file at that path fails with a conflict.

The public origin can be the provider domain or a custom domain. BoringCache stores the exact resulting URL and prevents origin changes after the first public path is reserved.

For managed storage, BoringCache keeps the Tigris bucket private, enables per-object access, and configures the custom domain through Tigris. For BYOC, configure public reads, DNS, TLS, and delete protection with your provider, and keep the Cache and private Artifact prefixes out of the public-read policy. BoringCache rejects publication paths inside those prefixes, but your provider controls whether existing objects are public.

Published files are permanent, cannot be deleted through the Artifact API, use Cache-Control: public, max-age=31536000, immutable, no-transform, and may be at most 5 GiB.

Upload and download with BoringCache One

Use the same Action for cache and immutable build outputs. Artifact transfers run directly on GitHub-hosted runners. Connect the repository through Connect CI and grant the job id-token: write, or supply your workspace's split credentials.

.github/workflows/ci.yml

- uses: boringcache/one@f0fb9b2d926a32b10c543e92093ba00c5a291b79 # v1.33.0
  id: upload
  with:
    mode: artifact
    artifact-command: push
    artifact-path: dist/
    artifact-name: release
    artifact-retention-days: 7
    trust-policy: auto

- uses: boringcache/one@f0fb9b2d926a32b10c543e92093ba00c5a291b79 # v1.33.0
  with:
    mode: artifact
    artifact-command: pull
    artifact-id: ${{ steps.upload.outputs.artifact-id }}
    artifact-path: restored/
    trust-policy: restore

Uploads return an immutable artifact-id and a content artifact-digest. Pass the ID through job outputs to download in another job. You can also pull by artifact-name within the same workflow run and attempt; duplicate names fail. Pull treats artifact-path as the exact destination file or directory and never replaces an existing destination. The artifact-download-path output gives the completed download location.

Workspace resolution follows the CLI; artifact-workspace selects an explicit workspace and must match an active Machine connection. Upload excludes dot-prefixed paths unless artifact-include-hidden: true. Artifact errors fail the step, and uploads require write authority: trust-policy: auto is restore-only on pull requests. This mode needs no mode: gha setup step.

Existing GitHub Artifact actions

On a runner integrated with BoringCache GHA, the official upload and download actions stay unchanged. The runner starts boringcache gha before the job, and their standard ArtifactService requests become first-class BoringCache Artifacts.

.github/workflows/ci.yml

- uses: actions/upload-artifact@v4
  with:
    name: release-linux
    path: dist/

- uses: actions/download-artifact@v4
  with:
    name: release-linux
    path: restored/

A workflow setup step cannot replace the endpoint GitHub injects into provider actions on a standard GitHub-hosted runner; those actions remain GitHub-backed. Use the native Artifact commands above when BoringCache must own build outputs there.

Retention and trust

The workspace default is 90 days. A timed upload may select 1–400 days. Administrators may choose permanent retention, which means no automatic expiry—not protection from explicit deletion.

A stage, save, or admin token can upload. Restore tokens can list, inspect, and download. Only administrators can delete native artifacts or extend retention beyond the workspace default.

Repository, run, and job fields are shown as Build context. They describe what the authenticated uploader reported; they are not a cryptographic attestation.

After storage verification, BoringCache signs an in-toto Statement in a DSSE publication receipt that binds the Artifact ID, exact digests, representation, sizes, and authenticated workload identity when available. artifact push and artifact pull verify the receipt automatically. Older Artifacts without a receipt remain usable with a warning. Set BORINGCACHE_TRUSTED_WORKSPACE_KEY_FINGERPRINT when the workspace key must be pinned independently.

The publication receipt proves which bytes BoringCache accepted and which workspace key signed that record. It does not describe how the artifact was built or what it contains. Build provenance and SBOM attestations remain separate evidence bound to the Artifact digest.

With a pinned publisher policy, native artifact pull verifies the producer attestation against the stored representation digest before downloading. The GitHub Actions compatibility service verifies the complete download before issuing its local URL. See the publisher policy.

You can upload a release directory containing your build output, Cosign bundle, SBOM, and provenance files. Download that Artifact by its ID, then verify the output with your own signing tools and identity policy. See Cosign’s signing and verification guide.

Need help or found something unclear? Open an issue or browse the CLI repo.