👩‍👩‍👧‍👧 Kettle::Family

if ci_badges.map(&:color).detect { it != "green"} ☝️ let me know, as I may have missed the discord notification.

if ci_badges.map(&:color).all? { it == "green"} 👇️ send money so I can do more of this. FLOSS maintenance is now my full-time job.

I've summarized my thoughts in this blog post.

kettle-family coordinates repeated maintenance workflows across related Ruby gems. It can discover member gems, order them by dependency or explicit hints, run shared check/test/lint/docs/template workflows, bump aligned versions, and drive release preparation or publishing.

Families can be monorepos, sibling repository workspaces, or a single flat gem that releases from several long-lived branches. For branch-stacked gems, release.target_branches lists the branches to process; the release workflow checks each branch out sequentially, rediscovers that branch's gem metadata, and runs the normal flat-repo release flow.

Publish runs are resumable. Before invoking kettle-release, kettle-family checks whether the current gem/version is already published and skips it when it is, avoiding duplicate release-prep commits after a failure/fix/retry cycle. kettle-release runs its own kettle-pre-release gate for full publish flows; options such as start_step=N and --local-ci pass through, CI failures still abort by default, and gem signing passphrases are cached once per family run while RubyGems MFA prompts remain interactive unless an opt-in release secrets provider supplies them.

Tokens to Remember
Works with MRI Ruby 4
Support & Community
Source
Documentation
Compliance
Style
Maintainer 🎖️
... 💖	🧊 🐙 🛖 🧪

Compatible with MRI Ruby 4.0.0+, and concordant releases of JRuby, and TruffleRuby. CI workflows and Appraisals are generated for MRI Ruby 4.0.0+. This test floor is configured by ruby.test_minimum in .kettle-jem.yml and may be higher than the gem's runtime compatibility floor when legacy Rubies are not practical for the current toolchain.

The amazing test matrix is powered by the kettle-dev stack.

Gem	Source	Role	Daily download rank
appraisal2	GitHub	multi-dependency Appraisal matrix generation
appraisal2-rubocop	GitHub	RuboCop Appraisal generator integration
kettle-dev	GitHub	development, release, and CI workflow tooling
kettle-jem	GitHub	Appraisals & CI workflow templates
kettle-soup-cover	GitHub	SimpleCov coverage policy and reporting
kettle-test	GitHub	standard test runner and coverage harness
rubocop-lts	GitHub	Ruby-version-aware linting
turbo_tests2	GitHub	parallel test execution

Federated DVCS Repository	Status	Issues	PRs	Wiki	CI	Discussions
🧪 kettle-dev/kettle-family on GitLab	The Truth	💚	💚	💚	🐭 Tiny Matrix	➖
🧊 kettle-dev/kettle-family on CodeBerg	An Ethical Mirror (Donate)	💚	💚	➖	⭕️ No Matrix	➖
🐙 kettle-dev/kettle-family on GitHub	Another Mirror	💚	💚	💚	💯 Full Matrix	💚
🎮️ Discord Server		Let's	talk	about	this	library!

Available as part of the Tidelift Subscription.

The maintainers of this and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.

• 💡Subscribe for support guarantees covering all your FLOSS dependencies
• 💡Tidelift is part of Sonar
• 💡Tidelift pays maintainers to maintain the software you depend on!
  📊@Pointy Haired Boss: An enterprise support subscription is "never gonna let you down", and supports open source maintainers

Alternatively:

Install the gem and add to the application's Gemfile by executing:

bundle add kettle-family

If bundler is not being used to manage dependencies, install the gem by executing:

gem install kettle-family

kettle-family reads .kettle-family.yml from the family root by default. Use --config PATH to load a different file.

Member discovery is recursive under the family member search roots. Discovery skips gemspecs ignored by git and any configured members.exclude glob patterns before loading gemspec metadata, so fixture or temporary gemspecs do not create duplicate members. Exclude patterns are matched relative to the family root and to each member root.

Use members.roots as the normal configured member list. Each root is a member directory with one primary gemspec. When members.roots is present, kettle-family still discovers additional matching gems by default, includes them in the operative member set, and reports warnings so the config can be updated. Set members.discover: false when a family must operate only on the configured roots.

