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,pushand 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
sourceblocks 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 credential | Used for | Where it lives | Main risk |
|---|---|---|---|
| RubyGems.org account (email, password, MFA) | Web UI, gem signin, owner management | RubyGems.org | Phishing 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_KEY | Long-lived by default; leaks from laptops, CI logs and packaged gems |
| Trusted publisher (OIDC) | Push from a specific GitHub Actions workflow | Configured per gem on RubyGems.org | Over-broad workflow, missing environment protection |
| Gem owner or maintainer role | Push and yank; owners also manage owners and Trusted Publishing | Per gem | Stale or untrusted co-owners |
Signing certificate (gem cert) | Optional package signatures | Author's key file and the gemspec cert_chain | Unprotected 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 --addandowner --removerequire MFA, and MFA applies to every API key. - UI and gem signin: UI and
gem signinrequire 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.
| Action | Gem owner | Gem maintainer | Org owner | Org admin | Org maintainer |
|---|---|---|---|---|---|
| Push new versions | Yes | Yes | Yes | Yes | Yes |
| Yank versions | Yes | Yes | Yes | Yes | Yes |
| Add or remove owners or members | Yes | No | Yes | Yes (not Owners) | No |
| Configure OIDC and Trusted Publishing | Yes | No | Not stated separately in the org docs | ||
| Add or remove gems in the organisation | n/a | n/a | Add and remove | Add only | No |
| Update or delete the organisation | n/a | n/a | Yes | No | No |
- 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.
| Scope | Allows | Typical holder |
|---|---|---|
index_rubygems | List the account's gems | Inventory scripts |
push_rubygem | Create a gem or publish a version of any owned gem | Release job (scope to one gem) |
yank_rubygem | Remove a published version | Human, short expiry |
add_owner / remove_owner | Change gem owners | Human only; never CI |
access_webhooks | List, create, delete and fire webhooks | Mirror or notification integration |
show_dashboard | Dashboard Atom feed; exclusive, cannot be combined | Feed 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-keymigrated to all scopes. Delete it, rungem signouton 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_KEYfrom 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.
- 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.
- Protect the
releaseenvironment in GitHub with required reviewers and tag rules, so only an approved release can request the token. - Grant
permissions: id-token: writeat job level, not workflow level, and check out withpersist-credentials: false. - Use the
rubygems/release-gemaction, which configures the credentials and runsbundle exec rake release. Itsattestationsinput (marked experimental, default true) adds sigstore attestations and only works through Trusted Publishing. - If you call a reusable workflow from another repository, fill in Workflow Repository Owner and Name, because the token's
job_workflow_refclaim points at the reusable workflow. - 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.
| Signal | Where | What to look for |
|---|---|---|
| Last access per API key | Settings, API KEYS | Use of a key outside release windows; keys never used (delete) |
| Owner addition and removal emails | All owners' inboxes | Unplanned changes; route to a shared security mailbox |
| Push webhooks | Your receiver | A version that no tagged CI run produced |
| Owners page MFA column | Gem owners page | Any owner without MFA |
| Attestations API | GET /api/v1/attestations/<gem>-<version>.json | Releases of your gem without the expected sigstore bundle |
| bundler-audit results | CI logs | New advisories from ruby-advisory-db; insecure http:// or git:// sources |
| Bundler install failures | CI logs | Checksum 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_requiredset to "true" in every gemspec. - Package contents: build the gemspec
fileslist from an allowlist such asgit ls-files, not a broad glob, and inspect the built gem withgem unpackbefore 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)
| Control | Setting | Gap it closes |
|---|---|---|
| Lockfile checksums | Default for new lockfiles (lockfile_checksums true); add to old ones with bundle lock --add-checksums | Gem tampered with after the lockfile was written (SHA-256 of the .gem file) |
| Frozen installs | BUNDLE_FROZEN=true or BUNDLE_DEPLOYMENT=true in CI and production | Silent lockfile changes during deploy |
| Never disable checksum validation | Keep disable_checksum_validation unset | Installing gems that fail RubyGems' checksum |
| Cooldown | bundle config set cooldown 7 or source "https://rubygems.org", cooldown: 7; internal source cooldown: 0 | Malicious releases installed before the ecosystem detects and yanks them |
| Source pinning | Every internal gem inside a source "https://gems.internal" do ... end block, every gem with an explicit source | Dependency confusion with a public gem of the same name |
| Vulnerability audit | bundle-audit in CI against ruby-advisory-db | Known 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 policy | Checks | Practical value |
|---|---|---|
| NoSecurity | None | Default behaviour |
| AlmostNoSecurity | Signature matches certificate, no chain check | Described by Ruby docs as basically useless |
| LowSecurity | Signature plus certificate expiry | Easily spoofed |
| MediumSecurity | Full chain to a root you explicitly trusted; unsigned gems allowed | Signature can simply be stripped |
| HighSecurity | As Medium, and rejects unsigned gems | Only 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
- Inventory: list every gem you publish, its owners and their MFA level, and every API key with its scopes and expiry.
- Accounts first: move all owners to WebAuthn and "UI and API", then ship
rubygems_mfa_requiredin the next release of each gem. - Pilot Trusted Publishing on one low-risk gem; keep the old key for one release as rollback, then delete it.
- 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.
- 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.
- Review quarterly: owners, keys, trusted publishers and environment protection rules.
Common misconfigurations
- Full-scope keys in CI: a
legacy-keyor 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
filesglobs:Dir["**/*"]packages.envfiles 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
sourceblock. - Legacy clients and old sign-in flows: the GemStuffer RubyGems Campaign found sign-in responses for legacy
gem signinclients being cached at the CDN, and RubyGems advised affected users to rotate keys. Keep RubyGems current withgem update --systemand rotate keys created from old clients.
Framework mapping
| Control area | NIST SP 800-53 Rev. 5 | NIST CSF 2.0 | Other |
|---|---|---|---|
| MFA for publishers and owners | IA-2(1), IA-5 | PR.AA-01, PR.AA-03 | ATT&CK T1078 Valid Accounts |
| Scoped, expiring API keys and Trusted Publishing | IA-5 | PR.AA-01 | ATT&CK T1552.001 Credentials In Files |
| Checksums, attestations and signing | SI-7, CM-14, SR-4, SR-11 | PR.PS-02 | ATT&CK T1195.002 Compromise Software Supply Chain |
| Dependency inventory, audit, cooldown, source pinning | SR-3, CM-7 | ID.AM-02, GV.SC-07 | CIS Controls v8.1 16.4, 16.5; ATT&CK T1195.001 |
| Release pipeline and monitoring | SA-15 | DE.CM-09 | ISO/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_requiredto "true". - Release engineers hold the Maintainer role, and owner lists are reviewed quarterly.
- The
legacy-keyis deleted; remaining keys are gem-scoped, minimum-scope and expiring. - Releases go through Trusted Publishing from a protected GitHub environment with
id-token: writeat job level. - Gemspec
filescome fromgit ls-files, and built gems are inspected before push. - Application lockfiles carry CHECKSUMS and CI installs with
BUNDLE_FROZENorBUNDLE_DEPLOYMENT. - Internal gems sit in explicit
sourceblocks, 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
- RubyGems: Security
- RubyGems: Setting up multi-factor authentication
- RubyGems: Trusted Publishing
- RubyGems: API key scopes
- RubyGems: How to delay new gem versions with cooldown
- Ruby: Gem::Security documentation
- RubySec: bundler-audit
- MITRE ATT&CK: Compromise Software Dependencies and Development Tools
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