Ruby

Buildkite Package Registries provides registry support for Ruby-based (RubyGems) packages.

Once your Ruby registry has been created, you can publish/upload packages (generated from your application's build) to this registry via a single command, or by configuring your ~/.gem/credentials and gemspec files with the code snippets presented on your Ruby registry's details page.

To view and copy the required command or ~/.gem/credentials and gemspec configurations:

Select Package Registries in the global navigation to access the Registries page.
Select your Ruby registry on this page.
Select Publish a Ruby Package and in the resulting dialog, use the copy icon at the top-right of the relevant code box to copy its snippet and paste it into your command line tool or the appropriate file.

These file configurations contain the following:

~/.gem/credentials: the URL for your specific Ruby registry in Buildkite and the API access token required to publish the package to this registry.
gemspec: the URL for your specific Ruby registry in Buildkite.

Publish a package

The following subsections describe the processes in the code boxes above, serving the following use cases:

Single command—for rapid RubyGems package publishing, using a temporary token.
Ongoing publishing—implements configurations for a more permanent RubyGems package publishing solution.

Single command

The first code box provides a quick mechanism for uploading RubyGems package to your Ruby registry.

GEM_HOST_API_KEY="temporary-write-token-that-expires-after-5-minutes" \
  gem push --host="https://packages.buildkite.com/{org.slug}/{registry.slug}" *.gem

where:

{org.slug} can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite.

{registry.slug} is the slug of your Ruby registry, which is the kebab-case version of your Ruby registry name, and can be obtained after accessing Package Registries in the global navigation > your Ruby registry from the Registries page.

Since the temporary-write-token-that-expires-after-5-minutes expires quickly, it is recommended that you just copy this command directly from the Publish a Ruby Package dialog.

Ongoing publishing

The remaining code boxes on the Publish a Ruby Package dialog provide configurations for a more permanent solution for ongoing RubyGems uploads to your Ruby registry.

Copy the following set of commands, paste them and modify as required before running to create your ~/.gem/credentials file:
```
mkdir ~/.gem
touch ~/.gem/credentials
chmod 600 ~/.gem/credentials
echo "https://packages.buildkite.com/{org.slug}/{registry.slug}: registry-write-token" >> ~/.gem/credentials
```
where:
- {org.slug} can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite.
- {registry.slug} is the slug of your Ruby registry, which is the kebab-case version of your Ruby registry name, and can be obtained after accessing Package Registries in the global navigation > your Ruby registry from the Registries page.
- registry-write-token is your API access token used to publish/upload packages to your Ruby registry. Ensure this access token has the Read Packages and Write Packages REST API scopes, which allows this token to publish packages to any registry your user account has access to within your Buildkite organization.
Note: This step only needs to be conducted once for the life of your Ruby registry.
Copy the following code snippet and paste it to modify the allowed_push_host line of your Ruby (gem) package's .gemspec file:
```
spec.metadata["allowed_push_host"] = "https://packages.buildkite.com/{org.slug}/{registry.slug}"
```
Note: This configuration prevents your Ruby package accidentally being published to the main RubyGems registry.
Publish your Ruby (RubyGems) package:
```
gem build *.gemspec
gem push *.gem
```
Alternatively, if you are using a Ruby (gem) package created with Bundler, publish the package this way:
```
rake release
```

Access a package's details

A Ruby package's details can be accessed from this registry through the Releases (tab) section of your Ruby registry page.

To access your Ruby package's details page:

Select Package Registries in the global navigation to access the Registries page.
Select your Ruby registry on this page.
On your Ruby registry page, select the package within the Releases (tab) section. The package's details page is displayed.

The package's details page provides the following information in the following sections:

Installation (tab): the installation instructions.
Contents (tab, where available): a list of directories and files contained within the package.
Details (tab): a list of checksum values for this package—MD5, SHA1, SHA256, and SHA512.
About this version: a brief (metadata) description about the package.
Details: details about:
- the name of the package (typically the file name excluding any version details and extension).
- the package version.
- the source registry the package is located in.
- the package's visibility (based on its registry's visibility)—whether the package is Private and requires authentication to access, or is publicly accessible.
- the distribution name / version.
- additional optional metadata contained within the package, such as a homepage, licenses, etc.
Pushed: the date when the last package was uploaded to the source registry.
Total files: the total number of files (and directories) within the package.
Dependencies: the number of dependency packages required by this package.
Package size: the storage size (in bytes) of this package.
Downloads: the number of times this package has been downloaded.

A Ruby registry's package also has a Dependencies tab, which lists other RubyGems gem packages that your currently viewed Ruby gem package has dependencies on.

Downloading a package

A Ruby package can be downloaded from the package's details page.

To download a package:

Access the package's details.
Select Download.

Installing a package

A Ruby package can be installed using code snippet details provided on the package's details page.

To install a package:

Access the package's details.
Ensure the Installation > Instructions section is displayed.
Copy the command in the code snippet, paste it into your terminal, and run it.

This code snippet is based on this format:

gem install gem-package-name -v version.number \
  --clear-sources --source https://buildkite:{registry.read.token}@packages.buildkite.com/{org.slug}/{registry.slug}

where:

gem-package-name is the name of your RubyGems gem package.
version.number is the version of your RubyGems gem package
{registry.read.token} is your API access token or registry token used to download packages to your Ruby registry. Ensure this access token has the Read Packages REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization. This URL component, along with its surrounding buildkite: and @ components are not required for registries that are publicly accessible.

{org.slug} can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite.

{registry.slug} is the name of your Ruby registry.