# Using CodeArtifact with Ruby These topics describe how to use the RubyGems and Bundler tools with CodeArtifact to install and publish Ruby gems. **Note** CodeArtifact recommends Ruby 3.3 or later and does not work with Ruby 2.6 or older. **Topics** + [Configure and use RubyGems and Bundler](configure-use-rubygems-bundler.md) + [ # RubyGems command support ](ruby-command-support.md) + [Bundler compatibility](bundler-compatibility.md) # Configure and use RubyGems and Bundler with CodeArtifact After you create a repository in CodeArtifact, you can use RubyGems (`gem`) and Bundler (`bundle`) to install and publish gems. This topic describes how to configure the package managers to authenticate with and use a CodeArtifact repository. ## Configure RubyGems (`gem`) and Bundler (`bundle`) with CodeArtifact To use RubyGems (`gem`) or Bundler (`bundle`) to publish gems to or consume gems from AWS CodeArtifact, you'll first need to configure them with your CodeArtifact repository information, including credentials to access it. Follow the steps in one of the following procedure to configure the `gem` and `bundle` CLI tools with your CodeArtifact repository endpoint information and credentials. ### Configure RubyGems and Bundler using the console instructions You can use configuration instructions in the console to connect your Ruby package managers to your CodeArtifact repository. The console instructions provide custom commands that you can run to set up your package managers without needing to find and fill in your CodeArtifact information. 1. Open the AWS CodeArtifact console at [https://console.aws.amazon.com/codesuite/codeartifact/home](https://console.aws.amazon.com/codesuite/codeartifact/home). 1. In the navigation pane, choose **Repositories**, and then choose the repository that you want to use for installing or pushing Ruby gems. 1. Choose **View connection instructions**. 1. Choose your operating system. 1. Choose the Ruby package manager client that you want to configure with your CodeArtifact repository. 1. Follow the generated instructions to configure the package manager client to install Ruby gems from or publish Ruby gems to the repository. ### Configure RubyGems and Bundler manually If you cannot or do not want to use the configuration instructions from the console, you can use the following instructions to connect to your Ruby package managers to your CodeArtifact repository manually. 1. In a command line, use the following command to fetch a CodeArtifact authorization token and store it in an environment variable. + Replace *my\$1domain* 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](domain-overview.md#domain-overview-cross-account). ------ #### [ 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 ``` ------ 1. 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\$1domain* 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](domain-overview.md#domain-overview-cross-account). + Replace *my\$1repo* 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. 1. 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 ``` ------ 1. 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 ``` ------ 1. 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 ``` ------ Now that you've configured RubyGems (`gem`) and Bundler (`bundle`) with your CodeArtifact repository, you can use them to publish and consume Ruby gems to and from it. ## Installing Ruby gems from CodeArtifact Use the following procedures to install Ruby gems from an CodeArtifact repository with the `gem` or `bundle` CLI tools. ### Install Ruby gems with `gem` You can use the RubyGems (`gem`) CLI to quickly install a specific version of a Ruby gem from your CodeArtifact repository. **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](#configure-ruby-gem) 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. 1. Use the following command to install Ruby gems from CodeArtifact: ``` gem install my_ruby_gem --version 1.0.0 ``` ### Install Ruby gems with `bundle` You can use the Bundler (`bundle`) CLI to install the Ruby gems that are configured in your `Gemfile`. **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](#configure-ruby-gem) 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. 1. 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' ``` 1. Use the following command to install the Ruby gems as specified in your `Gemfile`: ``` bundle install ``` ## Publishing Ruby gems to CodeArtifact Use the following procedure to publish Ruby gems to a CodeArtifact repository using the `gem` CLI. 1. If you haven't, follow the steps in [Configure RubyGems (`gem`) and Bundler (`bundle`) with CodeArtifact](#configure-ruby-gem) 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. 1. 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 ``` # RubyGems command support CodeArtifact supports the `gem install` and `gem push` commands. **Note** The `gem install` command requires RubyGems version 3.5.18 or earlier when used with CodeArtifact. RubyGems versions 3.5.19 and later require the Compact Index API to resolve gems, which CodeArtifact does not currently support. If you are using RubyGems 3.5.19 or later, use Bundler to install gems instead, or downgrade RubyGems by running `gem update --system 3.5.18`. CodeArtifact does not support the following `gem` commands: + `gem fetch` + `gem info --remote` + `gem list --remote` + `gem mirror` + `gem outdated` + `gem owner` + `gem query` + `gem search` + `gem signin` + `gem signout` + `gem sources --add` + `gem sources --update` + `gem specification --remote` + `gem update` + `gem yank` # Bundler compatibility This guide contains information about CodeArtifact's compatibility with Bundler. ## Bundler compatibility AWS CodeArtifact recommends Bundler 2.4.11 or higher. If you encounter issues with installation, update the Bundler CLI to the latest version. ### Bundler version support In Bundler versions lower than 2.4.11, there is a limit of 500 dependencies that can be defined in the Gemfile before Bundler decides to query the full index, `specs.4.8.gz`. Since CodeArtifact does not support the full index, specifying more than 500 dependencies will not work with CodeArtifact when using Bundler versions lower than 2.4.11. To define more than 500 dependencies in your Gemfile with CodeArtifact, update Bundler to version 2.4.11 or higher. ### Bundler operations support CodeArtifact's support for RubyGems does not include the Bundler Compact Index APIs (the `/versions` API is not supported). CodeArtifact only supports the Dependencies API. Because the Compact Index is not supported, Bundler resolves gems using the Dependencies API (`/api/v1/dependencies`), which sends multiple gem names in a single request. Each gem name in the request counts as a separate request toward your account's *Read requests per second* quota. For example, if Bundler sends a dependency request containing 20 gem names, it counts as 20 requests toward the quota. This can cause throttling in CI/CD environments with high concurrency, even when the HTTP request count appears to be well below the configured limit. If you experience throttling during Ruby gem resolution, request a quota increase for *Read requests per second from a single AWS account*. For more information, see [Quotas in AWS CodeArtifact](service-limits.md). Additionally, CodeArtifact does not support the various spec APIs, such as `specs.4.8.gz`.