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.
- 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
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
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
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 testMore for GitHub Actions: GitHub Actions setup guide.
GitLab CI
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 testMore 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.