Manage registries

This page provides details on how to manage registries within your Buildkite organization.

Buildkite Package Registries allows you to create two types of registries: source and composite.

Create a source registry

A source registry is a basic type of registry used for publishing and installing packages. A source registry stores package files, which are either hosted by Buildkite or in your own private storage.

New source registries can be created through the Registries page of the Buildkite / Package Registries interface.

To create a new source registry:

  1. Select Package Registries in the global navigation to access the Registries page.

    Note: Any previously created registries are listed and can be accessed from this page.

  2. Select New registry > Source Registry.

  3. On the New Registry page, enter the mandatory Name for your registry.

  4. Enter an optional Description for the registry. This description appears under the name of the registry item on the Registries page.

  5. Select the required registry Ecosystem based on the package ecosystem for this new registry.

  6. If your Buildkite organization has the teams feature enabled, select the relevant Teams to be granted access to the new registry.

  7. Select Create Registry.

    The new registry's details page is displayed. Selecting Package Registries in the global navigation opens the Registries page, where your new registry will be listed.

Manage packages in a source registry

Once a source registry has been created, packages can then be uploaded to it. Learn more about how to manage packages for your registry's relevant language and package ecosystem:

Update a source registry

Source registries can be updated using the Registries page of the Buildkite / Package Registries interface, which lists all previously created source and composite registries.

The following aspects of a source registry can be updated:

  • Name: be aware that changing this value will also change the URL, which in turn will break any existing installations that use this registry.
  • Description
  • Emoji: to change the emoji of the registry from the default provided when the source or composite registry was created. The emoji appears next to the registry's name.
  • Color: the background color for the emoji
  • Registry Management: the privacy settings for the registry—private (the initial default state for all newly created registries) or public.
  • OIDC Policy: one or more policies defining which OpenID Connect (OIDC) tokens, from the Buildkite Agent or another third-party system, can be used to either publish/upload packages to the registry, or download/install packages from the registry.
  • Tokens (private registries only): one or more registry tokens, which are an alternative to API access tokens.

A source registry's ecosystem type cannot be changed once the registry is created.

To update a source registry:

  1. Select Package Registries in the global navigation to access the Registries page.

  2. Select the source registry to update on this page.

  3. Select Settings and on the General (Settings) page, update the following fields as required:

    • Name: being aware of the consequences described above
    • Description: appears under the name of the registry item on the Registries page, and on the registry's details page
    • Emoji and Color: the emoji appears next to the registry's name and the color (in hex code syntax, for example, #FFE0F1) provides the background color for this emoji
    • Registry Management > Make registry public or Make registry private: select either of these buttons to make the registry public or revert it back to its private state—the existing wording on this button indicates the current state, and if the registry is public, the word Public is indicated explicitly next to the registry's name in the Buildkite interface.

  4. Select Update Registry to save your changes.

    The registry's updates will appear on the Registries page, as well as the registry's details page.

  5. If the registry's OIDC policy needs to be configured, learn more about this in OIDC in Buildkite Package Registries.

  6. If the registry is private and registry tokens (an alternative to API access tokens) need to be configured, learn more about this in Configure registry tokens.

  7. If private storage has been configured and linked to your Buildkite organization, the storage location for the registry can be changed. Learn more about this in Configure registry storage.

Configure registry storage

When a new source registry is created, it automatically uses the default Buildkite Package Registries storage location. However, your new source registry's default storage location can be overridden to use another configured storage location. Learn more about configuring private storage in Private storage links.

