Ruby gems in the package registry

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated Status: Experiment

Introduced in GitLab 13.10.

WARNING: The Ruby gems package registry for GitLab is under development and isn't ready for production use due to limited functionality. This epic details the remaining work and timelines to make it production ready.

You can publish Ruby gems in your project's package registry, then install the packages when you need to use them as a dependency. Although you can push gems to the registry, you cannot install them from the registry. However, you can download gem files directly from the package registry's UI, or by using the API.

For documentation of the specific API endpoints that the Ruby gems and Bundler package manager clients use, see the Ruby gems API documentation.

Enable the Ruby gems registry

The Ruby gems registry for GitLab is behind a feature flag that is disabled by default. GitLab administrators with access to the GitLab Rails console can enable this registry for your instance.

To enable it:

Feature.enable(:rubygem_packages)

To disable it:

Feature.disable(:rubygem_packages)

To enable or disable it for specific projects:

Feature.enable(:rubygem_packages, Project.find(1))
Feature.disable(:rubygem_packages, Project.find(2))

Create a Ruby gem

If you need help creating a Ruby gem, see the RubyGems documentation.

Authenticate to the package registry

Before you can push to the package registry, you must authenticate.

To do this, you can use:

A personal access token with the scope set to api.
A deploy token with the scope set to read_package_registry, write_package_registry, or both.
A CI job token.

Authenticate with a personal access token or deploy token

To authenticate with a personal access token, create or edit the ~/.gem/credentials file and add:

---
https://gitlab.example.com/api/v4/projects/<project_id>/packages/rubygems: '<your token>'

<your token> must be the token value of either your personal access token or deploy token.
Your project ID is displayed on the project overview page.

Authenticate with a CI job token

To work with RubyGems commands within GitLab CI/CD, you can use the CI_JOB_TOKEN predefined environment variable instead of a personal access token or deploy token.

For example:

# assuming a my_gem.gemspec file is present in the repository with the version currently set to 0.0.1
image: ruby

run:
  before_script:
    - mkdir ~/.gem
    - echo "---" > ~/.gem/credentials
    - |
      echo "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/rubygems: '${CI_JOB_TOKEN}'" >> ~/.gem/credentials
    - chmod 0600 ~/.gem/credentials # rubygems requires 0600 permissions on the credentials file
  script:
    - gem build my_gem
    - gem push my_gem-0.0.1.gem --host ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/rubygems

You can also use CI_JOB_TOKEN in a ~/.gem/credentials file that you check in to GitLab:

---
https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/rubygems: '${env.CI_JOB_TOKEN}'

Push a Ruby gem

Prerequisites:

You must authenticate to the package registry.
The maximum allowed gem size is 3 GB.

To push your gem, run a command like this one:

gem push my_gem-0.0.1.gem --host <host>

<host> is the URL you used when setting up authentication. For example:

gem push my_gem-0.0.1.gem --host https://gitlab.example.com/api/v4/projects/1/packages/rubygems

This message indicates that the gem uploaded successfully:

Pushing gem to https://gitlab.example.com/api/v4/projects/1/packages/rubygems...
{"message":"201 Created"}

To view the published gem, go to your project's Packages and registries page. Gems pushed to GitLab aren't displayed in your project's Packages UI immediately. It can take up to 10 minutes to process a gem.

Pushing gems with the same name or version

You can push a gem if a package of the same name and version already exists. Both are visible and accessible in the UI. However, only the most recently pushed gem is used for installs.

Install a Ruby gem

The Ruby gems registry for GitLab is under development, and isn't ready for production use. You cannot install Gems from the registry. However, you can download .gem files directly from the UI or by using the API.

Admin message