Configure authentication to Artifact Registry for Ruby gem repositories

This page describes how to configure authentication with an Artifact Registry Ruby gem repository.

You must authenticate to Artifact Registry when you use a third-party application to connect to a repository.

You don't need to configure authentication for Cloud Build or Google Cloud runtime environments such as Google Kubernetes Engine and Cloud Run.

Before you begin

  1. If the target repository doesn't exist, create a Ruby gem repository.
  2. Verify that Ruby is installed. For installation instructions, see the Google Cloud tutorial for setting up Ruby.
  3. Verify that the user account or service account you are using has the required permissions to access the repository.

  4. Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command: 

    gcloud init

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  5. (Optional) Configure defaults for gcloud CLI commands.

Overview

Ruby supports two methods for authenticating requests to your Artifact Registry repository:

  • RubyGems CLI: Supports push and pull requests. This CLI is available with Ruby by default. When you authenticate with RubyGems, you must authenticate each time you make a push or pull request to your repository.

  • Bundler CLI: Supports pull requests. Bundler stores packages and upstreams in a gemfile, which allows users to standardize setups across multiple machines without needing to authenticate each individual pull request. However, you must still reauthenticate your credentials to Bundler occasionally.

    To install the Bundler CLI, enter gem install bundler.

Authenticate with the RubyGems CLI

The RubyGems CLI uses OAuth2 tokens to authenticate a request. To pass OAuth2 tokens to calls to your Artifact Registry repositories, you must first generate the token and then pass it with the address of your repository when you make a request. Tokens have a one-hour lifespan and must be refreshed hourly.

Authenticate pull requests

You can authenticate a pull request in the Google Cloud CLI command line or by updating your .gemrc file.

Authenticate pull requests in the command line

To authenticate for the latest version of the gem in your pull request, run the following command:

export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
gem install GEM_NAME --source https://$GEM_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

To authenticate for a specific gem version, add -v GEM_VERSION to the gem install command.

Where:

  • GEM_NAME is the name of the gem for which the request is made.
  • LOCATION is the regional or multi-regional location for the repository.
  • PROJECT is the ID of the project containing the repository.
  • REPOSITORY is the ID of the repository.

Authenticate in a .gemrc file

You can configure your global or project-specific /.gemrc file to authenticate to your sources on pull requests by adding the following:

# File: ~/.gemrc

# Use the GEM_TOKEN retrieved from export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

<...>
:sources:
    - https://GEM_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPO/
<...>

To install a gem using the source or sources defined in your /.gemrc file, run:

gem install GEM_NAME

Authenticate push requests

You can authenticate a push request in the Google Cloud CLI command line or by updating your credentials file.

Authenticate push requests in the command line

To authenticate your push request, run the following command:

export GEM_HOST_API_KEY="Bearer $(gcloud auth print-access-token)"
gem push GEM_NAME --host https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

Where:

  • GEM_NAME is the name of the gem for which the request is made.
  • LOCATION is the regional or multi-regional location for the repository.
  • PROJECT is the ID of the project containing the repository.
  • REPOSITORY is the ID of the repository.

Authenticate push requests in a credentials file

The gem command line tool uses the ~/.gem/credentials file to store API keys for pushing and pulling gems. To configure your credentials file to authenticate to your sources on push requests, do the following:

  1. Generate an OAuth2 access token by running the following command:

    gcloud auth print-access-token

    This token acts as your API key for Artifact Registry.

  2. Update your credentials file:

    1. Open ~/.gem/credentials and add a line for your repository. The key is your repository URL, and the value is Bearer, followed by your token:

      :rubygems_api_key: RUBYGEMS_ORG_KEY
https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY: Bearer OAUTH_TOKEN

      Where:

      • RUBYGEMS_ORG_KEY is the API key for RubyGems.org.
      • LOCATION is the regional or multi-regional location for the repository.
      • PROJECT is the ID of the project containing the repository.
      • REPOSITORY is the ID of the repository.
      • OAUTH_TOKEN is your OAuth2 access token.

    2. Push your gem. Note that you don't need to set the GEM_HOST_API_KEY, as you have already defined the key in your credentials file.

      gem push GEM_NAME --host https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

Authenticate with Bundler

The Ruby Bundler manages application dependencies across one or more gems. To set up Bundler, do the following:

  1. Add the address of your repository as a source in your gemfile:

    # Gemfile
# <...>
source "https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY"

  2. Authenticate to your repository by using bundle config:

    export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
export HOST="https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY"
bundle config $HOST $GEM_TOKEN

Where:

  • LOCATION is the regional or multi-regional location for the repository.
  • PROJECT is the project ID. If this flag is omitted, the current or default project is used.
  • REPOSITORY is the ID of the repository. If you configured a default Artifact Registry repository, it is used when this flag is omitted from the command.

You will need to reauthenticate to your remote repository occasionally. In this event, run the same authentication command from Step 2.

For more information about configuring Bundler, see Gemfiles in the bundler.io documentation.

What's next