To configure/change your source registry's current storage:

  1. Select Package Registries in the global navigation to access the Registries page.

  2. Select the source registry whose storage requires configuring.

  3. Select Settings > Storage to access the source registry's Storage page.

  4. Select Change to switch from using Buildkite-hosted storage (or a previously configured private storage beginning with s3://...) to your new private storage link. If this setting is currently configured to use a previously configured private storage link, the storage location can also be reverted back to using Buildkite-hosted storage.

All subsequent packages published to this source registry will be stored in your newly configured storage location. Bear in mind that all existing packages in this registry will remain in their original storage location.

Composite registries

A composite registry is a Buildkite registry type that consists of one or more source registries (referred to as upstreams or upstream registries) that belong to a specific package ecosystem, can include the ecosystem's official (public) registry, and combines them all into a single virtual registry. Composite registries allow you to centrally manage packages so that they can be downloaded and installed from a single configurable URL using an API access token (with the Read Packages REST API scope), registry token, or temporary token available through the composite registry's Setup & Usage page.

This means that your projects only need to be configured with a single composite registry URL (one for each package ecosystem), to download and install the packages they need. Each upstream providing these packages can be configured separately through the composite registry itself.

A composite registry is always private. However, its upstreams can either be private or publicly accessible. Some private source registries may not be accessible to certain users within your Buildkite organization, due to team- or registry-level permissions applied to these registries, or both. Regardless of these permissions, if such private source registries and those with user-restricted access are configured as upstreams of a composite registry, then these source registries' packages can still be downloaded and installed by any user with access to this composite registry, through the composite registry's URL. Therefore, when configuring a composite registry's upstreams, be aware of the security implications around this user access.

Currently, the composite registries feature only supports the Java, JavaScript and Python package ecosystems.

Create a composite registry

New composite registries can be created through the Registries page of the Buildkite / Package Registries interface.

To create a new composite registry:

  1. Select Package Registries in the global navigation to access the Registries page.

    Note: Any previously created registries are listed and can be accessed from this page.

  2. Select New registry > Composite Registry.

  3. On the New Composite Registry page, enter the mandatory Name for your registry.

  4. Enter an optional Description for the registry. This description appears under the name of the registry item on the Registries page.

  5. Select the required registry Ecosystem based on the package ecosystem for this new registry.

  6. To allow your composite registry to download packages from your chosen package ecosystem's official public registry, select Add official registry? Doing this allows packages from one of the following official registries to be downloaded and installed through your composite registry's URL, based on your composite registry's package ecosystem:

  7. If your Buildkite organization has the teams feature enabled, select the relevant Teams to be granted access to the new registry.

  8. Select Create Registry.

    The new registry's details page is displayed. Selecting Package Registries in the global navigation opens the Registries page, where your new registry will be listed.

Edit a composite registry's upstreams and official registry

When a composite registry is created, it has no configured source registries as upstreams. The only registry that may be configured is one of the official public registries, based on your composite registry's package ecosystem:

Package Registries allows you to configure any of your Buildkite organization's currently available source registries that match your composite registry's package ecosystem, as upstreams. When viewing a composite registry, you can edit these upstreams by adding them to or removing them from your composite registry, as well as enabling or disabling the official public registry for your composite registry's package ecosystem.

Add or remove upstreams

To add upstreams to or remove them from your composite registry:

  1. Select Package Registries in the global navigation to access the Registries page.

  2. Select the composite registry whose upstreams are to be added or removed.

  3. Ensure the Upstreams tab is selected and select the Edit upstreams button.

    A list of all source registries available in your Buildkite organization matching your composite registry's package ecosystem, appears in a side panel. Any source registries already configured as upstreams in the composite registry are associated with a Remove button.

  4. To add one or more upstreams, select their Add button in the side panel.

  5. To remove one or more upstreams, select their Remove button in the side panel.

  6. Once done, select the X in the side panel to close it.

Enable or disable the official registry

To enable or disable access to the official public registry through your composite registry:

  1. Select Package Registries in the global navigation to access the Registries page.

  2. Select the composite registry whose official public registry is to be enabled or disabled.

  3. Ensure the Upstreams tab is selected, and in the Official registries section, select Enable to enable access to the official public registry for the composite registry's package ecosystem, or Disable to disable access to this official public registry.

Update a composite registry

Composite registries can be updated using the Registries page of the Buildkite / Package Registries interface, which lists all previously created source and composite registries.

The following aspects of a composite registry can be updated:

  • Name: be aware that changing this value will also change the URL, which in turn will break any existing installations that use this registry.
  • Description
  • Emoji: to change the emoji of the registry from the default provided when the source or composite registry was created. The emoji appears next to the registry's name.
  • Color: the background color for the emoji
  • Tokens (private registries only): one or more registry tokens, which are an alternative to API access tokens.

A composite registry's ecosystem type cannot be changed once the registry is created.

To update a composite registry:

  1. Select Package Registries in the global navigation to access the Registries page.

  2. Select the composite registry to update on this page.

  3. Select Settings and on the General (Settings) page, update the following fields as required:

    • Name: being aware of the consequences described above
    • Description: appears under the name of the registry item on the Registries page, and on the registry's details page
    • Emoji and Color: the emoji appears next to the registry's name and the color (in hex code syntax, for example, #FFE0F1) provides the background color for this emoji

  4. Select Update Registry to save your changes.

    The registry's updates will appear on the Registries page, as well as the registry's details page.

  5. If the registry's OIDC policy needs to be configured, learn more about this in OIDC in Buildkite Package Registries.

  6. If registry tokens (an alternative to API access tokens) need to be configured, learn more about this in Configure registry tokens.

Configure registry tokens

Registry tokens are long-lived read only tokens configurable for a private source registry or composite registry, which allow you download and install packages from that registry, acting as an alternative to (and without having to use) a user account-based API access token with the Read Packages REST API scope.

To configure registry tokens for a private source or composite registry:

  1. Select Package Registries in the global navigation to access the Registries page.

  2. Select the private source or composite registry whose registry tokens require configuring.

  3. Select Settings > Tokens to access the registry's Tokens page, where you can:

    • Create a new registry token. To do this:
      1. Select Create Registry Token.
      2. Enter a Description for this new token.
      3. Select Create.
    • Select the copy, view, Edit description or Delete token button associated with any existing token on this page, to perform that action on the token.

Unlike other tokens generated elsewhere in Buildkite, registry tokens can continue to be viewed and copied in their entirety on multiple occasions after their creation. This registry tokens feature (the Tokens page) is not accessible while a registry is public. However, any registry tokens that were created before a registry is made public, will become accessible again when the registry is made private.

Delete a registry

Any type of registry can be deleted using the Registries page of the Buildkite / Package Registries interface, which lists all previously created source and composite registries.

Deleting:

  • A source registry permanently deletes all packages contained within it.
  • A composite registry will prevent any projects configured with it from downloading and installing packages from this registry.

To delete a registry:

  1. Select Package Registries in the global navigation to access the Registries page.
  2. Select the registry to delete on this page.
  3. Select Settings to open the General (Settings) page.
  4. Under Registry Management, select Delete Registry.
  5. In the confirmation dialog, enter the name of the registry, exactly as it is presented, and select Delete Registry.

Audit logging

All events performed through Buildkite Package Registries are logged through the Buildkite organization's Audit Log feature.