Ruby Repository

Ruby Gems is the packaging format for Ruby language. Cloudsmith is proud to support fully-featured registries for managing your own private and public Gem packages.

For more information on Ruby, please see:

• Ruby Lang: The official website for Ruby language
• Ruby Gem Community: The official public repository for Ruby Gems
• Ruby Gem Documentation: The official docs for Ruby Gems

Contextual Documentation

The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy n' paste snippets (with your namespace/repo/rsa-key pre-configured).

In the following examples:

Upload a Package

To upload, you need to generate your Ruby gem package first. You can do this with:

gem build PACKAGE_NAME.gemspec

This generates a gem package file (.gem) like PACKAGE_NAME-PACKAGE_VERSION.gem that you can upload.

📘

This assumes that you've created a .gemspec file for your project. Please see the official Rubygems guide on how to make your own gem for more information. (external link)

Upload via gem push

The endpoint for the native Ruby API is:

https://ruby.cloudsmith.io/OWNER/REPOSITORY/

In order to authenticate for native publishing, you can either enter your credentials during the gem push command or add your credentials to your $HOME/.gem/credentials file:

:rubygems_api_key: API-KEY

You can also replace :rubygems_api_key: with an alternative, such as :cloudsmith:, and then specify --key 'cloudsmith' during the gem push command.

🚧

These credentials are not encrypted. It is recommended to log in on the first gem push `instead.

To publish a gem, you can do so from your project directory using gem push:

gem push PACKAGE_NAME-VERSION.gem \
  --host 'https://ruby.cloudsmith.io/OWNER/REPOSITORY'

If you haven't specified credentials above, you'll be asked for them during the push.

📘

You can also set the RUBYGEMS_HOST environment variable instead of --host:

Upload via the Cloudsmith CLI

For full details of how to install and setup the Cloudsmith CLI, see Command Line Interface.

The command to upload a Ruby gem package via the Cloudsmith CLI is:

cloudsmith push ruby OWNER/REPOSITORY PACKAGE_NAME-PACKAGE_VERSION.gem

Example:

cloudsmith push ruby your-account/your-repo safe_yaml-1.0.4.gem

Upload via Cloudsmith Website

Please see Upload a Package for details of how to upload via the Website UI.

Example Project

For examples of what your project should look like for packaging and publishing/uploading, please have a look at our examples repository (on GitHub). We'll supplement these with more detailed guidance later, but otherwise, just ask - we're here to help!

Download / Install a Package

Setup

As stated by Bundler, "Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed."

Bundler from version 1.7 supports scoped sources, so you can install a gem from Cloudsmith using the following declaration in your Gemfile:

Public Repositories

source 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/ruby/' do
  gem 'PACKAGE-NAME', '~> PACKAGE_VERSION'
end

Private Repositories

📘

Private Cloudsmith repositories require authentication. You can choose between two types of authentication, Entitlement Token Authentication or HTTP Basic Authentication.

The setup method will differ depending on what authentication type you choose to use.

🚧

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code or expose them in any logs.

source 'https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/ruby/' do
  gem 'PACKAGE-NAME', '~> PACKAGE_VERSION'
end

source 'https://USERNAME:[email protected]/basic/OWNER/REPOSITORY/ruby/' do
  gem 'PACKAGE-NAME', '~> PACKAGE_VERSION'
end

source 'https://USERNAME:[email protected]/basic/OWNER/REPOSITORY/ruby/' do
  gem 'PACKAGE-NAME', '~> PACKAGE_VERSION'
end

source 'https://token:[email protected]/basic/OWNER/REPOSITORY/ruby/' do
  gem 'PACKAGE-NAME', '~> PACKAGE_VERSION'
end

Setup with Ruby CLI

You can also add Cloudsmith as a source for the Ruby CLI instead:

Public Repositories

gem sources --add 'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/ruby/'

Private Repositories

The Ruby CLI setup method will differ depending on what authentication type you choose to use.

gem sources --add 'https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/ruby/'

gem sources --add 'https://USERNAME:[email protected]/basic/OWNER/REPOSITORY/ruby/'

gem sources --add 'https://USERNAME:[email protected]/basic/OWNER/REPOSITORY/ruby/'

gem sources --add 'https://token:[email protected]/basic/OWNER/REPOSITORY/ruby/'

Specifying Dependencies

If you have a project Gemfile you can specify your Ruby gem package as a dependency:

Public Repositories

source 'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/ruby/' do
  gem 'PACKAGE_NAME', 'PACKAGE_VERSION'
end

Private Repositories

source 'https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/ruby/' do
  gem 'PACKAGE_NAME', 'PACKAGE_VERSION'
end

source 'https://USERNAME:[email protected]/basic/OWNER/REPOSITORY/ruby/' do
  gem 'PACKAGE_NAME', 'PACKAGE_VERSION'
end

source 'https://USERNAME:[email protected]/basic/OWNER/REPOSITORY/ruby/' do
  gem 'PACKAGE_NAME', 'PACKAGE_VERSION'
end

source 'https://token:[email protected]/basic/OWNER/REPOSITORY/ruby/' do
  gem 'PACKAGE_NAME', 'PACKAGE_VERSION'
end

When specifying a private repository in a Gemfile, please bear in mind that the URL will contain the credentials (especially important if the Gemfile shared.)

Our recommendation is to specify the authentication credentials via environment variables, but you could also choose to encrypt your Gemfile via something like git-crypt (if you're using git or GitHub, for example).

Installing a Package

Once setup, you can install your Ruby gem package using gem install as follows.

To install a specific version of a package:

 gem install 'PACKAGE_NAME:PACKAGE_VERSION'

To install the latest version of a package:

 gem install 'PACKAGE_NAME'

Security Scanning

Supported
Please see our Security Scanning documentation for further information.

Upstream Proxying / Caching

Configurable Proxying Caching
You can configure upstream Ruby repositories that you wish to use for packages that are not available in your Cloudsmith repository. In addition, you can also choose to cache any requested packages for future use.

Please see our Upstream Proxying documentation for further instructions.

Key Signing Support

GPG

Troubleshooting

Please see the Troubleshooting page for further help and information.