Join our Newsletter — 33% off our NHI Course
Home› Guides› RubyGems Security Guide: MFA, Trusted Publishing, Signing and…
Guide Software & AI Supply Chain

RubyGems Security Guide: MFA, Trusted Publishing, Signing and Bundler Hardening

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 8 November 2026 15 min read
On this page

Every gem you install runs someone else's code with your privileges, and every gem you publish puts your RubyGems.org account inside your users' supply chain. This guide covers both sides of RubyGems security: protecting publisher accounts, owners and API keys on RubyGems.org, and hardening how Bundler resolves and installs gems in your applications. It goes deeper than the Ruby on Rails Security Guide, which covers the framework, and the Package Registry Publishing Tokens Guide, which compares tokens across registries. It is written for Ruby maintainers, platform and AppSec engineers, and anyone who owns a CI pipeline that pushes or installs gems. Facts are taken from the RubyGems guides and Ruby documentation as checked in October 2026.

This is an independent guide from NHI Mgmt Group, based on RubyGems's public documentation as of November 2026. It is not sponsored or reviewed by RubyGems. Product features change, so confirm settings against RubyGems's current documentation.

Key takeaways

  • Set MFA to "UI and API" with WebAuthn. It covers sign-in, gem signin, push and owner changes, and RubyGems.org already makes MFA mandatory for owners of gems with more than 180 million cumulative downloads.
  • Publish from CI with Trusted Publishing, not stored keys. GitHub Actions exchanges an OIDC token for a short-lived RubyGems.org token that can only push the gems configured to trust that workflow.
  • Treat every API key as a scoped, expiring credential. Pick only the scopes needed, scope push keys to one gem, set an expiry, and delete the old all-scopes legacy-key.
  • Harden the consumer side in Bundler. Lockfile checksums, frozen installs, a cooldown window, explicit source blocks for internal gems and bundler-audit in CI each close a different supply chain gap.
  • Do not rely on classic gem signing. RubyGems itself says signing is rarely used because there is no chain of trust; sigstore attestations through Trusted Publishing are the direction of travel.

How identity and access work in RubyGems

RubyGems has two security domains. The registry, RubyGems.org, decides who may publish, yank and manage a gem. The client tools, gem and Bundler, decide what code ends up on a developer laptop, CI runner or production host. Attackers target both: account takeover and leaked keys on the registry side, and typosquats, dependency confusion and tampered packages on the client side, all mapping to MITRE ATT&CK T1195.001 Compromise Software Dependencies and Development Tools.

Identity or credentialUsed forWhere it livesMain risk
RubyGems.org account (email, password, MFA)Web UI, gem signin, owner managementRubyGems.orgPhishing and credential stuffing leading to malicious releases
API key (rubygems_...)gem push, yank, owner, webhooks~/.local/share/gem/credentials or ~/.gem/credentials, or GEM_HOST_API_KEYLong-lived by default; leaks from laptops, CI logs and packaged gems
Trusted publisher (OIDC)Push from a specific GitHub Actions workflowConfigured per gem on RubyGems.orgOver-broad workflow, missing environment protection
Gem owner or maintainer rolePush and yank; owners also manage owners and Trusted PublishingPer gemStale or untrusted co-owners
Signing certificate (gem cert)Optional package signaturesAuthor's key file and the gemspec cert_chainUnprotected private key, no revocation

Two account details matter for detection. API keys are stored by RubyGems.org after one-way encryption, so a lost key cannot be retrieved, only replaced. The old GET /api/v1/api_key endpoint that returned a key for a username and password is retired and answers 410 Gone; clients create keys with POST /api/v1/api_key instead.

MFA levels

RubyGems.org supports WebAuthn (security keys, platform authenticators such as Touch ID or Windows Hello, and passkeys) and time-based one-time passwords. SMS is not supported for sign-in or recovery. When you enable MFA, the account defaults to the strongest level:

  • UI and API (Recommended): UI operations, gem signin, push, owner --add and owner --remove require MFA, and MFA applies to every API key.
  • UI and gem signin: UI and gem signin require MFA; individual API keys can then be marked to require an OTP for push, yank and owner commands.
  • UI only: removed; only accounts already on it still see the option. Move them up.

