Skip to content

2. Triggering the workflow

Jump to bottom
Edouard CHIN edited this page Feb 19, 2026 · 1 revision

Manual trigger

Once the workflow generated by cibuildgem (refer to the installation page) lands on the default branch of your repository, visit the GitHub action page at https://github.com/<replace with your repository>/actions/workflows/cibuildgem.yaml and you'll be able to trigger a build.

image

Workflow breakdown

image

Compilation and packaging

This step runs the compilation for all platforms listed in the workflow and will compile a different binary for all minor Ruby versions the gem supports. Once the compilation is done for a platform, the workflow packages the gem with precompiled binaries.

Finally, the <gem_name>-<gem-version>-<gem-platform>.gem and <gem_name>-<gem-version>.gem (which doesn't include precompiled binaries) files as well as all unpackaged compilation artifacts are uploaded in a tarball to GitHub to be available for other jobs.

Testing phase

The tarball uploaded in the previous job is downloaded. A matrix of jobs kicks in and run the test suite. The matrix consists of 3 elements:

  1. The platforms the gem was compiled on.
  2. The minor Ruby versions supported by the gem.
  3. Binary target.

For example, a gem super-gem that supports Ruby 3.4 and Ruby 4 for which we want to precompile binaries on ubuntu-22 and arm64-darwin will have a matrix of 8 jobs to run.

  1. Ruby 3.3 on ubuntu-22 using the binary compiled during the compilation phase.
  2. Ruby 3.3 on ubuntu-22 without using the binary precompiled (compilation will take place again)
  3. Ruby 3.4 on ubuntu-22 using the binary ...
  4. Ruby 3.4 on ubuntu-22 without using the binary ...
  5. 4 more jobs similar for the arm64-darwin platform

Note

For extra safety before publishing a gem, the default workflow generated by cibuildgem will run the test suite agains both the compiled binaries for a specific Ruby version as well as run the test suite without using the precompiled binaries and will re-run a compilation. The latter is used to ensure the gem works for users that don't install gems with precompiled binaries.

Verification phase

The tarball uploaded during the compilation phase is downloaded. For every platforms the gem was compiled on, a new job is run and tries to install the .gem. This step ensures the gem can actually be installed.

Publishing phase

Once all previous jobs succeeds, all .gem files will be pushed to RubyGems.org.

Note

Publishing the gems requires to tick a box when you trigger the workflow.

image

Clone this wiki locally