Cloudsmith Documentation/Help Hub

Welcome to the Cloudsmith Documentation/Help Hub. You'll find comprehensive guides and documentation to help you start working with Cloudsmith as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Ruby Repository

Cloudsmith provides public & private repositories for Ruby gems

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:

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 pre-configured).

In the following examples:

Identifier

Description

OWNER

Your Cloudsmith account name or organisation name (namespace)

REPOSITORY

Your Cloudsmith Repository name (also called "slug")

TOKEN

Your Cloudsmith Entitlement Token (see Entitlements for more details)

USERNAME

Your Cloudsmith username

PASSWORD

Your Cloudsmith password

API-KEY

Your Cloudsmith API Key

PACKAGE_NAME

The name of your package

PACKAGE_VERSION

The version number of your package

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.

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'

Upstream Proxying / Caching

Not Supported

Key Signing Support

GPG

Troubleshooting

Please see the Troubleshooting page for further help and information.

Updated 2 months ago


Ruby Repository


Cloudsmith provides public & private repositories for Ruby gems

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.