Use members.explicit only when the member directory and gemspec cannot be resolved by the one-gemspec rule. For example, use it when a member directory has multiple gemspecs or the intended gemspec filename does not match the directory.

family:
  members_root: gems

members:
  roots:
    - gems/alpha
    - gems/beta
  explicit:
    - root: gems/compat
      gemspec: compat-runtime.gemspec
  exclude:
    - "**/tmp/**"
    - "**/vendor/**"

Pre-release checks can skip project-specific volatile image URLs with shell-style URL patterns. Family release commands pass the active config path to member release commands so this setting works when releases run from member directories.

pre_release:
  image_url_skip_patterns:
    - https://assets.example.com/generated/*

Member branch-stack releases can be configured in the member repository itself:

release:
  target_branches:
    - r1_8-even-v0
    - r1_9-even-v2

Family root configs can override a member's branch targets explicitly by member name. Members not listed here still inherit their member-local branch target config when present.

release:
  member_target_branches:
    rubocop-lts:
      - r1_8-even-v0
      - r1_9-even-v2

Monorepo families whose member gems share release metadata from the repository root can configure readiness and changelog ownership explicitly:

family:
  name: structuredmerge-ruby
  local_path_env: STRUCTUREDMERGE_DEV

check:
  required_files:
    - Gemfile
    - Rakefile
    - README.md
    - LICENSE.md
  required_bins:
    - bin/rake
    - bin/rspec
  root_required_files:
    - CHANGELOG.md
    - SECURITY.md

changelog:
  mode: root
  path: CHANGELOG.md
  version_file: gems/tree_haver/lib/tree_haver/version.rb

release:
  env:
    KETTLE_DEV_DEV: false
  disable_local_path_env:
    - TSLP_DEV
  family_changelog:
    enabled: true
    command: bundle exec kettle-changelog

family.local_path_env names the environment variable that activates local path dependencies for this family. It is the family identity used by other families when they scan lockfile PATH remotes and need to disable local resolution before writing CI-facing release lockfiles. Configure it when the env name is not the default derived from family.name.

release.disable_local_path_env is different: it is an extra release-lockfile normalization shutoff list for path-injecting env vars that are not themselves discoverable as family roots, such as vendored parser/tooling paths.

For changelog.mode: root, release commands pass K_CHANGELOG_GEM_NAME as the configured family name and K_CHANGELOG_VERSION_FILE when version_file is configured, so kettle-changelog can operate from a repository root without a root gemspec.

For a flat repository that releases from multiple long-lived branches, list the release branches under release.target_branches. The branch list is processed in order. Each branch must be clean enough for git checkout, and each branch is treated as a normal flat gem after checkout.

release:
  target_branches:
    - r1_8-even-v0
    - r1_9-even-v2
    - r2_0-even-v4

Publish runs use bundle exec kettle-release by default, which means full publish flows inherit the kettle-pre-release gate from kettle-release. The release command can be overridden when a family needs a custom wrapper:

release:
  publish_command: bundle exec kettle-release

Resume and security-release options pass through to kettle-release. Passing --start-step N appends start_step=N; as with direct kettle-release usage, N > 1 resumes after the pre-release gate and should be used only after that gate already passed or the failure was intentionally handled:

kettle-family release --publish --start-step 10 --local-ci

Executed publish runs skip versions that are already published. CI failures abort by default; pass --continue-ci-failures to set K_RELEASE_CI_CONTINUE=true for the underlying kettle-release process.

Executed publish runs can also use a release secrets provider. The default provider is interactive. The 1password provider is supplied by kettle-dev, uses the local op CLI, and expects that op is installed, unlocked, and signed in before the release starts.

release:
  secrets:
    provider: 1password
    item: Rubygems
    gem_signing_passphrase_field: GEM-SIGN-PASSPHRASE
    rubygems_otp_field: one-time password

Use --secrets-provider 1password to opt in explicitly for a release run, or --secrets-provider interactive to force prompts even when the family config has a provider configured. Family publish runs pass --yes to child kettle-release commands by default, making release confirmation approval explicit instead of relying on terminal prompt detection. Pass --no-accept to leave child release confirmation prompts interactive. When publishing through kettle-release, kettle-family loads the signing passphrase once and passes the cached value to each child process; kettle-release still fetches RubyGems OTP values directly from 1Password at prompt time.

