Configure authentication to Artifact Registry for Ruby gem repositories

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

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

You don't need to configure authentication for Cloud Build or Google Cloudruntime 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 theGoogle Cloudtutorial for setting up Ruby.
  3. Verify that the user account or service account you are using has therequiredpermissions to access therepository.

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

    gcloudinit

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

    Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
  5. (Optional)Configure defaults for gcloud CLI commands.

Overview

Ruby supports two methods for authenticating requests to your Artifact Registryrepository:

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

  • Bundler CLI: Supports pull requests. Bundler storespackages and upstreams ina gemfile, which allows users to standardize setups across multiple machineswithout needing to authenticate each individual pull request. However,you must still reauthenticate your credentials to Bundler occasionally.

    To install the Bundler CLI, entergem 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 mustfirstgenerate the tokenand then pass it with the address of your repository when you make arequest. 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 byupdating your.gemrc file.

Authenticate pull requests in the command line

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

exportGEM_TOKEN="oauth2accesstoken:$(gcloudauthprint-access-token)"geminstallGEM_NAME--sourcehttps://$GEM_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

To authenticate for a specific gem version, add-vGEM_VERSION to thegem install command.

Where:

  • GEM_NAME is the name of the gem for which the request is made.
  • LOCATION is the regional or multi-regionallocation 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 authenticateto 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:

geminstallGEM_NAME

Authenticate push requests

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

Authenticate push requests in the command line

To authenticate your push request, run the following command:

exportGEM_HOST_API_KEY="Bearer$(gcloudauthprint-access-token)"gempushGEM_NAME--hosthttps://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY
Note: AfterGEM_HOST_API_KEY has been defined, push requests don't needto pass the OAuth2 token in the URL.

Where:

Authenticate push requests in a credentials file

Thegem command line tool uses the~/.gem/credentials file to store API keysfor pushing and pulling gems. To configure your credentials file toauthenticate 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 keyis your repository URL, and the value isBearer, followed by your token:

      :rubygems_api_key:RUBYGEMS_ORG_KEYhttps://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY:BearerOAUTH_TOKEN

      Where:

      • RUBYGEMS_ORG_KEY is the API key forRubyGems.org.
      • LOCATION is the regional or multi-regionallocation 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 theGEM_HOST_API_KEY,as you have already defined the key in your credentials file.

      gempushGEM_NAME--hosthttps://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

Authenticate with Bundler

The RubyBundler manages application dependenciesacross one or more gems. To set up Bundler, do the following:

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

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

  2. Authenticate to your repository by usingbundle config:

    exportGEM_TOKEN="oauth2accesstoken:$(gcloudauthprint-access-token)"exportHOST="https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY"bundleconfig$HOST$GEM_TOKEN

Where:

  • LOCATION is the regional or multi-regionallocation for the repository.
  • PROJECT is the project ID. If this flag is omitted,the current ordefault project is used.
  • REPOSITORY is the ID of the repository. If you configured adefault Artifact Registryrepository, it is used when this flag is omitted from the command.

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

For more information about configuring Bundler,seeGemfiles in the bundler.iodocumentation.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.