Instant deployment with Fleet Managed Cloud. Join the beta
Welcome to the documentation for Fleet, the lightweight telemetry platform for servers and workstations.
Install osquery and FleetGet started
Can't find what you need?Support
This section outlines the release process at Fleet.
The current release cadence is once every three weeks and concentrates around Wednesdays.
To make sure we build quality releases, Fleet has a freeze period for testing prior to each release. Effective at the start of the freeze period, we will not merge new feature work.
When bugs are found during release testing, use the process documented in our handbook. Release bugs are exempt from the freeze period.
Note: Please prefix versions with
fleet-v4.0.0) in git tags, Helm charts, and NPM configs.
Update the CHANGELOG with the changes you made since the last
Fleet release. Use
make changelog to pull the changes files into
CHANGELOG.md, then manually
edit. When editing, order the most relevant/important changes at the time and try to make the
tone and syntax of the written language match throughout the document.
make changelog will stage all changes
file entries for deletion with the commit.
Add a "Performance" section below the list of changes. This section should summarize the number of hosts that the Fleet server can handle, call out if this number has changed since the last release, and list the infrastructure used in the load testing environment.
Update version numbers in the relevant files:
Commit these changes via Pull Request and pull the changes on the
main branch locally. Check that
HEAD of the
main branch points to the commit with these changes.
Tag and push the new release in Git:
git tag fleet-v<VERSION> git push origin fleet-v<VERSION>
origin may be
upstream depending on your
git remote configuration. The intent here
is to push the new tag to the
After the tag is pushed, GitHub Actions will automatically begin building the new release.
Wait while GitHub Actions creates and uploads the artifacts.
When the Actions Workflow has been completed:
Edit the draft release on the GitHub releases page. Use the version number as the release title. Use the below template for the release description (replace items in <> with the appropriate values):
### Changes <COPY FROM CHANGELOG> ### Upgrading Please visit our [update guide](https://fleetdm.com/docs/deploying/upgrading-fleet) for upgrade instructions. ### Documentation Documentation for Fleet is available at [fleetdm.com/docs](https://fleetdm.com/docs). ### Binary Checksum **SHA256** <COPY FROM checksums.txt>
When editing is complete, publish the release.
fleetctlon NPM. Run
npm publishin the fleetctl-npm directory. Note that NPM does not allow replacing a package without creating a new version number. Take care to get things correct before running
If releasing a "prerelease" of Fleet, run
npm publish --tag prerelease. This way, you can publish a prerelease of fleetctl while the most recent fleetctl npm package, available for public download, is still the latest official release.
Deploy the new version to Fleet's internal dogfood instance: https://fleetdm.com/handbook/engineering#deploying-to-dogfood.
In the #g-cx Slack channel, notify the @infrastructure-oncall of the release. This way, the @infrastructure-oncall individual can deploy the new version.
Announce the release in the #general channel.
Announce the release in the #fleet channel of osquery
update the channel's topic with the link to this release. Using
@here requires admin
permissions, so typically this announcement will be done by
Announce the release via blog post (on Medium) and Twitter (linking to blog post).
A patch release is required when a critical bug is found. Critical bugs are defined in our handbook.
The DRI for release testing/QA notifies the directly responsible individual (DRI) for creating the patch release branch to create the new branch, starting from the git tag of the prior release. Patch branches should be prefixed with
patch-. In this example we are creating
git checkout fleet-v4.3.0 git checkout --branch patch-fleet-v4.3.1
The DRI for creating the patch release branch cherry picks the necessary commits into the new branch:
git cherry-pick d34db33f
The DRI for creating the patch release branch pushes the branch to github.com/fleetdm/fleet:
git push origin patch-fleet-v4.3.1
patch-* branch is pushed, the Docker publish
be invoked to push a container image for QA with
fleetctl preview (eg.
fleetctl preview --tag patch-fleet-v4.3.1).
The DRI for creating the patch release branch checks in the GitHub UI that Actions ran successfully for this branch.
The DRI for creating the patch release branch notifies the DRI for release testing/QA that the branch is available for completing smoke tests.
The DRI for release testing/QA makes sure the standard release instructions at the top of this document are followed. Be sure that modifications to the changelog and config files are commited on the
The DRI for release testing/QA notifies the DRI for the release ritual that the patch release is ready. The DRI for the release ritual releases the patch.
The DRI for creating the patch release branch cherry-picks the commit containing the changelog updates into a new branch, and merges that commit into
main through a Pull Request.
Important! The DRI for creating the patch release branch manually checks the database migrations. Any migrations that are not cherry-picked in a patch must have a later timestamp than migrations that were cherry-picked. If there are new migrations that were not cherry-picked, verify that those migrations have later timestamps. If they do not, submit a new Pull Request to increase the timestamps and ensure that migrations are run in the appropriate order.
TODO #2850: Improve docs/tooling for this.
If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the Fleet repo.