> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/new-to-artifact-registry/quickstart/rubygems-quickstart.md).

# RubyGems

{% @harness-package-selector/package-selector platforms="%5B%7B%22label%22%3A%22Docker%22%2C%22slug%22%3A%22docker%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fdocker-quickstart%22%7D%2C%7B%22label%22%3A%22Helm%22%2C%22slug%22%3A%22helm%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fhelm-quickstart%22%7D%2C%7B%22label%22%3A%22Helm%20HTTP%22%2C%22slug%22%3A%22helm-http%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fhelm-http-quickstart%22%7D%2C%7B%22label%22%3A%22Generic%22%2C%22slug%22%3A%22generic%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fgeneric-quickstart%22%7D%2C%7B%22label%22%3A%22Raw%20File%22%2C%22slug%22%3A%22raw-file%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fraw-file-quickstart%22%7D%2C%7B%22label%22%3A%22Maven%22%2C%22slug%22%3A%22maven%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fmaven-quickstart%22%7D%2C%7B%22label%22%3A%22Python%22%2C%22slug%22%3A%22python%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fpython-quickstart%22%7D%2C%7B%22label%22%3A%22NPM%22%2C%22slug%22%3A%22npm%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fnpm-quickstart%22%7D%2C%7B%22label%22%3A%22Nuget%22%2C%22slug%22%3A%22nuget%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fnuget-quickstart%22%7D%2C%7B%22label%22%3A%22RPM%22%2C%22slug%22%3A%22rpm%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Frpm-quickstart%22%7D%2C%7B%22label%22%3A%22Debian%22%2C%22slug%22%3A%22debian%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fdebian-quickstart%22%7D%2C%7B%22label%22%3A%22Alpine%22%2C%22slug%22%3A%22alpine%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Falpine-quickstart%22%7D%2C%7B%22label%22%3A%22Wolfi%22%2C%22slug%22%3A%22wolfi%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fwolfi-quickstart%22%7D%2C%7B%22label%22%3A%22Cargo%22%2C%22slug%22%3A%22cargo%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fcargo-quickstart%22%7D%2C%7B%22label%22%3A%22Conan%22%2C%22slug%22%3A%22conan%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fconan-quickstart%22%7D%2C%7B%22label%22%3A%22Go%22%2C%22slug%22%3A%22go%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fgo-quickstart%22%7D%2C%7B%22label%22%3A%22Hugging%20Face%22%2C%22slug%22%3A%22hugging-face%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fhugging-face-quickstart%22%7D%2C%7B%22label%22%3A%22Conda%22%2C%22slug%22%3A%22conda%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fconda-quickstart%22%7D%2C%7B%22label%22%3A%22Dart%22%2C%22slug%22%3A%22dart%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fdart-quickstart%22%7D%2C%7B%22label%22%3A%22PHP%20Composer%22%2C%22slug%22%3A%22php-composer%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fphp-composer-quickstart%22%7D%2C%7B%22label%22%3A%22Swift%22%2C%22slug%22%3A%22swift%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fswift-quickstart%22%7D%2C%7B%22label%22%3A%22Puppet%22%2C%22slug%22%3A%22puppet%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fpuppet-quickstart%22%7D%2C%7B%22label%22%3A%22Terraform%22%2C%22slug%22%3A%22terraform%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fterraform-quickstart%22%7D%2C%7B%22label%22%3A%22R%20(CRAN)%22%2C%22slug%22%3A%22r-cran%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fr-cran-quickstart%22%7D%2C%7B%22label%22%3A%22RubyGems%22%2C%22slug%22%3A%22rubygems%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Frubygems-quickstart%22%7D%5D" selectedPlatform="rubygems" %}

Use a **RubyGems** registry to host private Ruby gems and serve them to the gem CLI and Bundler.

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* Ensure you have the RubyGems CLI (`gem`) installed on your local machine. Bundler is optional and required only if you install gems with `bundle`.
* Access to a Harness account with appropriate permissions to create registries and connectors.

***

### Create a RubyGems artifact registry <a href="#create-a-rubygems-artifact-registry" id="create-a-rubygems-artifact-registry"></a>

