Configure and use RubyGems and Bundler with CodeArtifact

1. Open the AWS CodeArtifact console at https://console.aws.amazon.com/codesuite/codeartifact/home.

2. In the navigation pane, choose Repositories, and then choose the repository that you want to use for installing or pushing Ruby gems.

3. Choose View connection instructions.

4. Choose your operating system.

5. Choose the Ruby package manager client that you want to configure with your CodeArtifact repository.

6. Follow the generated instructions to configure the package manager client to install Ruby gems from or publish Ruby gems to the repository.

1. In a command line, use the following command to fetch a CodeArtifact authorization token and store it in an environment variable.

   • Replace my_domain with your CodeArtifact domain name.

   • Replace 111122223333 with the AWS account ID of the owner of the domain. If you are accessing a repository in a domain that you own, you don't need to include --domain-owner. For more information, see Cross-account domains.

   macOS and Linux

   export CODEARTIFACT_AUTH_TOKEN=`aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --query authorizationToken --output text`

   Windows

   • Windows (using default command shell):

     for /f %i in ('aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --query authorizationToken --output text') do set CODEARTIFACT_AUTH_TOKEN=%i

   • Windows PowerShell:

     $env:CODEARTIFACT_AUTH_TOKEN = aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --query authorizationToken --output text

2. To publish Ruby gems to your repository, use the following command to fetch your CodeArtifact repository's endpoint and storing it in the RUBYGEMS_HOST environment variable. The gem CLI uses this environment variable to determine where gems are published.

   Note

   Alternatively, instead of using the RUBYGEMS_HOST environment variable, you can provide the repository endpoint with the --host option when using the gem push command.

   • Replace my_domain with your CodeArtifact domain name.

   • Replace 111122223333 with the AWS account ID of the owner of the domain. If you are accessing a repository in a domain that you own, you don't need to include --domain-owner. For more information, see Cross-account domains.

   • Replace my_repo with your CodeArtifact repository name.

   macOS and Linux

   export RUBYGEMS_HOST=`aws codeartifact get-repository-endpoint --domain my_domain --domain-owner 111122223333 --repository my_repo --format ruby --query repositoryEndpoint --output text | sed 's:/*$::'`

   Windows

   The following commands retrieve the repository endpoint, trim the trailing /, then store them in an environment variable.

   • Windows (using default command shell):

     for /f %i in ('aws codeartifact get-repository-endpoint --domain my_domain --domain-owner 111122223333 --repository my_repo --format ruby --query repositoryEndpoint --output text') do set RUBYGEMS_HOST=%i
                                     
     set RUBYGEMS_HOST=%RUBYGEMS_HOST:~0,-1%

   • Windows PowerShell:

     $env:RUBYGEMS_HOST = (aws codeartifact get-repository-endpoint --domain my_domain --domain-owner 111122223333 --repository my_repo --format ruby --query repositoryEndpoint --output text).TrimEnd("/")

   The following URL is an example repository endpoint:

   https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/ruby/my_repo/

   Note

   To use a dualstack endpoint, use the codeartifact.region.on.aws endpoint.

3. To publish Ruby gems to your repository, you must authenticate to CodeArtifact with RubyGems by editing your ~/.gem/credentials file to include your auth token. Create a ~/.gem/ directory and a ~/.gem/credentials file if the directory or file doesn't exist.

   macOS and Linux

   echo ":codeartifact_api_key: Bearer $CODEARTIFACT_AUTH_TOKEN" >> ~/.gem/credentials

   Windows

   • Windows (using default command shell):

     echo :codeartifact_api_key: Bearer %CODEARTIFACT_AUTH_TOKEN% >> %USERPROFILE%/.gem/credentials

   • Windows PowerShell:

     echo ":codeartifact_api_key: Bearer $env:CODEARTIFACT_AUTH_TOKEN" | Add-Content ~/.gem/credentials

