Documentation
Docs / Bring your own storage
Bring your own storage
Connect an S3-compatible bucket or Azure Blob container for Cache and Artifacts. Runners use short-lived object URLs.
Connect your storage
Security boundary
Use one private bucket or Azure Blob container dedicated to a workspace's Cache and Artifacts. Registry storage remains managed by BoringCache. BoringCache encrypts the storage credential and gives runners short-lived object URLs; runners do not receive the bucket or account key.
Private Cache and Artifact operations use the workspace's generated prefixes. BoringCache does not create BYOC buckets or containers, change their access policy, or manage provider lifecycle rules. Optional public-file publication uses the exact path you choose outside those private prefixes and requires a separately configured public origin.
Amazon S3: use an IAM role
The recommended AWS connection stores only your role ARN. Create an IAM role in your AWS account using the trust policy and external ID shown in workspace settings, attach the generated permissions policy, then paste the role ARN into BoringCache.
BoringCache assumes the role for one hour and uses the resulting temporary credentials to sign storage requests. Presigned runner URLs expire within 45 minutes. The external ID is unique to the workspace and prevents one BoringCache customer from asking the service to assume another customer's role.
Keep the generated policy attached to the role so you retain control of its maximum access. See AWS guidance for third-party access. If the bucket uses a customer-managed KMS key, also grant the role kms:GenerateDataKey and kms:Decrypt on that key.
Azure Blob Storage
Use CLI 1.32.0 or later for Azure block uploads. In Workspace storage settings, select Azure Blob Storage and enter the container, storage account name, and account key. This connection uses Azure's native Blob API.
Use a dedicated storage account with HTTPS required and public blob access disabled. The account key grants access to the full account, even when BoringCache uses only one container. Runners receive short-lived, object-specific SAS URLs. Microsoft Entra ID and user-delegation SAS authentication are not supported by this connection.
For rotation, switch BoringCache to the account's other key and verify access before regenerating the old key. Existing SAS URLs signed by the old key stop working when it is regenerated, so allow active transfers to finish. Follow Microsoft's account-key rotation instructions.
Other S3-compatible providers
The portable connection uses the provider's S3 access ID and secret. Create a separate identity for BoringCache and scope it as narrowly as the provider allows.
| Provider | Recommended identity | Scope |
|---|---|---|
| Google Cloud Storage | Service-account HMAC key | Grant object read, create, list, and delete permissions on this bucket. |
| Cloudflare R2 | R2 API token | Choose Object Read & Write and apply it to this bucket only. |
| MinIO | Service account | Attach the generated S3 policy shown in workspace settings. |
| Wasabi | Dedicated sub-user key | Attach the generated S3 policy shown in workspace settings. |
| Backblaze B2 | Application key | Limit it to this bucket and workspace prefix with list, read, write, and delete capabilities. |
| DigitalOcean Spaces | Limited-access key | Choose this bucket with Read/Write/Delete. Do not combine it with a bucket policy. |
Verify before builds use it
Saving a new or changed connection automatically checks write, read, prefix list, delete, and multipart access. S3-compatible providers use a multipart create/list/abort check. Azure uploads and lists an uncommitted block; Azure handles cleanup because it has no equivalent multipart abort operation. BoringCache saves the connection even when verification fails so you can correct the provider policy without re-entering the setup.
Rotate an access key by entering the replacement pair and saving again. AWS role connections rotate automatically through temporary sessions; update the role's trust or permissions in AWS when you need to revoke access.
Need help or found something unclear? Open an issue or browse the CLI repo.