Inspect discovery and release plans before executing them:

kettle-family discover
kettle-family release

Audit changelog release state across the selected family members:

kettle-family release-state
kettle-family state

state is an alias for release-state. The release-state report lists each gem's current version.rb, latest versioned CHANGELOG.md section, latest published RubyGems release, latest GitHub release tag, transfer-changelog lag, whether pending changelog work exists in either Unreleased or an unpublished prepared release section, and how many commits the current branch is ahead of or behind the latest release tag. The version columns are ordered as V.rb, V.ch.md, V.rel, and GH.rel; GH.rel is prefixed with a red circle when it does not match V.rel.

Use release-state tokens with --only to select gems by state instead of by name. Multiple tokens are combined with logical AND, so this selects only gems that are both unreleased and pending. Status tokens cannot be mixed with member names in the same --only value.

kettle-family release-state --only pending
kettle-family release-state --only unreleased,prepared
kettle-family release --execute --only unreleased,pending

The supported release-state tokens are:

When --only is omitted, kettle-family bump defaults to --only bump and kettle-family release defaults to --only pending.

Most commands accept --json to print a machine-readable report instead of the text report, and --report PATH to write that JSON report while still printing the normal text report.

Plan or update GitHub Actions workflow SHA pins across the selected family members:

kettle-family gha-sha-pins
kettle-family gha-sha-pins --execute
kettle-family gha-sha-pins --execute --upgrade minor

Run release prep/build phases without publishing:

kettle-family release --execute

When a remote mirror is temporarily unavailable, skip it for the underlying kettle-release fetch/parity gate instead of removing the remote from each member repository:

kettle-family release --execute --publish --skip-remotes cb
kettle-family release --execute --publish --skip-remotes cb,mirror2

Publish through kettle-release. A full publish first runs the kettle-pre-release gate, then prompts once for the gem signing key password and leaves RubyGems MFA prompts interactive by default:

kettle-family release --publish --execute

By default, family publish runs pass --yes to child kettle-release commands. Use --no-accept when you want each child release command to ask its own confirmation prompts.

Executed publish runs can opt in to the local 1Password CLI for unattended release credentials. The gem signing passphrase is loaded once and cached only in memory for the current kettle-family process. When the publish command is kettle-release, that cached value is passed through an internal environment integration so child releases do not query 1Password repeatedly for the same passphrase. RubyGems OTP values are loaded by kettle-release when each MFA prompt arrives, so long releases do not reuse a stale TOTP from release startup.

release:
  secrets:
    provider: 1password
    item: Rubygems
    gem_signing_passphrase_field: GEM-SIGN-PASSPHRASE
    rubygems_otp_field: one-time password

kettle-family release --publish --execute --secrets-provider 1password

For vault-specific or field-specific references, configure explicit 1Password secret references. rubygems_otp_reference is read with op read; otherwise the OTP path uses op item get ITEM --otp.

release:
  secrets:
    provider: 1password
    account: my.1password.com
    gem_signing_passphrase_reference: op://Private/Rubygems/GEM-SIGN-PASSPHRASE
    rubygems_otp_reference: op://Private/Rubygems/one-time password?attribute=otp

If an old failed release left local unpublished versions installed and Bundler keeps selecting them, clean selected family members before retrying:

kettle-family clean-unreleased --execute

The cleanup command compares installed local gem versions with each member's latest released version and uninstalls only versions newer than the release state reports.

If a member lockfile has captured local sibling paths or checksum-less gem versions from local development, reset the selected members' Gemfile.lock files:

kettle-family reset Gemfile.lock
kettle-family reset Gemfile.lock --execute

reset Gemfile.lock runs each member's bundle exec kettle-reset release-lockfiles with configured, inferred, and path-like local *_DEV/*_LOCAL environment variables disabled. The member-level reset rewrites local sibling paths and checksum-less local gem versions back to released registry versions with sha256= checksums in Gemfile.lock and Appraisal.root.gemfile.lock. Executed family resets fail if the resulting lockfiles still contain sibling path remotes or checksum gaps.

