Foreman 5.0.0 Release Process

[Zhunting]

This procedure was generated from procedures/foreman/release.md.erb at bbd576cd934227e488b070a397953a0934acf6fe

Make this post a wiki (help)

Roles

• Release Owner: @ogajduse
• Release Engineer: @ogajduse
• Installer Maintainer: @

Preparing code: 2026-09-08

Installer Maintainer

• Make patch releases of installer modules that have important changes
  • Branch to MAJ.MIN-stable if recent changes to the module aren’t suitable for patch (x.y.z) release

Release Owner

• Make sure any release blocking issues are resolved and remove/change target version field for any open Redmine tickets assigned to the release still (next minor, unset it or reject). Look for the 5.0.0 release TODO saved query on Foreman’s issues.
• Ensure that code in git matches issues fixed in 5.0.0 in Redmine. Use the 5.0.0 release DONE saved query on Foreman’s issues. issues can be used to generate a comparison between the two.
• Check for open pull requests in Foreman, smart-proxy, foreman-installer and foreman-selinux gh search prs --state=open --base=5.0-stable --repo=theforeman/foreman --repo=theforeman/smart-proxy --repo=theforeman/foreman-installer --repo=theforeman/foreman-selinux

Tagging a release: 2026-09-08

Release Owner

• Make sure foreman-5.0-stable-test and smart-proxy-5.0-stable-test are green using verify_green_jobs
• Run make -C locale tx-update in foreman 5.0-stable
• Update release version similar to here
• Tag the projects
  • Create tags using tag_project
  • Push tags using tag_push
• Update Redmine versions
  • Close old 5.0.x versions using close_redmine_version
  • Create new version 5.0.1 using create_redmine_version: ./create_redmine_version next
• Run the Jenkins Tarballs Release using release_tarballs to create tarballs

Release Engineer

• Sign Tarballs
  • download_tarballs
  • inspect_tarballs
  • Sign and upload detached signatures using sign_tarballs

Note: If for some reason there was an issue with the tarballs that required uploading new tarballs, CDN cache should be invalidated so that the builders use the updated tarballs.

Packaging a release: 2026-09-08

Note it is considered good practice to release on a day when the next day is a working day. This means no releases on Fridays or on the day before a holiday.

Release Engineer

Background documentation

• Update foreman-packaging branches
  • rpm/5.0 using bump_rpm_packaging
  • deb/5.0 using bump_deb_packaging
• Wait for packages to be built using wait_packaging (checks rpm/5.0 and deb/5.0). This takes a while so you can already start on the manual updates.
• Check for outstanding PRs against 5.0 packaging, and merge if possible:
  • rpm/5.0: gh pr list --repo theforeman/foreman-packaging --state open --base rpm/5.0
  • deb/5.0: gh pr list --repo theforeman/foreman-packaging --state open --base deb/5.0
• Sign the RPMs in the release
  • generate_stage_repository
  • sign_stage_rpms
  • upload_stage_rpms
• Sign RPMs for client repos (call scripts with PROJECT=client)
  • generate_stage_repository
  • sign_stage_rpms
  • upload_stage_rpms
• Kick off the release pipeline by calling release_pipeline
• Kick off the client pipeline by calling PROJECT=client ./release_pipeline
• Kick off the plugins pipeline by calling plugins_pipeline

Manual updates: 2026-09-08

Release Owner

• Update manual if applicable for any additional installation steps
• Update the website’s release notes section in the manual
  • Using the release notes script: ./scripts/release_notes.rb foreman 5.0.0
  • Append CLI release notes taken from the hammer-cli and hammer-cli-foreman changelogs, in theforeman.org.
  • Headline features: half a dozen important features with a few sentences description each
  • Upgrade warnings: all important notices that users must be aware of before upgrading
  • Deprecations: anything that will be removed in a future release
  • Submit this as a PR
• Update docs.theforeman.org
  • Using redmine_release_notes script (see README as well): ./guides/doc-Release_Notes/redmine_release_notes foreman 5.0.0 > ./guides/doc-Release_Notes/topics/foreman-5.0.0.adoc
  • Append CLI release notes taken from the hammer-cli and hammer-cli-foreman changelogs to foreman-5.0.0.adoc.
  • Make sure foreman-contributors.adoc is updated
  • Make sure headline features, upgrade warnings and deprecations are in sync with the website
  • Submit this as a PR
• Update the apipie docs and place those in the foreman/5.0/apidoc directory if any changes were made to the API

After the packages have been released

Release Owner

• Update theforeman.org
  • Update installer options section using the get-params script (Note: this step can only be done after packages are released)
  • Update _config.yml
    • Update the foreman_version to 5.0
    • Update foreman_latest_releases
• Update the docs.theforeman.org master
  • Update 5.0 as supported: sed -i '/"state":/ s/"[A-Za-z]\+",/"supported",/' web/releases/5.0.json
  • Update 5.-2 as unsupported: sed -i '/"state":/ s/"[A-Za-z]\+",/"unsupported",/' web/releases/5.-2.json
• Update the docs.theforeman.org 5.0 DocState as stable in attributes.adoc: sed -i '/:DocState:/ s/ .\+/ stable/' guides/common/attributes.adoc
• Update the docs.theforeman.org 5.-2 DocState as unsupported in attributes.adoc: sed -i '/:DocState:/ s/ .\+/ unsupported/' guides/common/attributes.adoc
• Announce the release on Discourse using release_announcement
• Update the topic in #theforeman channel on Matrix
• Update stable_release version in foreman-infra
• Create an issue in foreman-infra to archive old Debian releases (keeping 5.-5 and newer)
• Release pipeline will trigger foreman-plugins-5.0-deb-test-pipeline and foreman-plugins-5.0-rpm-test-pipeline. These don’t block releases but can be used to understand known issues around plugin compatibility with Foreman 5.0.
• Prepare 5.0.1 by updating the 5.0.0 release TODO and 5.0.0 release DONE saved queries on Foreman’s issues. Be sure to update both the name and individual filters.