OpenVox Release Playbook

OpenVox Agent

1. Ensure dependency bumps are merged into puppet-runtime, including running Update Components to bump all the Ruby gems, and manually updating the other components such a Ruby, Curl, and OpenSSL to new versions if needed.

2. Run prepare -> release -> build. Build agent-runtime-main (OpenVox 9) and/or agent-runtime-8.x (OpenVox 8).

3. Use the promote action to promote the version of puppet-runtime you just built into openvox. Ensure you select the correct target branch to promote into (main for OpenVox 9 and 8.x for OpenVox 8).

4. If there is a new version of OpenFact since the last release, use the same promote action to promote that version to the target branch as well.

5. (Optional) Run the Build openvox-agent action, giving it the branch name (main for OpenVox 9 or 8.x for OpenVox 8). This will build unsigned test versions of the packages and uploads them to the artifacts S3 bucket. You can find the version of the build by inspecting the "Upload output to S3" step in the build action for any of the platforms.

6. (Optional) Ask the community to beta test these packages and highlight any issues so they can be fixed before release. If there are fixes needed, repeat the steps above as appropriate.

7. Run the Beaker Acceptance Pipeline for OpenVox with Pre-release build checked and the new version you are releasing + the latest release of the other components you aren't releasing. Ensure everything is green.

8. Run the Prepare release action, inspect the CHANGELOG in the result PR, and merge the PR.

9. Run the Release action. Previously, this would fail on the step where it tries to bump the version, because we don't do that for this repo. But the release would be cut anyway. I think this is now fixed since the last release where this failed, though. Note: you do not need to run the "Gem Release" action. This will run automatically when the release action tags the repo.

10. Edit the release notes and add a short summary of the changes, and include a list of CVEs fixed. You will likely need to look at the changes in puppet-runtime and look at the changelog of each component to find if they include CVEs in order to generate this list. If you're unsure how to find this information, ask for help in the #sig-security channel.

11. Run the Build openvox-agent action. This builds all of the unsigned packages and uploads them to the artifacts S3 bucket.

12. Follow the Sign and Release process below.

13. Make an announcement in the #announce channel about the release, including the list of CVEs fixed and a link to the release notes in the GitHub repo.

OpenVox Server

1. Ensure all dependency bumps are merged in.

   • If any of the openvoxproject clojure sub-components need updating, you'll need to do the whole process of building those in the right order to avoid leiningen being cranky about differing dependency versions. Note that there is currently a circular dependency between clj-http-client and trapperkeeper-webserver-jetty10 around dependencies that are only for tests, but lein will still be unhappy and you may need to merge the bump of one of them with tests being red.
   • For OpenVox Server 8, note that we must remain on logback 1.3.x, ring-core 1.14.x, and Bouncy Castle 1.x (all of the various jars for org.bouncycastle).

2. (Optional) Run the Build openvox-server and Build openvox-server - FIPS platforms actions, giving it the branch name (main for OpenVox 9 or 8.x for OpenVox 8). This will build unsigned test versions of the packages and uploads them to the artifacts S3 bucket. You can find the version of the build by inspecting the "Upload output to S3" step in the build action for any of the platforms.

3. (Optional) Ask the community to beta test these packages and highlight any issues so they can be fixed before release. If there are fixes needed, repeat the steps above as appropriate.

4. Run the Beaker Acceptance Pipeline for OpenVox with Pre-release build checked and the new version you are releasing + the latest release of the other components you aren't releasing. Ensure everything is green.

5. Manually run bundle exec rake changelog and merge in the updates. We'll change this in the future to be part of automation. Do not change any version strings. The lein release process later will bump them accordingly, and the changelog action will automatically strip the -SNAPSHOT off of the current unreleased version string.

6. Run Release and publish package to clojars -> Build openvox-server and Build openvox-server - FIPS platforms.

7. Edit the release notes and add a short summary of the changes, and include a list of CVEs fixed. You will likely need to look at the changes in puppet-runtime and look at the changelog of each component to find if they include CVEs in order to generate this list. If you're unsure how to find this information, ask for help in the #sig-security channel.

8. Follow the Sign and Release process below.

9. Make an announcement in the #announce channel about the release, including the list of CVEs fixed and a link to the release notes in the GitHub repo.

OpenVoxDB

1. Ensure all dependency bumps are merged in.

   • If any of the openvoxproject clojure sub-components need updating, you'll need to do the whole process of building those in the right order to avoid leiningen being cranky about differing dependency versions.
   • For OpenVoxDB 8, note that we must remain on ring-core 1.14.x and Bouncy Castle 1.x (all of the various jars for org.bouncycastle).

