cacheport

Ecosystem · Ruby

RubyGems cache for Bundler in CI

Bundler can transparently redirect a gem source to a mirror. Point rubygems.org at Cacheport and bundle install pulls gems from your region without any change to the Gemfile or lockfile.

CP-RUBYGEMSManifest
Upstream
rubygems.org
Endpoint
https://acme.cacheport.cc/gems/
Config
bundle config mirror.https://rubygems.org
Credentials
BUNDLE_ACME__CACHEPORT__CC
Gemfile.lock
Unchanged
Gems
Cached forever, immutable

How RubyGems caching works

A Bundler mirror is set per source. Your Gemfile keeps saying source "https://rubygems.org" and Gemfile.lock keeps the same remote, while Bundler quietly fetches from the mirror.

Cacheport serves the compact index Bundler uses to resolve dependencies and the .gem files themselves. The index is refreshed every few minutes, gems are kept for good.

What gets cached
Compact index
Refreshed every 5 minutes, stale copy if rubygems.org is down.
.gem files
Cached forever, served byte-identical.
Native extensions
Compiled on your runner as usual.

Set it up

Mirror and credentials

shell
bundle config set --global mirror.https://rubygems.org https://acme.cacheport.cc/gems/
bundle config set --global acme.cacheport.cc "ci:$CACHEPORT_TOKEN"

Or with environment variables

shell
export BUNDLE_MIRROR__HTTPS://RUBYGEMS__ORG/=https://acme.cacheport.cc/gems/
export BUNDLE_ACME__CACHEPORT__CC="ci:$CACHEPORT_TOKEN"

Bundler turns dots in a host name into double underscores for environment variables, so credentials for acme.cacheport.cc live in BUNDLE_ACME__CACHEPORT__CC. The first form is easier to read; use whichever your CI handles better.

Use it in CI

Store the token as a secret named CACHEPORT_TOKEN, then pick your provider.

GitHub Actions

.github/workflows/ci.yml
jobs:
  test:
    runs-on: ubuntu-latest
    env:
      BUNDLE_ACME__CACHEPORT__CC: ci:${{ secrets.CACHEPORT_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - run: bundle config set --global mirror.https://rubygems.org https://acme.cacheport.cc/gems/
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3.3"
          bundler-cache: true
      - run: bundle exec rake test

More for GitHub Actions: GitHub Actions setup guide.

GitLab CI

.gitlab-ci.yml
test:
  image: ruby:3.3
  before_script:
    - bundle config set --global mirror.https://rubygems.org https://acme.cacheport.cc/gems/
    - bundle config set --global acme.cacheport.cc "ci:$CACHEPORT_TOKEN"
  script:
    - bundle install
    - bundle exec rake test

More for GitLab CI: GitLab CI setup guide.

Native gems and precompiled platforms

Gems like nokogiri ship precompiled builds for common platforms. Bundler picks the platform gem from the index, and Cacheport caches each platform variant separately, so mixed fleets of x86_64 and arm64 runners all hit the cache.

Troubleshooting

Errors that usually mean the public registry is the bottleneck, and what Cacheport changes about them.

Questions

Do I need to change the source line in my Gemfile?

No. The mirror setting redirects it, so the Gemfile works with or without Cacheport.

Does gem install use the mirror?

No, the mirror is a Bundler setting. For plain gem install, pass --source https://acme.cacheport.cc/gems/.

Can I proxy a private gem server?

Yes. Add it as an upstream and mirror its URL the same way.

Other ecosystems people set up next

Start on the free plan

20 GB of cache, every registry, unlimited users. Upgrade when your pipelines outgrow it.