To set up RubyGems trusted publishing, open your gem on rubygems.org, add a trusted publisher naming your GitHub owner, repository and workflow file, then give that workflow job the id-token write permission. Pushing a version tag then releases the gem with no stored API key.
What trusted publishing replaces
Most gem releases still rely on an API key sitting in a CI secret. If that key leaks, anyone who finds it can push a new version. Trusted publishing swaps the stored key for a short-lived identity token.
Per the RubyGems guide, the CI provider issues the token through OpenID Connect (OIDC), and RubyGems.org exchanges it for a short-lived API token that can push only to the gems that trust that workflow. The guide describes setup for GitHub Actions.
Setup for a gem that already exists
- Open your profile on rubygems.org and select the gem.
- As an owner, click "Trusted publishers" in the right sidebar.
- Click Create.
- Enter the GitHub owner name, repository name and workflow file name. The environment name is optional, and the guide suggests
release. - Save the publisher.
Setup for a gem you have not published yet
Use the pending trusted publisher page at rubygems.org/profile/oidc/pending_trusted_publishers. It takes the same fields plus the gem name. After the first successful push, the pending entry becomes a normal trusted publisher and you become the gem's owner.
Be aware that a pending publisher holds a gem name for your workflow. Use a name you actually plan to ship, and register it only when you are ready to push.
The workflow file
name: Push gem
on:
push:
tags: ["v*"]
jobs:
push:
runs-on: ubuntu-latest
permissions:
contents: write
id-token: write
environment: release
steps:
- uses: actions/checkout@v5
with:
persist-credentials: false
- uses: ruby/setup-ruby@v1
with:
bundler-cache: true
ruby-version: ruby
- uses: rubygems/release-gem@v1
Three details from the guide matter:
| Detail | What to do |
|---|---|
| id-token: write | Required. Set it on the job, not the whole workflow. |
| Environment | If you set one on RubyGems, the workflow must use the same one. |
| Reusable workflows | Fill in the workflow repository owner and name only if the file lives in another repository. |
Consider pinning the third party actions to commit SHAs, as covered in pin GitHub Actions to a SHA or a tag. A release job holds more power than a test job.
After the switch
Delete the old API key from your CI secrets and revoke it on rubygems.org. A trusted publisher that sits beside a still valid key does not reduce your exposure much. Pair this with the MFA setting described in the RubyGems MFA guide so an owner account cannot be used to push by hand without a second factor.
You can also gate the job with a GitHub environment that needs a reviewer. See required reviewers for deployment approval.
One short note on Safeguard: it can scan your gem's dependencies and generate an SBOM, and the free scan at gold.safeguard.sh/scan is a quick way to see what you ship.
Quick check
Do I still need an API key after enabling trusted publishing?
Not for pushes from the trusted workflow. Remove stored keys you no longer need, and revoke them.
Can one workflow publish several gems?
Yes. The guide says a repository and workflow can serve multiple gems, and a gem can allow multiple publishers.
Sources
Last reviewed: 19 October 2026.