2. (Optional) Run the Build openvoxdb and Build openvoxdb - FIPS platforms actions, giving it the branch name (main for OpenVox 9 or 8.x for OpenVox 8). This will build unsigned test versions of the packages and uploads them to the artifacts S3 bucket. You can find the version of the build by inspecting the "Upload output to S3" step in the build action for any of the platforms.

3. (Optional) Ask the community to beta test these packages and highlight any issues so they can be fixed before release. If there are fixes needed, repeat the steps above as appropriate.

4. Run the Beaker Acceptance Pipeline for OpenVox with Pre-release build checked and the new version you are releasing + the latest release of the other components you aren't releasing. Ensure everything is green.

5. Manually run bundle exec rake changelog and merge in the updates. We'll change this in the future to be part of automation. Do not change any version strings. The lein release process later will bump them accordingly, and the changelog action will automatically strip the -SNAPSHOT off of the current unreleased version string.

6. Run Release and publish package to clojars -> Build openvoxdb and Build openvoxdb - FIPS platforms.

7. Edit the release notes and add a short summary of the changes, and include a list of CVEs fixed. You will likely need to look at the changes in puppet-runtime and look at the changelog of each component to find if they include CVEs in order to generate this list. If you're unsure how to find this information, ask for help in the #sig-security channel.

8. Follow the Sign and Release process below.

9. Make an announcement in the #announce channel about the release, including the list of CVEs fixed and a link to the release notes in the GitHub repo.

OpenBolt

1. Ensure dependency bumps are merged into puppet-runtime, including running Update Components to bump all the Ruby gems, and manually updating the other components such a Ruby, Curl, and OpenSSL to new versions if needed.

2. Run prepare -> release -> build. Build openbolt-runtime

3. Use the promote action to promote the version of puppet-runtime you just built into OpenBolt.

4. (Optional) Run the Build openbolt action, giving it the branch name (main). This will build unsigned test versions of the packages and uploads them to the artifacts S3 bucket. You can find the version of the build by inspecting the "Upload output to S3" step in the build action for any of the platforms.

5. (Optional) Ask the community to beta test these packages and highlight any issues so they can be fixed before release. If there are fixes needed, repeat the steps above as appropriate.

6. Run the Prepare release action, inspect the CHANGELOG in the result PR, and merge the PR.

7. Run the Release action. Note: you do not need to run the "Gem Release" action. This will run automatically when the release action tags the repo.

8. Edit the release notes and add a short summary of the changes, and include a list of CVEs fixed. You will likely need to look at the changes in puppet-runtime and look at the changelog of each component to find if they include CVEs in order to generate this list. If you're unsure how to find this information, ask for help in the #sig-security channel.

9. Run the Build openbolt action. This builds all of the unsigned packages and uploads them to the artifacts S3 bucket.

10. Follow the Sign and Release process below.

11. Make an announcement in the #announce channel about the release, including the list of CVEs fixed and a link to the release notes in the GitHub repo.

Sign and Release

Note: This repo has limited permissions on who can run things for security purposes. If you are not on the release team, ask a team member in #sig-release to do this process.

1. Run the Reset Test Repos action to make the test repos match the current state of production repos.

2. Run the Release action, leaving Deploy to production unchecked. This process will sign the packages and deploy them to the test repo, then verify that package managers can see the new packages.

3. (Optional) The above process is fairly self-checking, but it is a good idea to do a manual check on a few platforms that the packages install cleanly. The openvox*-release release packages in the test repos (e.g. openvox8-release-ubuntu24.04.deb) are created to point to this test repo rather than the production repo to facilitate manual testing.

4. Run the Release action, this time checking Deploy to production. This process will sign the packages and deploy them to the production repo, then verify that package managers can see the new packages.

5. If there is a bug in the released version, release a new version. But if there is a problem with the deployment to the repos themselves and the repos are broken, follow the instructions in the README to perform a rollback, or in the very worst cases if packages and big parts of the repo are gone, a restore.

6. Either wait for the voxpupuli.org mirrors to sync (they do every hour), or trigger a sync. If you have SSH access to the mirror, you can run the ~/reposync script to do this on demand. Be aware there is no locking mechanism, so if the cron jobs kick in at the same time, you might see errors, but it seems to be harmless when it happens.

7. If openvox-agent or openbolt was released, update the version numbers and checksums in OpenVoxProject/homebrew-openvox