Resume a failed family publish after fixing the failure. Already published versions are skipped automatically; start_step is passed to kettle-release for unreleased members that still need work. Use --start-step only after the pre-release gate already passed or the failure was intentionally handled:

kettle-family release --publish --execute --start-step 10

For security updates, publish locally before pushing commits/tags to remotes by passing --local-ci through to kettle-release:

kettle-family release --publish --execute --local-ci

If you intentionally need to continue after CI failures, opt in explicitly:

kettle-family release --publish --execute --continue-ci-failures

Bump aligned member versions with bump. The older bump-version command still works as a deprecated alias.

kettle-family bump --execute --only pending patch
kettle-family bump --execute --only unreleased minor

Run kettle-jem templating across the selected family members. Planning shows the commands that would run; --execute runs them. Executed templating defaults to a parallel job count based on CPU cores, capped for readability, and can be overridden with --jobs.

kettle-family template
kettle-family template --execute --jobs 4
kettle-family template --execute --only kettle-family

Templating uses kettle-jem --events as the default child interface, so executed runs stream member-prefixed progress while still keeping the final family report. Each member line includes a scheduled family-step counter and a per-member elapsed timer. Child kettle-jem events can still add progress marks, but only completed family steps advance the counter. Progress marks include:

Example progress:

templating 1 member with 1 job:
[kettle-family]   (0/4)   00:00 > prepare_lockfiles
[kettle-family]   (1/4)   00:01 . prepare_lockfiles
[kettle-family]   (2/4)   00:05 . prepare_template_dependencies
[kettle-family]   (3/4)   00:12 . template
[kettle-family]   (4/4)   00:13 . normalize_lockfiles
[kettle-family]   (4/4)   00:13 done 2 files changed
.
template summary: 1/1 members ok, 2 files changed

Use --verbose when you need kettle-jem verbose diagnostics layered on top of the event stream. Environment overrides pass through to every member workflow command, which is useful when templating against local unreleased dependencies.

kettle-family template --execute --verbose --jobs 1
kettle-family template --execute \
  --env K_JEM_TEMPLATING=true \
  --env STRUCTUREDMERGE_DEV=/home/me/src/structuredmerge/ruby/gems

See SECURITY.md.

If you need some ideas of where to help, you could work on adding more code coverage, or if it is already 💯 (see below) check issues or PRs, or use the gem and think about how it could be better.

We so if you make changes, remember to update it.

See CONTRIBUTING.md for more detailed instructions.

See CONTRIBUTING.md.

Everyone interacting with this project's codebases, issue trackers, chat rooms and mailing lists agrees to follow the .

Made with contributors-img.

Also see GitLab Contributors: https://gitlab.com/kettle-dev/kettle-family/-/graphs/main

This library follows for its public API where practical. For most applications, prefer the Pessimistic Version Constraint with two digits of precision.

For example:

spec.add_dependency("kettle-family", "~> 1.0")

Dropping support for a platform can be a breaking change for affected users. If a release changes supported platforms, it should be called out clearly in the changelog and versioned with that impact in mind.

To get a better understanding of how SemVer is intended to work over a project's lifetime, read this article from the creator of SemVer:

• "Major Version Numbers are Not Sacred"

See CHANGELOG.md for a list of releases.

The gem is available under the following license: AGPL-3.0-only. See LICENSE.md for details.

If none of the available licenses suit your use case, please contact us to discuss a custom commercial license.

See LICENSE.md for the official copyright notice.

• Copyright (c) 2026 Peter H. Boling

Maintainers have teeth and need to pay their dentists. After getting laid off in an RIF in March, and encountering difficulty finding a new one, I began spending most of my time building open source tools. I'm hoping to be able to pay for my kids' health insurance this month, so if you value the work I am doing, I need your support. Please consider sponsoring me or the project.

To join the community or get help 👇️ Join the Discord.

To say "thanks!" ☝️ Join the Discord or 👇️ send money.

💌 💌 💌

Many parts of this project are actively managed by a kettle-jem smart template utilizing StructuredMerge.org merge contracts.

Thanks for RTFM. ☺️