> 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/3.0/setup/ruby-gems.md).

# RubyGems

RubyGems - host gems in Harness Artifacts

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

## What you will learn from this topic

By the end of this guide, you will know how to:

* Create a registry in Harness Artifacts.
* Publish a package to the registry.
* Install the package from the registry and confirm that it works.

## Before you begin

* Install the RubyGems CLI (`gem`) on your local machine. Install Bundler only if you plan to install gems with `bundle`.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a RubyGems Registry

To create a RubyGems Registry:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**Registry name criteria**

The registry name must start with a letter, can only contain lowercase alphanumerics, `_`, `.`, and `-`, and must be unique to your Harness account.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Ruby** as the **Registry type**.
7. Select **Save**.
8. Select **Create** to finalize.

## Configure an upstream proxy (optional)

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 upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Select the drop-down next to **+ Create Registry** and select **Upstream Proxy**.
3. Specify the **Registry name**.
4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Ruby** as the **Registry type**.
7. Select the **Source**: **RubyGems.org** or **Custom**.
   * If you select **Custom**, specify the **Remote registry URL** (for example, `https://rubygems.org`).
8. Select the **Authentication method**.
   * **Username and password**: Specify the username and password. Use an existing secret, or create a new secret by specifying the **Name** and entering the **Secret text**.
   * **Anonymous**: No credentials required. This works for public RubyGems sources.
9. Select **Create** to finalize.

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

1. In Artifact Registry, select an existing RubyGems Artifact.
2. Navigate to the **Configuration** tab.
3. Select **Edit** in the **Upstream proxy** section.
4. Select **+ Add upstream proxy**.
5. Select the required proxy from the list.
6. Select **Apply**.
7. Select **Update** to finalize.

{% 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 %}

## RubyGems client setup

In your RubyGems Artifact, select the registry, then select **Setup Client**.

### Generate an identity token

An identity token serves as the password for authenticating with the registry.

1. In your RubyGems Artifact Registry, select **Setup Client**.
2. Select **Generate Token**.
3. Select an **Expiration** for the token:
   * **30 Days**
   * **90 Days**
   * **180 Days**
   * **Custom**
4. Copy the token. Use the token in place of `<API_KEY>` in the following steps.

{% hint style="info" %}
**Token expiration**

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.
{% endhint %}

### Configure the client

Configure the gem CLI and Bundler to authenticate with your registry, then publish and install gems. In the code samples, replace the values in angle brackets with your own values.

**1. Configure**

Add the registry as a remote host:

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

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

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

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>"
```

Add the registry URL to your Gemfile:

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

**2. Publish**

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>
```

**3. Install**

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**

If a download stalls, reduce the concurrent-download setting to 1 in the `.gemrc` file, the `config.rb` file, and your Bundler config.
{% endhint %}

**4. Yank**

Remove a gem version from the registry:

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

## Setup verification

Confirm that your registry serves the gem you published. To verify your setup:

1. In a new directory with no cached gems or Bundler lock file, install the gem you published using the `gem install` command from the earlier steps.
2. Confirm that `gem` downloaded the gem from your Harness registry address, which is shown in **Setup Client**.
3. In Harness, open your registry and confirm that the gem and version appear in the package list.

If a step fails, go to [Troubleshooting](#troubleshooting) to resolve common authentication and resolution issues before you retry.

## Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one version in the registry.

The following Run step shows the shape of a publish step. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        gem push <ARTIFACT_NAME>-"$PACKAGE_VERSION".gem --host https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/ruby --key <API_KEY_NAME>
```

## Troubleshooting

<details>

<summary>`gem push` or `bundle install` returns `401 Unauthorized` or `403 Forbidden`</summary>

Regenerate the identity token from **Setup 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 push` 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 install` returns `404 Not Found`, or cannot resolve the version</summary>

Check that the gem name and version match the values you used when you published the gem, and that the registry name and account ID in the source URL are correct.

</details>

<details>

<summary>Setup Client does not show a push command for an upstream proxy registry</summary>

An upstream proxy registry is pull-only, so **Setup Client** omits push instructions. Publish your gem to a virtual registry instead, or let the upstream proxy cache gems from the remote source on demand.

</details>

<details>

<summary>`gem install` stalls or hangs</summary>

Reduce the concurrent-download setting to 1 in the `.gemrc` file, the `config.rb` file, and your Bundler config.

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