Recovery codes are shown once, each works once, and re-registering MFA on a new device can take up to two. Store them in a password manager or vault, not in the repository. On the command line, WebAuthn works by opening a verification link in the browser, so headless CI cannot complete it; that is the reason to use Trusted Publishing for automation rather than weakening the MFA level. See the Phishing-Resistant MFA Guide.

Admin roles and privileged access

Ownership is the privileged layer of RubyGems. Every owner can push and yank any version, so one weak co-owner account is enough to ship malware under a trusted name.

ActionGem ownerGem maintainerOrg ownerOrg adminOrg maintainer
Push new versionsYesYesYesYesYes
Yank versionsYesYesYesYesYes
Add or remove owners or membersYesNoYesYes (not Owners)No
Configure OIDC and Trusted PublishingYesNoNot stated separately in the org docs
Add or remove gems in the organisationn/an/aAdd and removeAdd onlyNo
Update or delete the organisationn/an/aYesNoNo
  • Use the Maintainer role for release engineers: maintainers can publish and yank but cannot add owners or change gem security settings, which limits the blast radius of a compromised account.
  • Review owners on every gem: the owners page shows confirmation status, each owner's MFA level and who added them (the ADDED BY column may be empty for older owners). New owners must confirm within 48 hours, and all existing owners are emailed when someone is added, so treat an unexpected email as an incident trigger.
  • Require MFA from all owners: release a version with s.metadata = { "rubygems_mfa_required" => "true" }. From that version on, any owner without MFA gets "Rubygem requires owners to enable MFA" on push, and the gem page shows NEW VERSIONS REQUIRE MFA. Setting it back to "false" only takes effect after a successful push with the new value, so watch for that change in pull requests.
  • Organizations: RubyGems.org Organizations are in private beta as of October 2026. They require MFA to create, replace individual ownership with membership roles (Owner, Admin, Maintainer, Outside Collaborator), and keep continuity when people leave. If you are in the beta, keep Owners to two or three named people.

Integrations, API tokens and service accounts

API keys are the non-human identities of RubyGems. A key is named, carries scopes and can be limited to one gem and one expiry date. Create keys in the web UI under API KEYS (password re-prompt) or with gem signin on RubyGems 3.2.0 or newer, where every scope defaults to No.

ScopeAllowsTypical holder
index_rubygemsList the account's gemsInventory scripts
push_rubygemCreate a gem or publish a version of any owned gemRelease job (scope to one gem)
yank_rubygemRemove a published versionHuman, short expiry
add_owner / remove_ownerChange gem ownersHuman only; never CI
access_webhooksList, create, delete and fire webhooksMirror or notification integration
show_dashboardDashboard Atom feed; exclusive, cannot be combinedFeed readers
  • Gem scoping: push, yank and owner scopes can be bound to one gem. If your ownership of that gem is removed, the key stops working.
  • Expiry: must be at least five minutes ahead and cannot be changed later; keys without one stay valid until deleted or reset. Set short expiries for one-off tasks.
  • Legacy key: older accounts have a legacy-key migrated to all scopes. Delete it, run gem signout on every host that used it, and issue new scoped keys.
  • CI fallback: where Trusted Publishing is not possible (for example a non-GitHub CI), pass a gem-scoped, push-only, expiring key as GEM_HOST_API_KEY from a secrets store, never in the repository. See the CI/CD Pipeline Identity Security Guide.

Trusted Publishing

Trusted Publishing removes the stored key entirely. A gem owner registers a trusted publisher with the GitHub repository owner, repository name, workflow filename and, ideally, a GitHub environment (RubyGems suggests release). The workflow requests an OIDC identity token, RubyGems.org checks it against the configured publisher, and issues a short-lived API token that can only push the gems that trust that publisher.

  1. Owner opens the gem page, then Trusted publishers, then Create, and enters repository, workflow and environment. For a gem that does not exist yet, create a pending trusted publisher under your profile; after the first push it converts to a normal publisher and you become owner.
  2. Protect the release environment in GitHub with required reviewers and tag rules, so only an approved release can request the token.
  3. Grant permissions: id-token: write at job level, not workflow level, and check out with persist-credentials: false.
  4. Use the rubygems/release-gem action, which configures the credentials and runs bundle exec rake release. Its attestations input (marked experimental, default true) adds sigstore attestations and only works through Trusted Publishing.
  5. If you call a reusable workflow from another repository, fill in Workflow Repository Owner and Name, because the token's job_workflow_ref claim points at the reusable workflow.
  6. Delete the old push key once two releases have gone through cleanly.

