| name | foreman-plugin-release |
|---|---|
| description | Use when releasing a Foreman plugin gem - bumping version, tagging, pushing to rubygems, and updating upstream/downstream packaging |
Release process for Foreman plugins: bump version in-repo, tag, push (triggers rubygems publish via GitHub Actions), then trigger packaging updates.
git fetch upstream
# Create a worktree based on upstream/master to keep the main working directory clean
git worktree add /tmp/<plugin_name>-release upstream/master
cd /tmp/<plugin_name>-releaseRead the current version from lib/<plugin_name>/version.rb and recent commits/changelog to determine what changed since the last release. Apply versioning rules (see below) to propose the next version.
STOP: Present the suggested version to the user and wait for explicit approval before proceeding.
# Working inside /tmp/<plugin_name>-release
# Bump version file (lib/<plugin_name>/version.rb)
# Edit VERSION = "x.y.z"
git add lib/<plugin_name>/version.rb
git commit -m "Bump version to x.y.z"
git tag vx.y.z
# Push HEAD explicitly since this worktree is in detached-like state (not on local master)
git push upstream HEAD:master
git push upstream vx.y.z
# Remove the worktree
cd -
git worktree remove /tmp/<plugin_name>-releaseTag push triggers GitHub Actions release workflow → gem built and pushed to rubygems.org.
Verify it worked — either check GitHub Actions:
gh run list --repo theforeman/<plugin_name> --workflow release.yml --limit 5
gh run watch <run-id> --repo theforeman/<plugin_name>Or poll rubygems.org directly:
# Replace gem name and version as appropriate
curl -s https://rubygems.org/api/v1/versions/<gem_name>.json | \
python3 -c "import sys,json; vs=[v['number'] for v in json.load(sys.stdin)]; print('Found' if 'x.y.z' in vs else 'NOT found')"Don't proceed to upstream packaging until the gem is confirmed on rubygems.org.
Automation runs twice weekly comparing packaging vs rubygems. To trigger manually:
gh workflow run bump_packages.yml \
--repo theforeman/foreman-packaging \
-f package=MyPackageHereAfter triggering, wait for the automation to create PRs, then find and present them to the user:
# Poll until PRs appear (may take a few minutes)
gh pr list --repo theforeman/foreman-packaging --search "<gem_name>" --json number,title,urlPresent the PR links to the user. Usually two PRs per package (rpm + deb). Merge permission matches source repo permissions.
| Change | Version bump |
|---|---|
| Foreman dependency version requirement changes | Major |
| Required Ruby version changes | Major |
| New features | Minor |
| Bug fixes | Patch |
- Forgetting to push the tag (
git push upstream vx.y.z) — rubygems publish won't trigger - Pushing tag before the version bump commit — tag should point to the bump commit
- Targeting all packages in packaging workflow — prefer targeting individual packages with
package=filter - Using
rubygem-prefix in thepackage=parameter — that's RPM-specific; use the bare gem name - The
package=value is usually the gem name (with underscores), but foreman-tasks is an exception: useforeman-tasks(dashes), notforeman_tasks