Grouping and hierarchy for cached objects and settings

Projects enable organization and hierarchy of your build caches. Projects are always owned by at least one account scope: either an individual user account, or a tenant organization.

Where Projects fit in

Every cache blob is associated with up to two "projects:" there is the default project, which covers cache blobs with no project set and which models your "global" account cache, and then there are more specific projects, which you can create from your dashboard or the CLI.

When you create a Project within Buildless, you can choose settings which apply to the objects associated with your project. These settings change service behavior when the project is active for a given request.

Project Settings

Projects can customize how a cache behaves. These settings apply only when the project is active for a given cache request cycle.

Access Controls

Projects have several access mode options, one of which may be set at any time:

  • Private: The cache is only visible to the owner, and to accounts added explicitly to the cache. This is the default setting for caches created by individual users. Privileges are managed explicitly.
  • Internal: The cache is visible to the owner, and to users who share an organization tenant. This is the default setting for caches created within tenant organizations. Privileges default to org-wide settings.
  • Public: The cache is visible for read-only access to anyone on the internet, with write access granted according to Internal or Private project rules, based on the account which owns the project. For example, a Public project owned by an organization is read-only for public access, and read/write for org users.


Optionally, your cache project can propagate writes to your global scope. This is a good idea if you plan to share cache objects between related projects.


Cache writes are always authorized.

Public projects are public only for reads, so propagation to your global scope can never be leveraged by outside parties.

Naming & Authorization

Projects have a display name and short name; you typically refer to the project in configurations via the short name. Using a project-level credential automatically activates that project.

Fields on a project

  • Display name: Whatever you want
  • Short name: whatever-you-want

The short name can't change after you create a project, but the display name can change whenever you like.

Authorizing project traffic

Projects can have their own API keys and attached integrations. By default, every project is provisioned with at least one default API key, just like a user or org.

When using project-level API keys, the associated project is automatically made active for that API request.