Manage registries

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

Buildkite Package Registries allows you to create source registries.

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 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 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 link such as s3://… or gs://…) 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.

Configure registry tokens

Registry tokens are long-lived read only tokens configurable for a private source 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 registry:

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

  2. Select the private source 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 registries.

Deleting a source registry permanently deletes all packages contained within it.

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.