Ruby

Publish a package

The following subsections describe the processes in the code boxes above.

Using a single command

The following gem command (modified as required before submitting) describes the process for publishing a package to your Ruby registry:

GEM_HOST_API_KEY="registry-write-token" gem push --host="https://buildkitepackages.com/{org.slug}/{registry.name}" *.gem

where:

• registry-write-token is the Buildkite Packages-generated API token required to publish/upload packages to your Ruby registry.

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

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

Using configuration files

This option allows you to use simpler gem commands to publish your Ruby (gem) packages after implementing the required configuration file changes:

1. Copy the following set of commands, paste them and modify as required before submitting to create your ~/.gem/credentials file:

   mkdir ~/.gem
   touch ~/.gem/credentials
   chmod 600 ~/.gem/credentials
   echo "https://buildkitepackages.com/{org.slug}/{registry.name}: registry-write-token" >> ~/.gem/credentials
   

   where:

   • {org.slug} can be obtained from the end of your Buildkite URL, after accessing Pipelines in the global navigation of your organization in Buildkite.
   • {registry.name} is the name of your Ruby registry.
   • registry-write-token is the Buildkite Packages-generated API token required to publish/upload packages to your Ruby registry.

   Note: This step only needs to be conducted once for the life of your Ruby registry.

2. 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://buildkitepackages.com/{org.slug}/{registry.name}"
   

   Note: This configuration prevents your Ruby package accidentally being published to the main RubyGems registry.

3. Publish your Ruby (gem) 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 using the Packages section of your Ruby registry page.

To access your Ruby package's details page:

1. Select Packages in the global navigation to access the Registries page.
2. Select your Ruby registry on this page.
3. On your Ruby registry page, select the package within the Packages 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 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.

• Last pushed: the date when the last package was uploaded to the 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:

1. Access the package's details.
2. 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:

1. Access the package's details.
2. Ensure the Installation > Installation instructions section is displayed.
3. Copy the command in the code snippet, paste it into your terminal, and submit it.

This code snippet is based on this format:

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

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 the Buildkite Packages-generated API token required to download packages from your Ruby registry. This URL component, along with the following @ are not required for registries that are publicly accessible.

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

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