RubyGems

The proxy implements the RubyGems protocol.

Endpoint: <proxy-url>/rubygems

Authentication: the API key, sent as the password in HTTP basic auth. The username is not checked; _ is the conventional placeholder.

Bundler

Bundler mirrors RubyGems.org through the proxy, which leaves Gemfile untouched:

export SHIELDEDSTACK_API_KEY=YOUR_API_KEY_HERE
bundle config set --global mirror.https://rubygems.org <proxy-url>/rubygems
bundle config set --global <proxy-url>/rubygems "_:${SHIELDEDSTACK_API_KEY}"

The second command attaches credentials to the mirror URL, so the two values have to match exactly, including the absence of a trailing slash.

--global writes to the user configuration, normally ~/.bundle/config, which then holds the key. Treat that file as a secret. Dropping --global writes to .bundle/config in the project instead, which is only safe to commit when it carries the mirror and not the credential.

The gem command

For direct gem install use, add the proxy as a source and remove the public one:

gem sources --add "https://_:${SHIELDEDSTACK_API_KEY}@<proxy-host>/rubygems/"
gem sources --remove https://rubygems.org/

Removing the public source is the half that matters. With both present, gem can satisfy a package from either.

The trailing slash here follows RubyGems’ own source URL convention, and is why this differs from the Bundler mirror value above. Bundler is the strict one: its mirror and credential entries must match each other exactly.

Committing the configuration

The mirror URL is shareable. Bundler’s credential entry and any gem sources URL containing the API key are not, because the key is inside the URL. Keep those in a protected user configuration, or create them inside an ephemeral CI home directory that is discarded with the job. Do not commit .bundle/config when it contains credentials.

Verify

bundle install

The installed gems appear under Packages in the Control Plane, attributed to the project name on the API key.

Troubleshooting

Check what Bundler thinks is configured. bundle config list shows the mirror and whether a credential is attached to it.

401 or 403. The credential is registered against a URL that differs from the mirror URL, usually by a trailing slash. Both commands must use the identical value.

Stale gems. bundle clean --force.

After key rotation. Remove the old credential first, with bundle config unset --global <proxy-url>/rubygems, then register the new one.