Skip to end of metadata
Go to start of metadata
Table of Contents


This page assumes you are familiar with the concept of repositories in general.

If you are not, please refer to Configuring Repositories for general information about repositories before continuing.

 Artifactory fully supports RubyGems repositories providing the following:

  • Setting up a proxy and caching of remote repositiories
  • Local repositories with RubyGems API support
  • Virtual repositories that aggregate multiple local and remote repositories including indices of both gems and specifications
  • Support for common Ruby tools such as gem and bundler


Artifactory Support for RubyGems

Page Contents

Remote Repositories

Setting up a Proxy

A remote RubyGems repository serves as a caching proxy for a repository managed at a remote URL such as

Once requested, artifacts (Gems) are cached on demand. They can then be removed, but you cannot manually deploy anything into a remote repository.

You can proxy a remote RubyGems repository, such as as follows:

  1. In the Admin tab under Configuration | Repositories  go to the Remote Repositories section and select "New" 
  2. Set the Repository Key value, and specify the URL to the remote repository in the URL field as displayed below
     Defining a new RubyGems Repository
  3. In the Packages tab of the New Remote Repository popup, set Enable RubyGems Support and click "Create"
    Enabling RubyGems Support  


In order to allow the integration with the gem command line tool, you must add the relevant source URL to your RubyGems configuration.

  1. In the Artifacts tab, select your newly created repository in the Repository Browser and select the General tab.
  2. Copy the source URL from the RubyGems Sources section. 
    Copying the RubyGems Source
  3. Add this URL by modifying your ~/.gemrc file or using the gem source command as follows:
    Adding a Remote Source to Use a RubyGems Repository 

Additional Gem Commands You Can Use

You can remove previous source entries by modifying your ~/.gemrc file manually or by running gem sources -r
You can also run gem sources --list to know what your effective sources are and their order.

Overcoming Unauthorized Status Failures

Some gem/bundler commands may fail with an Unauthorized (401) status. In some cases these can be overcome by using one of the following options:

  • Enable the "Anonymous User" by checking Allow Anonymous Access in Security General Configuration as described in Managing Users.

  • Create a specialized Permission Target that allows anonymous access only to the remote repository.
  • Use a source URL with embedded credentials, such as: gem sources -a http://user:password@host/...
    Note that due to a known issue  in RubyGems, it is not possible to use URL embedded encrypted passwords with gem/bundler.

Local Repositories

Local RubyGems repositories are physical, locally-managed repositories into which you can deploy and manage your in-house Gems.


You can set up a local RubyGems repository as follows:

  1. In the Admin tab under Configuration | Repositories go to the Local Repositories section and select "New" 
  2. Set the Repository Key value.
  3. Under the Packages tab, set Enable RubyGems Support and click "Create"
  4. Extract the source URL from the General tab as described above
  5. Add this repository source URL by modifying your ~/.gemrc file or using the gem source command as displayed below. 
    Notice that there are two sources. First, the remote proxy, then the local one. This will effectively allow you to retrieve Gems from both of them in the specified order.
     RubyGems Sources


First, setup the appropriate credentials for the gem tool: either include the API key in the  ~/.gem/credentials file or issue this command:

Setting Up Credentials


$ART_GEMS:  The Artifactory gems url prefix http://ARTIFACTORY_HOST/artifactory/api/gems
REPO_KEY: The local repository name
USER:PASS The Artifactory user and password

On Linux you may need to change the permissions of the credentials file to 600 (chmod 600)

On Windows, the credentials file is located at %USERPROFILE%/.gem/credentials

API keys

You can modify the credentials file manually and add different API keys. You can later use gem push -k key to choose the relevant API key.

In order to push gems to the local repository, you can set the global variable $RUBYGEMS_HOST to point to the local repository as follows:


To get this value, in the Artifacts tab, select your repository in the Repository Browser and select the General tab.

RUBYGEMS_HOST will be displayed in the RubyGems Sources section as follows:


Alternatively you could use the gem push command with --host, and optionally, --key to specify the relevant API key. 

Make sure you are familiar with your effective sources and their order as specified in the ~/.gemrc file.

Also, make sure you are familiar with your global $RUBYGEMS_HOST variable before you issue a gem push command or use the push --host option.

When a local repository is first created, it is populated with rubygems-update-*.gem by default. In order to disable this behavior, you must change the System Properties to include: 

Virtual Repositories

A Virtual RubyGems repository (or "repository group") can aggregate multiple local and remote RubyGems repositories, seamlessly exposing them under a single URL.

The repository is virtual in that you can resolve and retrieve artifacts from it but you cannot deploy anything to it.

For more information on virtual repositories please refer to Virtual Repositories.


The procedure for setting up a virtual repository is very similar to setting up a local or remote repository, however as a last step, you need to select the repositories that will be included in the virtual repository you are creating.


Using a virtual RubyGems repository is also to using local and remote repositories.

You need to set the right repository source URL, in the same way as described in Usage for a local RubyGems repository, just with the appropriate repository key as follows:

source:  http://ARTIFACTORY:HOST/artifactory/api/gems/REPO_KEY/

target:    http://ARTIFACTORY_HOST/artifactory/api/gems/REPO_KEY #no slash at the end

Using the REST API

The REST API provides access to the Gems Add-on through the repository key using the following URL:



In addition to the basic binary repository operations, such as download, deploy, delete etc., the following API Gem commands are supported:

Gem command
Curl syntax example
Infocurl $ART_GEMS/REPO_KEY/api/v1/gems/my_gem.(json|xml|yaml)Optionally indicate JSON / XML / YAML (default: JSON)
Searchcurl $ART_GEMS/REPO_KEY/api/v1/search.(json|xml|yaml)?query=[query]Will search for gems with name containing query
Dependenciescurl $ART_GEMS/REPO_KEY/api/v1/dependencies?gems=[gem1,...]Use a csv of gem names for the value of gems

curl -X DELETE $ART_GEMS/REPO_KEY/api/v1/yank

-d 'gem_name=gem_name' -d 'version=0.0.1' -d 'platform=ruby'

Deletes the specific gem file from the repository


Indexing is done automatically by Artifactory in the background, however if you still need to recreate or update the spec index files, the following REST API  commands are also available:

REST command
Curl syntax example
ReIndexcurl -X POST $ART_GEMS/REPO_KEY/reindex

Re-creates all spec index files.

Update indexcurl -X POST $ART_GEMS/REPO_KEY/updateIndexUpdates all spec index files if needed. 

For full details please refer to Artifactory REST API. 

Viewing RubyGems Artifact Information

In the Artifacts tab under Browse | Tree Browser you can view a list of your repositories. If you select a RubyGems artifact within the repository tree you can select the RubyGems tab to view detailed information on the selected artifact. 

The screencast below how to use RubyGems with Artifactory:










  • No labels