See the GitHub Actions OIDC Federation Hardening Guide and the PyPI API Tokens and Trusted Publishing Security Guide, whose security model RubyGems points to.

Webhooks

RubyGems.org webhooks notify a URL on every push of one gem or all gems (*). Each fired webhook carries an Authorization header that is the SHA-2 hash of gem name, version and your API key. Verify it on the receiver, and remember that the key behind it is a secret: rotate the key and the receiver's check together.

Logging and detection

RubyGems.org exposes little in the way of audit logs to gem owners, so detection relies on the signals it does provide plus your own pipeline telemetry.

SignalWhereWhat to look for
Last access per API keySettings, API KEYSUse of a key outside release windows; keys never used (delete)
Owner addition and removal emailsAll owners' inboxesUnplanned changes; route to a shared security mailbox
Push webhooksYour receiverA version that no tagged CI run produced
Owners page MFA columnGem owners pageAny owner without MFA
Attestations APIGET /api/v1/attestations/<gem>-<version>.jsonReleases of your gem without the expected sigstore bundle
bundler-audit resultsCI logsNew advisories from ruby-advisory-db; insecure http:// or git:// sources
Bundler install failuresCI logsChecksum mismatches, which can mean a tampered source

Useful metrics:

  • MFA coverage: percentage of owners across your gems at "UI and API" level (target 100).
  • Keyless release rate: share of releases pushed through Trusted Publishing.
  • Key hygiene: count of keys with no expiry or with owner scopes (target 0).
  • Checksum coverage: share of application lockfiles with a CHECKSUMS section.
  • Advisory dwell time: days from a bundler-audit finding to a merged fix.

Hardening baseline

Publisher baseline

  • Account: WebAuthn security key or passkey as primary factor, "UI and API" level, recovery codes vaulted.
  • Gem metadata: rubygems_mfa_required set to "true" in every gemspec.
  • Package contents: build the gemspec files list from an allowlist such as git ls-files, not a broad glob, and inspect the built gem with gem unpack before release. A pushed gem is mirrored by several hundred services through webhooks, so yanking does not recall a leaked secret. Revoke first, then yank. See the Open Source Project Maintainer Security Guide.
  • Release path: Trusted Publishing from a protected environment, with attestations enabled.

Consumer baseline (Bundler)

ControlSettingGap it closes
Lockfile checksumsDefault for new lockfiles (lockfile_checksums true); add to old ones with bundle lock --add-checksumsGem tampered with after the lockfile was written (SHA-256 of the .gem file)
Frozen installsBUNDLE_FROZEN=true or BUNDLE_DEPLOYMENT=true in CI and productionSilent lockfile changes during deploy
Never disable checksum validationKeep disable_checksum_validation unsetInstalling gems that fail RubyGems' checksum
Cooldownbundle config set cooldown 7 or source "https://rubygems.org", cooldown: 7; internal source cooldown: 0Malicious releases installed before the ecosystem detects and yanks them
Source pinningEvery internal gem inside a source "https://gems.internal" do ... end block, every gem with an explicit sourceDependency confusion with a public gem of the same name
Vulnerability auditbundle-audit in CI against ruby-advisory-dbKnown vulnerable versions and insecure sources

Cooldown has two caveats. It delays security fixes too, so document an override (bundle update <gem> --cooldown 0 --conservative). And it relies on the server publishing a per-version created_at in the v2 compact index; versions from servers that do not, including private registries on the v1 format, are treated as outside the window and stay installable. Confirm your internal server's behaviour before you count on it. See the Malicious Package and Dependency Confusion Guide.

Gem signing: when and how

RubyGems can sign gems with X.509 certificates created by gem cert --build, referenced from the gemspec signing_key and cert_chain fields, and verified with a trust policy (gem install -P HighSecurity or bundle install --trust-policy HighSecurity).