1. Go to the Artifact Registry module in your Harness project.
2. Click **New Artifact Registry**.
3. In the Registry Type list, select **Ruby**.
4. Enter a **Registry Name**.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>REGISTRY NAME CRITERIA</strong></p><p>The registry name must start with a letter, should only contain lowercase alphanumerics, <code>_</code>, <code>.</code> and <code>-</code>, and <em>must be unique to your Harness account</em>.</p></div>
5. Optionally, add a Description and Labels for better organization.
6. Select **Create Registry** to finalize.

***

### Configure an upstream proxy (optional) <a href="#configure-an-upstream-proxy-optional" id="configure-an-upstream-proxy-optional"></a>

An upstream proxy allows your registry to fetch gems from external RubyGems sources when they are not available locally. The default upstream is RubyGems.org.

#### Create an upstream proxy <a href="#create-an-upstream-proxy" id="create-an-upstream-proxy"></a>

1. In the Artifact Registry module, select the dropdown next to **New Artifact Registry** and select **Upstream Proxy**.
2. Select **Ruby** as the proxy type.
3. Enter an **Upstream Proxy Key**.
4. Optionally, add a Description and Labels.
5. Select your **Source**:
   * RubyGems.org
   * Custom
6. If you choose Custom, enter your **Remote Registry URL** (for example, `https://rubygems.org`).
7. Choose your **Authentication** method (`Anonymous` by default for public RubyGems sources).
8. Click **Create Upstream Proxy** to establish the connection.

#### Configure the upstream proxy in your registry <a href="#configure-the-upstream-proxy-in-your-registry" id="configure-the-upstream-proxy-in-your-registry"></a>

1. In the Artifact Registry module, select an existing RubyGems Artifact Registry.
2. Go to the **Configuration** tab.
3. In the **Advanced (Optional)** section, click **Configure Upstream**.
4. Select from the list of compatible proxies to add them to your registry.
5. Select **Save** to save the configuration.

{% hint style="info" %}
**UPSTREAM PROXY CACHING**

If a gem is not found in your Harness registry, the upstream proxy fetches it from the remote registry and caches it.
{% endhint %}

***

### Set up the RubyGems client <a href="#set-up-the-rubygems-client" id="set-up-the-rubygems-client"></a>

In your Harness RubyGems Artifact Registry, click **Set Up Client** and follow the instructions to configure the gem CLI to use the registry.

**1. Generate identity token**

1. In your Harness RubyGems Artifact Registry, click **Set Up Client**.
2. Click **Generate Token** to generate an identity token.

**2. Configure registry**

1. Add the registry as a remote host:

```bash
gem sources --add https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/ruby
```

or (to save along with token)

```bash
gem sources --add https://<USERNAME>:<API_KEY>@pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/ruby
```

2. Add the following entry to \~/.gem/credentials (create the file if it does not exist):

```bash
:<API_KEY_NAME>: "Bearer <API_KEY>"
```

3. Configure Bundler to authenticate with this registry:

```bash
bundle config set --global "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/ruby" "<USERNAME>:<API_KEY>"
```

4. Add the registry URL to your Gemfile:

```bash
source "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/ruby"
```

**3. Push package**

Set allowed\_push\_host in your gemspec to the registry host, then push your gem:

```bash
gem push <ARTIFACT_NAME>-<VERSION>.gem --host https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/ruby --key <API_KEY_NAME>
```

**4. Install package**

Install a gem from this registry:

```bash
gem install <ARTIFACT_NAME> -v <VERSION> --source https://<USERNAME>:<API_KEY>@pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/ruby
```

{% hint style="info" %}
**DOWNLOAD STALLS**

Reduce concurrent downloads to 1 in the `.gemrc` file and the Bundler config.
{% endhint %}

**5. Yank package**

Remove a gem version from this registry:

```bash
gem yank <ARTIFACT_NAME> -v <VERSION> --host https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/ruby --key <API_KEY_NAME>
```

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>Publish to a RubyGems registry returns 409 Conflict</summary>

Gem versions are immutable after publish. Choose a new SemVer version, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>gem push or gem install returns 401 Unauthorized against a Harness RubyGems registry</summary>

Regenerate the identity token from Set Up Client, update \~/.gem/credentials or your Bundler config with the new token, and confirm the registry URL includes your account ID and registry name.

</details>

<details>

<summary>gem install returns 403 Forbidden, 404 Not Found, or the installation hangs</summary>

Reduce the number of concurent downloads in the \~/.gemrc file and config\_file.

</details>