Skip to content
Documentation

Docs / Artifacts

Artifacts

Artifacts store immutable build outputs with explicit retention and verified downloads. Their lifecycle is separate from cache.

Artifacts and cache

Artifacts are immutable outputs such as binaries, test reports, coverage bundles, static sites, and deployment packages. Choose managed or BYOC storage in Artifacts → Storage. Managed Artifact bytes count toward the namespace's shared storage pool, including any extra capacity from its budget. Standard and Large admins set that budget in Billing; it defaults to $0. BYOC Artifact bytes have no BoringCache capacity limit; your provider supplies their storage capacity. Artifact retention and cleanup are separate from Cache. Storage requests count toward the plan's shared build-storage request allowance.

Cache: reusable build state

Dependencies and intermediate build state are removed after going unused for the retention period. When confirmed usage reaches the namespace allowance, new uploads stop. Existing uploads can finish and stored content can be reused.

Artifacts: build 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.

Public file publishing

Any workspace can publish one file at an immutable path on its public HTTPS origin. Choose the public domain in Artifacts → Custom domain, 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.

With managed storage, use the BoringCache address shown in Artifacts → Custom domain or enter your own domain. BoringCache configures the domain and HTTPS. For your own domain, copy the exact CNAME target shown in Artifacts → Custom domain and point your download domain's CNAME to it. The target identifies your Artifact storage; use the hostname without https:// or a path. Save your public HTTPS address, such as https://downloads.example.com, without a file path. Storage domain configuration must be confirmed before publication.

With BYOC, you manage the public domain, DNS, HTTPS and public-read policy with your provider. Keep Cache and private Artifact paths protected. BoringCache rejects publication paths inside those prefixes, but your provider controls which objects are public.

Artifacts → Storage shows locations retained by existing Artifacts and publications, including their bucket or container and saved public download address. Storage for new private uploads is configured separately. Existing publications retain their storage and URLs.

The public domain is the address people use to download published files. Private uploads do not become public when you save these settings. BoringCache stores each publication's exact URL; its domain cannot change after the first public path is reserved.

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.

Completing a publication under releases/<product>/<tag>/, such as releases/tool/v1.2.3/tool.tar.zst, creates its release group automatically. Product and tag names may each contain up to 128 characters. In Artifacts → Publications, workspace managers can edit the title and Markdown notes or create a group with another publication path prefix. Existing and future public files under that directory appear together. Publish each file with the same artifact publish command and a path under the prefix.

An unfinished upload reserves its public path. Retry publishing the same file to complete it. If the upload failed and its signed upload request has expired, a workspace manager can select Release public path in Artifacts → Settings. BoringCache releases the path only after checking that no object is stored there. Completed publications cannot be released.

Release groups organize the workspace view. Changing a group's tag, notes or prefix, or removing the group, does not change published files, download URLs or signed receipts. Use All files to find standalone publications. Notes support headings, lists, links and fenced code blocks; HTML and images are not rendered.

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@1781572d7b3ec5aef652f8ba479b981439b2776b # v1.48.2
  id: upload
  with:
    mode: artifact
    artifact-command: push
    artifact-path: dist/
    artifact-name: release
    artifact-retention-days: 7
    trust-policy: auto

- uses: boringcache/one@1781572d7b3ec5aef652f8ba479b981439b2776b # v1.48.2
  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.

Trial expiry overrides Artifact retention. Without a paid subscription, remaining managed Artifacts are scheduled for deletion seven days after the 30-day trial ends, including permanent Artifacts and published files. Copies already downloaded or cached elsewhere are outside this cleanup. See the trial policy.

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.