fleet/tools/release/README.md

Releasing Fleet

Setup

This script release requires various secrets to utilize chat GPT for formatting as well as posting to Slack channels automatically

  OPEN_API_KEY           Open API key used for fallback if not provided via -o or --open-api-key option
  SLACK_GENERAL_TOKEN    Slack token to publish via curl to #general
  SLACK_HELP_INFRA_TOKEN Slack token to publish via curl to #help-infrastructure
  SLACK_HELP_ENG_TOKEN   Slack token to publish via curl to #help-engineering

This requires: jq gh git curl awk sed make ack grep

The script will check that each of these are installed and available before running

Make sure the repo is set to default (Needed only once)

  gh repo set-default

Before you begin

Make sure all tickets are tagged with the correct milestone.

Filter by both the milestone you expect and also double check no milestone to make sure you haven't missed anything, and that all tickets are in the correct GitHub Projects column.

Make sure you are on the main branch, and that you have all updates pulled locally.

Add the -d flag to any command to dry run and test the next step.

Minor Release

1. Create release candidate

./tools/release/publish_release.sh -m

This will create the minor release candidate branch, changelog PRs (main and RC branch), and the release QA issue.

2. Complete quality assurance

A Quality Assurance Engineer from each product group needs to confirm that their product group is ready before proceeding to the next step.

3. Merge changelog and version bump

Finalize and merge the two PRs. Check out the RC branch locally and pull the latest updates so that the changelog commit is the most recent commit on the branch.

4. Tag minor release

./tools/release/publish_release.sh -mg

Wait for build to run, which typically takes about fifteen minutes.

5. Publish minor release

./tools/release/publish_release.sh -muq

Wait for publish process to complete.

6. Update the fleetdm/terraform and fleetdm/fleet-gitops repos

Update all Fleet version references in our fleetdm/terraform repo and submit a PR. Then update DEFAULT_FLEETCTL_VERSION in .github/gitops-action/action.yml in fleetdm/fleet-gitops and submit a PR.

7. Merge milestone pull requests

Merge any pull requests associated with this release milestone, which include reference documentation, feature guides, and a release announcement article.

Wait for the release article to appear on the Fleet articles page.

8. Post to LinkedIn company page

When the release article is published, create a LinkedIn post on Fleet's company page. Copy the previous version announcement post, update the headline features and associated emojis, and update the URL to point to the new release article. Publish the LinkedIn post, then copy a link to the post.

Open the Fleet releaser script and search for a variable called linkedin_post_url. Change the associated value to the new LinkedIn post URL.

9. Announce release

./tools/release/publish_release.sh -mnu -v {current_version}

Change {current_version} to the current version that was just released. For example: ./tools/release/publish_release.sh -mnu -v 4.50.0.

Open the Fleet channels in the osquery Slack and MacAdmins Slack and update the topic to point to the new release.

10. Conclude the milestone

Complete the conclude the milestone ritual.

Patch release

1. Confirm commits, milestones, and cherry-picks

Ensure all tickets that you want in the patch release are milestoned to that release, and all PRs into main for associated work, including follow-ups, are linked to an issue with the milestone. For confidential issues, create a placeholder issue (e.g. https://github.com/fleetdm/fleet/issues/39483) to link against, as the patch release tooling does not interact with the confidential repo.

If a higher-version minor release RC is currently active, make sure all chosen commits are also in the RC branch, either because they were made before the RC cut or because they were cherry-picked in after the cut. For example, any commit landing in 4.80.1 should also land in 4.81.0, so when a new minor release goes GA users upgrading from a patch release don't experience regressions.

2. Create release candidate

./tools/release/publish_release.sh

This will create the patch release candidate branch, changelog PRs (main and RC branch), and the release QA issue.

3. Complete quality assurance

A Quality Assurance Engineer from each product group needs to confirm that their product group is ready before proceeding to the next step.

4. Merge changelog and version bump

Finalize and merge the two PRs. Check out the RC branch locally and pull the latest updates so that the changelog commit is the most recent commit on the branch.

5. Tag patch release

./tools/release/publish_release.sh -g

Wait for build to run, which typically takes about fifteen minutes.

6. Publish patch release

./tools/release/publish_release.sh -u

During the publish process, the release script will attempt to publish fleetctl to NPM. If this times out or otherise fails, you need to publish to NPM manually. From the /tools/fleetctl-npm/ directory, run npm publish.

7. Update the fleetdm/terraform and fleetdm/fleet-gitops repos

Update all Fleet version references in our fleetdm/terraform repo and submit a PR. Then, if this release is not a backport, update DEFAULT_FLEETCTL_VERSION in .github/gitops-action/action.yml in fleetdm/fleet-gitops and submit a PR.

8. Announce the release

The release script will announce the patch in the #general channel. Open the Fleet channels in the osquery Slack and MacAdmins Slack and update the topic to point to the new release.

9. Conclude the milestone

Complete the conclude the milestone ritual.

Using the Backport check script

./tools/release/backport-check.sh fleet-v4.81.0 rc-patch-fleet-v4.81.1 rc-minor-fleet-v4.82.0

Example output

Indexing rc-minor-fleet-v4.82.0 since merge-base with fleet-v4.81.0 (6e9d46202e9b54e1b83542179f40ed880586d3f4)...

=== INCLUDED (present on rc-minor-fleet-v4.82.0) ===
STATUS     PATCH_SHA     MINOR_SHA     MATCH     SUBJECT
--------   ------------  ------------  --------  ----------------------------------------
INCLUDED   8798f6cee5ea  b1d0a5c2da8c  subject   End user UI: Update logo loading spinner styling (#39234)
INCLUDED   67c2d503f23d  fa4b7426f1db  subject   End user /enroll page for macOS: Download button should have semi-bold font weight (#39301)
INCLUDED   1f09d64f4df7  fac6ca5f2afd  subject   Add ellipsis to cut-off placeholder text in search fields (#39112)
INCLUDED   a3c6f7e3a1c6  ba1862595e4e  subject   Add route for Microsoft Entra home page (for tenant ID) (#39216)
...
INCLUDED   4ec78002e0d6  3b825449757f  subject   Set secure cookie in SSO callback (#40765) (#40806)

=== MISSING (not found on rc-minor-fleet-v4.82.0) ===
STATUS     PATCH_SHA     SUBJECT
--------   ------------  ----------------------------------------
MISSING    cb08454ddfef  improve windows resending (#40365)
MISSING    3ef6f40a10fc  Batch select query in CleanupExcessQueryResultRows (#40491)
MISSING    9e64a65f29c9  Improved validation for packages (#40407)
MISSING    5df0a554fe1d  Add migration to update host_certificates_template UUID column size (… (#40709)
MISSING    82890f883369  Exorcise edited_enroll_secrets from v4.81.1 (#40714)
MISSING    1adbfb89429b  Cherry-pick: Remove "do not enqueue setup experience items >24 hours after enrollment" logic for macOS hosts (#40739) (#40748)
MISSING    ac068800375a  Adding changes for Fleet v4.81.1 (#40704)
MISSING    729c324074c3  Avoid panics on VPP install command errors when command not initiated by Fleet VPP install -> 4.81.0 (#40395)

For each item in missing you can verify manually by opening the PR's at the end of each line to trace back to the original issue and validate if a related PR made it into the minor branch you are targeting.

To include any code missed checkout the minor branch, branch off into a new branch to pull them in and then git cherry-pick <patch_sha> to add the missing code. Resolve any conflicts and open a PR based off the minor branch.