Trust policyChecksPractical value
NoSecurityNoneDefault behaviour
AlmostNoSecuritySignature matches certificate, no chain checkDescribed by Ruby docs as basically useless
LowSecuritySignature plus certificate expiryEasily spoofed
MediumSecurityFull chain to a root you explicitly trusted; unsigned gems allowedSignature can simply be stripped
HighSecurityAs Medium, and rejects unsigned gemsOnly workable for a small, closed set of internal gems

The Ruby documentation lists the limits plainly: no system-wide trust list, no CRL, OCSP or revocation, and the chain root must be self-signed. Use signing for a private gem set where you control every certificate; for public gems, rely on Trusted Publishing, checksums and sigstore attestations. See the Sigstore Guide.

Rolling it out

  1. Inventory: list every gem you publish, its owners and their MFA level, and every API key with its scopes and expiry.
  2. Accounts first: move all owners to WebAuthn and "UI and API", then ship rubygems_mfa_required in the next release of each gem.
  3. Pilot Trusted Publishing on one low-risk gem; keep the old key for one release as rollback, then delete it.
  4. Consumer controls in audit mode: add bundler-audit as a non-blocking CI step and checksums to lockfiles; fix findings for two weeks, then make the step blocking.
  5. Cooldown and source pinning: enable per project, starting with services that deploy daily; roll back by removing the setting if a release is urgently needed.
  6. Review quarterly: owners, keys, trusted publishers and environment protection rules.

Common misconfigurations

  • Full-scope keys in CI: a legacy-key or a key with owner scopes stored as a CI secret gives anyone who can run a workflow the power to add owners.
  • Trusted publisher without an environment: any workflow run of that file, on any branch a contributor can push to, can then request a token. Bind the publisher to a protected environment.
  • Owners nobody remembers: former colleagues and one-time contributors keep full push and yank rights until removed.
  • Sloppy gemspec files globs: Dir["**/*"] packages .env files and credentials, which webhooks spread to mirrors within moments.
  • Unpinned internal gems: a private gem name that also exists on rubygems.org can be resolved from the public source if it is not inside a source block.
  • Legacy clients and old sign-in flows: the GemStuffer RubyGems Campaign found sign-in responses for legacy gem signin clients being cached at the CDN, and RubyGems advised affected users to rotate keys. Keep RubyGems current with gem update --system and rotate keys created from old clients.

Framework mapping

Control areaNIST SP 800-53 Rev. 5NIST CSF 2.0Other
MFA for publishers and ownersIA-2(1), IA-5PR.AA-01, PR.AA-03ATT&CK T1078 Valid Accounts
Scoped, expiring API keys and Trusted PublishingIA-5PR.AA-01ATT&CK T1552.001 Credentials In Files
Checksums, attestations and signingSI-7, CM-14, SR-4, SR-11PR.PS-02ATT&CK T1195.002 Compromise Software Supply Chain
Dependency inventory, audit, cooldown, source pinningSR-3, CM-7ID.AM-02, GV.SC-07CIS Controls v8.1 16.4, 16.5; ATT&CK T1195.001
Release pipeline and monitoringSA-15DE.CM-09ISO/IEC 27001:2022 A.5.21, A.8.28

Practitioner checklist

  • Every owner of every gem you publish uses WebAuthn at the "UI and API" level, with recovery codes vaulted.
  • Each gemspec sets rubygems_mfa_required to "true".
  • Release engineers hold the Maintainer role, and owner lists are reviewed quarterly.
  • The legacy-key is deleted; remaining keys are gem-scoped, minimum-scope and expiring.
  • Releases go through Trusted Publishing from a protected GitHub environment with id-token: write at job level.
  • Gemspec files come from git ls-files, and built gems are inspected before push.
  • Application lockfiles carry CHECKSUMS and CI installs with BUNDLE_FROZEN or BUNDLE_DEPLOYMENT.
  • Internal gems sit in explicit source blocks, and a cooldown is set for public sources.
  • bundler-audit runs in CI and blocks on new advisories.
  • Owner-change emails and push webhooks feed a monitored channel.

Standards and references

Related NHI Mgmt Group resources: Package Registry Security Comparison Guide · Software Supply Chain Security Guide · Malicious Open Source Package Response Playbook · API Key Management Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 8 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.