4. To use gem to install Ruby gems from your repository, you must add the repository endpoint information and auth token to your .gemrc file. You can add it to the global file (~/.gemrc) or your project .gemrc file. The CodeArtifact information you must add to the .gemrc is a combination of the repository endpoint and auth token. It is formatted as follows:

   https://aws:${CODEARTIFACT_AUTH_TOKEN}@my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/ruby/my_repo/

   • For the authentication token, you can use the CODEARTIFACT_AUTH_TOKEN environment variable that was set in an earlier step.

   • To fetch the repository endpoint, you can read the value of the RUBYGEMS_HOST environment variable that was set earlier, or you can use the following get-repository-endpoint command, replacing the values as necessary:

     aws codeartifact get-repository-endpoint --domain my_domain --domain-owner 111122223333 --repository my_repo --format ruby --query repositoryEndpoint --output text

   After you have the endpoint, use a text editor to add aws:${CODEARTIFACT_AUTH_TOKEN}@ in the appropriate position. Once you have the repository endpoint and auth token string created, add it to the :sources: section of your .gemrc file with the echo command as follows:

   Warning

   CodeArtifact does not support adding repositories as sources using the gem sources -add command. You must add the source directly to the file.

   macOS and Linux

   echo ":sources:
       - https://aws:${CODEARTIFACT_AUTH_TOKEN}@my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/ruby/my_repo/" > ~/.gemrc

   Windows

   • Windows (using default command shell):

     echo ":sources:
         - https://aws:%CODEARTIFACT_AUTH_TOKEN%@my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/ruby/my_repo/" > "%USERPROFILE%\.gemrc"

   • Windows PowerShell:

     echo ":sources:
         - https://aws:$env:CODEARTIFACT_AUTH_TOKEN@my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/ruby/my_repo/" | Add-Content ~/.gemrc

5. To use Bundler, you must configure Bundler with your repository endpoint URL and authentication token by running the following bundle config command:

   macOS and Linux

   bundle config $RUBYGEMS_HOST aws:$CODEARTIFACT_AUTH_TOKEN 

   Windows

   • Windows (using default command shell):

     bundle config %RUBYGEMS_HOST% aws:%CODEARTIFACT_AUTH_TOKEN%

   • Windows PowerShell:

     bundle config $Env:RUBYGEMS_HOST aws:$Env:CODEARTIFACT_AUTH_TOKEN

To install Ruby gems from a CodeArtifact repository with gem

1. If you haven't, follow the steps in Configure RubyGems (gem) and Bundler (bundle) with CodeArtifact to configure the gem CLI to use your CodeArtifact repository with proper credentials.

   Note

   The authorization token generated is valid for 12 hours. You will need to create a new one if 12 hours have passed since a token was created.

2. Use the following command to install Ruby gems from CodeArtifact:

   gem install my_ruby_gem --version 1.0.0

To install Ruby gems from a CodeArtifact repository with bundle

1. If you haven't, follow the steps in Configure RubyGems (gem) and Bundler (bundle) with CodeArtifact to configure the bundle CLI to use your CodeArtifact repository with proper credentials.

   Note

   The authorization token generated is valid for 12 hours. You will need to create a new one if 12 hours have passed since a token was created.

2. Add your CodeArtifact repository endpoint URL to your Gemfile as a source to install configured Ruby gems from your CodeArtifact repository and its upstreams.

   source "https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/ruby/my_repo/"
                   
   gem 'my_ruby_gem'

3. Use the following command to install the Ruby gems as specified in your Gemfile:

   bundle install

1. If you haven't, follow the steps in Configure RubyGems (gem) and Bundler (bundle) with CodeArtifact to configure the gem CLI to use your CodeArtifact repository with proper credentials.

   Note

   The authorization token generated is valid for 12 hours. You will need to create a new one if 12 hours have passed since a token was created.

2. Use the following command to publish Ruby gems to a CodeArtifact repository. Note that if you did not set the RUBYGEMS_HOST environment variable, you must provide your CodeArtifact repository endpoint in the --host option.

   gem push --key codeartifact_api_key my_ruby_gem-0.0.1.gem