Configure Ruby and Bundler for Artifactory

Configure Ruby/Bundler for dependency resolution and publishing through Artifactory.

This topic covers the following tasks:

• Configure Ruby and Bundler for Artifactory (jf ruby-config)
• Complete Bundler Setup After Configuration

When to Use

Use jf ruby-config to save your Artifactory server and repository preferences for Ruby projects. After running it, complete the Bundler credential and source configuration steps in After Configuration. Then bundle install resolves gems from Artifactory.

Prerequisites

• Ruby ≥ 3.0 and Bundler ≥ 2.3 must be installed.
• Configure a server with jf c add (alias: jf config add).
• Authentication to Artifactory is required.

Configuration: jf ruby-config

Generate Ruby/Bundler configuration for dependency resolution and publishing through Artifactory. Run this once per project before your first bundle install.

To configure Ruby/Bundler for Artifactory:

1. From your project directory (or with --global), run jf ruby-config with resolve (and optionally deploy) server and repository flags (see Non-Interactive Configuration with Flags).
2. Confirm .jfrog/projects/ruby.yaml (or the global path) was written (see How to Verify).

Synopsis

jf ruby-config [options]

Aliases: rubyc

Configuration Options

Configuration Examples

View Help

jf ruby-config --help

Non-Interactive Configuration with Flags

jf ruby-config --server-id-resolve=<server-id> --repo-resolve=<repo-name>

Where:

• <server-id>: The server ID configured using jf config add
• <repo-name>: The name of the Ruby repository in Artifactory

For example:

jf ruby-config --server-id-resolve=my-server --repo-resolve=ruby-virtual

Global Configuration

jf ruby-config --global --server-id-resolve=<server-id> --repo-resolve=<repo-name>

What jf ruby-config Does

jf ruby-config saves your Artifactory server and repository preferences to a local config file:

• Project-level (default): .jfrog/projects/ruby.yaml
• Global (--global): ~/.jfrog/projects/ruby.yaml

It does not modify Bundler's native configuration. After running jf ruby-config, you must also configure Bundler to use Artifactory as a gem source or mirror. See After Configuration.

Configuration Notes

• Config-only: There is no jf ruby command. After running jf ruby-config, complete the Bundler credential and source setup described in After Configuration.
• Resolution and deployment: Use --repo-resolve for installing gems and --repo-deploy for publishing gems.
• Run once per project: Re-run when changing repository assignments.

Expected Output

$ jf ruby-config --server-id-resolve=my-server --repo-resolve=ruby-virtual
[Info] ruby build config successfully created.

How to Verify

After running, confirm the config file was written:

cat .jfrog/projects/ruby.yaml

Expected content:

version: 1
type: ruby
resolver:
    repo: ruby-virtual
    serverId: my-server

After Configuration

jf ruby-config saves JFrog-side preferences but does not modify Bundler's native configuration. You must complete the following steps before bundle install will resolve from Artifactory.

To finish Bundler setup so gems resolve from Artifactory:

1. Run jf ruby-config with your server and repository settings if you have not already:

   Bash

   jf ruby-config --server-id-resolve=my-server --repo-resolve=ruby-virtual

2. Configure Bundler credentials for your Artifactory host. Run once per machine (or inject via environment in CI):

   Bash

   bundle config <artifactory-host> <username>:<access-token>

   For example:

   Bash

   bundle config my-instance.jfrog.io my-user:AKCp...token...

   For CI/CD, use the environment variable form instead:

   Bash

   export BUNDLE_MY__INSTANCE__JFROG__IO="my-user:AKCp...token..."

   Replace dots in the hostname with double underscores when forming the env var name (for example, my-instance.jfrog.io → BUNDLE_MY__INSTANCE__JFROG__IO).

3. Point Bundler at Artifactory by updating your Gemfile:

   Ruby

   source 'https://my-instance.jfrog.io/artifactory/api/gems/ruby-virtual'

   Or configure a mirror so the existing source 'https://rubygems.org' line is redirected:

   Bash

   bundle config mirror.https://rubygems.org https://my-instance.jfrog.io/artifactory/api/gems/ruby-virtual

4. Install dependencies:

   Bash

   bundle install

5. (Optional) If --repo-deploy was set in jf ruby-config, publish a gem with --host set to your Artifactory gems API:

   Bash

   gem push my-gem-1.0.0.gem --host https://my-instance.jfrog.io/artifactory/api/gems/ruby-local

Important Notes

• Config-only: There is no jf ruby command. jf ruby-config saves JFrog preferences to .jfrog/projects/ruby.yaml only. Bundler credential and source configuration must be done separately — see After Configuration.
• Resolution and deployment: Use --repo-resolve for installing gems and --repo-deploy for publishing gems.

CI/CD Example: GitHub Actions

# .github/workflows/build.yml
steps:
  - uses: actions/checkout@v4

  - name: Setup JFrog CLI
    uses: jfrog/setup-jfrog-cli@v4
    env:
      JF_URL: ${{ vars.JF_URL }}
      JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}

  - name: Setup Ruby
    uses: ruby/setup-ruby@v1
    with:
      ruby-version: '3.2'

  - name: Save JFrog Ruby config
    run: jf ruby-config --server-id-resolve=setup-jfrog-cli-server --repo-resolve=ruby-virtual

  - name: Configure Bundler credentials
    # Inject Artifactory credentials into Bundler so bundle install can authenticate.
    # The env var name is the hostname with dots replaced by double underscores, uppercased.
    # Example for my-instance.jfrog.io → BUNDLE_MY__INSTANCE__JFROG__IO
    env:
      BUNDLE_ARTIFACTORY_HOST: ${{ vars.ARTIFACTORY_HOST }}
      ARTIFACTORY_USER: ${{ vars.ARTIFACTORY_USER }}
      ARTIFACTORY_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}
    run: bundle config ${BUNDLE_ARTIFACTORY_HOST} ${ARTIFACTORY_USER}:${ARTIFACTORY_TOKEN}

  - name: Install dependencies
    run: bundle install

Store ARTIFACTORY_HOST (for example, my-instance.jfrog.io) and ARTIFACTORY_USER as repository variables. Store the access token as a secret (JF_ACCESS_TOKEN).

Troubleshooting

Enable debug logging: export JFROG_CLI_LOG_LEVEL=DEBUG

Frequently Asked Questions

This section provides answers to frequently asked questions about configuring Ruby and Bundler for Artifactory.

Related Topics

• Build Tools Overview
• Native Mode
• Use JFrog CLI Package Alias