Ruby gems in the package registry

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated Status: Experiment
History
The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

You can publish Ruby gems to your project’s package registry. Then, you can download them from the UI or with the API.

This feature is an experiment. For more information about the development of this feature, see epic 3200.

Authenticate to the package registry

Before you can interact with the package registry, you must authenticate to it.

To do this, you can use:

For example:

With an access token

To authenticate with an access token:

  • Create or edit your ~/.gem/credentials file, and add: 

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

In this example:

  • <token> must be the token value of either your personal access token or deploy token.
  • <project_id> is displayed on the project overview page.
With a CI/CD job token

To authenticate with a CI/CD job token:

  • Create or edit your .gitlab-ci.yml file, and add: 

    # 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 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:

To do this:

  • Run a command like: 

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

    In this example, <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

When a gem is published successfully, a message like this is displayed: 

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

The gem is published to your package registry, and is shown on the Packages and registries page. It can take up to 10 minutes before GitLab processes and displays your 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.

Download gems

You can’t install Ruby gems from the GitLab package registry. However, you can download gem files for local use.

To do this:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Deploy > Package registry.
  3. Select the package name and version.
  4. Under Assets, select the Ruby gem you want to download.

To download Ruby gems, you can also use the API.