This page covers the steps to perform when releasing a new version of Velero.
- Please read the documented variables in each script to understand what they are for and how to properly format their values.
- You will need to have an upstream remote configured to use to the
You can check this using
git remote -v.
The release script (
tag-release.sh) will use
upstream as the default remote name if it is not specified using the environment variable
- GA release: major and minor releases only. Example: 1.0 (major), 1.5 (minor).
- Pre-releases: Any release leading up to a GA. Example: 1.4.0-beta.1, 1.5.0-rc.1
- RC releases: Release Candidate, contains everything that is supposed to ship with the GA release. This is still a pre-release.
Velero Release Requirements
Velero is on a “train leaves the station” model for releases. We will generate a release candidate (RC)
at the scheduled time. Multiple release candidates may be generated, depending on if bugs are found during testing.
When testing has passed a release build will be generated.
Release Candidate criteria
The release candidate commit must meet the following criteria:
- No major bugs outstanding
- Unit tests pass
- E2E tests against latest Kubernetes on AWS, vSphere and kind pass
Once the release has moved to RC, a code freeze is in effect. Only changes needed to release are allowable.
In order for a release candidate to be released, it must meet the following criteria:
- Unit tests pass
- E2E tests against latest K8S and earliest supported K8S on Azure, vSphere, Kind, AWS, GCP
- Manual tests pass (manual tests will be converted to automated testing)
When bugs are identified by any of these methods, we will determine whether the bug is a release blocker or not and
a fix generated if it is. When release blocker bugs identifies in an release candidate are fixed, another RC will
be generated and the test cycle will restart.
Create release blog post (GA only)
For each major or minor release, create and publish a blog post to let folks know what’s new. Please follow these
Changelog and Docs PR
- If you encounter the error
You don't have enough free space in /var/cache/apt/archives/ when running
make serve-docs: run
docker system prune.
- If it doesn’t already exist: in a branch, create the file
changelogs/CHANGELOG-<major>.<minor>.md by copying the most recent one.
- Update the file
make changelog to generate a list of all unreleased changes.
- Copy/paste the output into
CHANGELOG-<major>.<minor>.md, under the “All Changes” section for the release.
- You may choose to tweak formatting on the list of changes by adding code blocks, etc.
- Update links at the top of the file to point to the new release version
- Update the main
CHANGELOG.md file to properly reference the release-specific changelog file
- Under “Current release”:
- Should contain only the current GA release.
- Under “Development release”:
- Should contain only the latest pre-release
- Move any prior pre-release into “Older releases”
- GA Only: Remove all changelog files from
- Generate new docs
make gen-docs, passing the appropriate variables. Examples:
VELERO_VERSION=v1.5.0-rc.1 NEW_DOCS_VERSION=v1.5.0-rc.1 make gen-docs.
VELERO_VERSION=v1.5.0 NEW_DOCS_VERSION=v1.5 make gen-docs).
PREVIOUS_DOCS_VERSION=<doc-version-to-copy-from> is optional; when not set, it will default to the latest doc version.
- Clean up when there is an existing set of pre-release versioned docs for the version you are releasing
site/content/docs/v1.5.0-beta.1 exists, and you’re releasing
- Remove the directory containing the pre-release docs, i.e.
- Delete the pre-release docs table of contents file, i.e.
- Remove the pre-release docs table of contents mapping entry from
- Remove all references to the pre-release docs from
- Create the “Upgrade to $major.minor” page if it does not already exist (
If it already exists, update any usage of the previous version string within this file to use the new version string instead (
This needs to be done in both the versioned and the
- Review and submit PR
- Follow the additional instructions at
site/README-HUGO.md to complete the docs generation process.
- Do a review of the diffs, and/or run
make serve-docs and review the site.
- Submit a PR containing the changelog and the version-tagged docs.
Pin the base image
The image of velero is built based on
Distroless docker image.
For the reproducibility of the release, before the release candidate is tagged, we need to make sure the in the Dockerfile
on the release branch, the base image is referenced by digest, such as
- Pre-requisite: PR with the changelog and docs is merged, so that it’s included in the release tag.
- This process is the same for both pre-release and GA.
- Refer to the
General notes above for instructions.
- If the dry-run fails with random errors, try running it again.
- Manually create the release branch on Github, in the form like
- Create a tagged release in dry-run mode
- This won’t push anything to GitHub.
VELERO_VERSION=v1.9.0-rc.1 REMOTE=<upstream-remote> GITHUB_TOKEN=REDACTED ON_RELEASE_BRANCH=TRUE ./hack/release-tools/tag-release.sh.
- Fix any issue.
- Create a tagged release and push it to GitHub
VELERO_VERSION=v1.9.0-rc.1 REMOTE=<upstream-remote> GITHUB_TOKEN=REDACTED ON_RELEASE_BRANCH=TRUE ./hack/release-tools/tag-release.sh publish.
- Publish the release
- Navigate to the draft GitHub release at https://github.com/vmware-tanzu/velero/releases and edit the release.
- If this is a patch release (e.g.
v1.9.1), note that the full
CHANGELOG-1.9.md contents will be included in the body of the GitHub release. You need to delete the previous releases’ content (e.g.
v1.9.0's changelog) so that only the latest patch release’s changelog shows.
- Do a quick review for formatting.
- Note: the
goreleaser process should have detected if it’s a pre-release version and, if so, checked the box at the bottom of the GitHub release page appropriately, but it’s always worth double-checking.
- Verify that GitHub has built and pushed all the images (it takes a while): https://github.com/vmware-tanzu/velero/actions
- Verify that the images are on Docker Hub: https://hub.docker.com/r/velero/velero/tags
- Verify that the assets were published to the GitHub release
- Publish the release.
- Test the release
- By now, the Docker images should have been published.
- Perform a smoke-test - for example:
- Download the CLI from the GitHub release
- Use it to install Velero into a cluster (or manually update an existing deployment to use the new images)
- Verify that
velero version shows the expected output
- Run a backup/restore and ensure it works
Homebrew release (GA only)
These are the steps to update the Velero Homebrew version.
- If you don’t already have one, create a
GitHub access token for Homebrew
export HOMEBREW_GITHUB_API_TOKEN=your_token_here on your command line to make sure that
brew can work on GitHub on your behalf.
hack/release-tools/brew-update.sh. This script will download the necessary files, do the checks, and invoke the brew helper to submit the PR, which will open in your browser.
- Update Windows Chocolatey version. From a Windows computer, follow the step-by-step instructions to
create the Windows Chocolatey package for Velero CLI
To release plugins maintained by the Velero team, follow the
plugin release instructions.
After the plugin images are built, be sure to update any
e2e tests that use these plugins.
Helm Chart (GA only)
- Update the CRDs under helm chart folder
crds according to the current Velero GA version, and add the labels for the helm chart CRDs. For example: https://github.com/vmware-tanzu/helm-charts/pull/248.
- Bump the Chart version
version on the
- Bump the Velero version
appVersion on the
Chart.yaml file and
tag on the
- Bump the plugin version on the
values.yaml if needed.
- Update the upgrade instruction and related tag on the
How to write and release a blog post
What to include in a release blog:
- Thank all contributors for their involvement in the release.
- Where possible shoutout folks by name or consider spotlighting new maintainers.
- Highlight the themes, or areas of focus, for the release. Some examples of themes are security, bug fixes, feature improvements. See past Velero
release blog posts for more examples.
- Include summaries of new features or workflows introduced in a release.
- This can also include new project initiatives, like a code-of-conduct update.
- Consider creating additional blog posts that go through new features in more detail. Plan to publish additional blogs after the release blog (all blogs don’t have to be publish all at once).
Release blog post PR:
- Prepare a PR containing the release blog post. Read the
website guidelines for more information on creating a blog post. It’s usually easiest to make a copy of the most recent existing post, then replace the content as appropriate.
- You also need to update
site/index.html to have “Latest Release Information” contain a link to the new post.
- Plan to publish the blog post the same day as the release.
Announce a release
Once you are finished doing the release, let the rest of the world know it’s available by posting messages in the following places.
- GA Only: Merge the blog post PR.
- Velero’s Twitter account. Maintainers are encouraged to help spread the word by posting or reposting on social media.
- Community Slack channel.
- Google group message.
What to include:
- Thank all contributors
- A brief list of highlights in the release
- Link to the release blog post, release notes, and/or github release page