Ruby gems API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated

This is the API documentation for Ruby gems.

This API is used by the Ruby gems and Bundler package manager clients and is generally not meant for manual consumption. This API is under development and is not ready for production use due to limited functionality.

For instructions on how to upload and install gems from the GitLab package registry, see the Ruby gems registry documentation.

These endpoints do not adhere to the standard API authentication methods. See the Ruby gems registry documentation for details on which headers and token types are supported. Undocumented authentication methods might be removed in the future.

Enable the Ruby gems API

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

To enable it:

Copy to clipboard
Feature.enable(:rubygem_packages)

To disable it:

Copy to clipboard
Feature.disable(:rubygem_packages)

To enable or disable it for specific projects:

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

Download a gem file

Download a gem:

Copy to clipboard
GET projects/:id/packages/rubygems/gems/:file_name
AttributeTypeRequiredDescription
idstringyesThe ID or full path of the project.
file_namestringyesThe name of the .gem file.
Copy to clipboard
curl --header "Authorization:<personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/rubygems/gems/my_gem-1.0.0.gem"

Write the output to file:

Copy to clipboard
curl --header "Authorization:<personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/rubygems/gems/my_gem-1.0.0.gem" >> my_gem-1.0.0.gem

This writes the downloaded file to my_gem-1.0.0.gem in the current directory.

Fetch a list of dependencies

Fetch a list of dependencies for a list of gems:

Copy to clipboard
GET projects/:id/packages/rubygems/api/v1/dependencies
AttributeTypeRequiredDescription
idstringyesThe ID or full path of the project.
gemsstringnoComma-separated list of gems to fetch dependencies for.
Copy to clipboard
curl --header "Authorization:<personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/rubygems/api/v1/dependencies?gems=my_gem,foo"

This endpoint returns a marshalled array of hashes for all versions of the requested gems. Since the response is marshalled, you can store it in a file. If Ruby is installed, you can use the following Ruby command to read the response. For this to work, you must set your credentials in ~/.gem/credentials:

Copy to clipboard
$ ruby -ropen-uri -rpp -e \
  'pp Marshal.load(open("https://gitlab.example.com/api/v4/projects/1/packages/rubygems/api/v1/dependencies?gems=my_gem,rails,foo"))'

[{:name=>"my_gem", :number=>"0.0.1", :platform=>"ruby", :dependencies=>[]},
 {:name=>"my_gem",
  :number=>"0.0.3",
  :platform=>"ruby",
  :dependencies=>
   [["dependency_1", "~> 1.2.3"],
    ["dependency_2", "= 3.0.0"],
    ["dependency_3", ">= 1.0.0"],
    ["dependency_4", ">= 0"]]},
 {:name=>"my_gem",
  :number=>"0.0.2",
  :platform=>"ruby",
  :dependencies=>
   [["dependency_1", "~> 1.2.3"],
    ["dependency_2", "= 3.0.0"],
    ["dependency_3", ">= 1.0.0"],
    ["dependency_4", ">= 0"]]},
 {:name=>"foo",
  :number=>"0.0.2",
  :platform=>"ruby",
  :dependencies=>
    ["dependency_2", "= 3.0.0"],
    ["dependency_4", ">= 0"]]}]

This writes the downloaded file to mypkg-1.0-SNAPSHOT.jar in the current directory.

Upload a gem

Upload a gem:

Copy to clipboard
POST projects/:id/packages/rubygems/api/v1/gems
AttributeTypeRequiredDescription
idstringyesThe ID or full path of the project.
Copy to clipboard
curl --request POST \
     --upload-file path/to/my_gem_file.gem \
     --header "Authorization:<personal_access_token>" \
     "https://gitlab.example.com/api/v4/projects/1/packages/rubygems/api/v1/gems"