How to Publish a Ruby Gem From CI

Build the gem with gem build and run gem push, authenticating through a credentials file from GEM_HOST_API_KEY, or via RubyGems OIDC trusted publishing.

CI builds the .gem with gem build, then gem push uploads it. Authentication uses the ~/.gem/credentials file, which you can populate from the GEM_HOST_API_KEY env var. RubyGems also supports OIDC trusted publishing, which avoids a stored key.

Steps

• Store a RubyGems API key as RUBYGEMS_API_KEY, or configure trusted publishing.
• Run gem build <name>.gemspec.
• Run gem push <name>-<version>.gem with GEM_HOST_API_KEY set.

Workflow

on:
  push:
    tags: ['v*']
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
      - run: gem build *.gemspec
      - run: gem push *.gem
        env:
          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}

Gotchas

• Pushing an existing version fails with Repushing of gem versions is not allowed.
• If MFA is set to require it for gem operations, use an API key with the push scope, not an interactive session.

Related guides