Skip to content

releasing.md

Latest commit

 

History

History
204 lines (144 loc) · 9.58 KB

releasing.md

File metadata and controls

204 lines (144 loc) · 9.58 KB
Raw

Introduction

Kgateway maintains releases through a GitHub-Actions + GoReleaser pipeline. This guide provides step-by-step instructions for creating a minor or a patch release.

Making any changes here? See if you should update the issue template at .github/ISSUE_TEMPLATE/RELEASE-REQUEST.md to keep its checklist in sync.

Background

Kgateway uses Semantic Versioning 2.0.0 to communicate the impact of every release (MAJOR.MINOR.PATCH). Artifacts (binaries, images, etc) are built by GoReleaser and published by a single Release workflow that can be run on demand via workflow_dispatch. Each release starts by creating a tracking issue (see issue #11406 as an example) so that every task is visible and auditable.

Prerequisites

After confirming that you have permissions to push to the Kgateway repo, set the environment variables that will be used throughout the release workflow:

export MINOR=0
export REMOTE=origin

If needed, clone the Kgateway repo:

git clone -o ${REMOTE} https://github.com/kgateway-dev/kgateway.git && cd kgateway

Minor Release

If the release branch does not exist, create one:

  • Create a new release branch from the main branch. The branch should be named v2.${MINOR}.x, for example, v2.0.x:

    git checkout -b v2.${MINOR}.x

  • Push the branch to the Kgateway repo:

    git push ${REMOTE} v2.${MINOR}.x

  • On main, bump ROLLING_MAIN_VERSION in the Makefile to the next minor's rolling tag via a PR (for example, after cutting v2.3.x, set it to v2.4.0-main), since main now tracks the next minor.

  • On main, bump gateway-api-version in the e2e test workflow to 1 version lower than what is used in go.mod (since this is an upgrade test)

  • Update the OSV security scan workflow branch allowlist in .github/workflows/osv-scanner.yaml to include the new release branch, and drop any branch that is no longer LTS. This workflow only scans an explicit set of branches, so each newly cut release branch must be added to both the scheduled scan matrix and the workflow_dispatch branch options. This allowlist is the single source of truth for which branches get scanned: tooling such as hack/osvtool and the cve-bump skill reads it rather than hardcoding the branch list, so keeping it current is all that is needed.

OSV scan and CVE triage

Before a release is cut, maintainers typically use the OSV scan results for the branch that will be released and clear any open source-dependency findings that would otherwise ship in the release artifact. The release workflow does not run this triage for you, so it belongs in the release checklist.

If you are using Codex, Claude Code, etc., the cve-bump skill (invoked with @cve-bump, Clear CVEs, etc. depending on the coding agent) wraps this workflow and uses hack/osvtool as the canonical entry point. For a manual run, start with the table view to see the current branch state:

./hack/osvtool --table --target source --state todo
./hack/osvtool --table --target image --state todo

Use --state todo to focus on critical and high findings, or --state open when you want the full severity picture. hack/osvtool reads the branch allowlist from .github/workflows/osv-scanner.yaml, so the branches it checks stay aligned with the scheduled scan workflow.

For a specific release branch, pull the raw alerts and decide how each one will be handled:

./hack/osvtool --raw --branch v2.3.x --target source --state todo
./hack/osvtool --raw --branch v2.3.x --target image --state todo

The usual outcomes are:

  • bump a dependency to the first fixed version when the advisory has a fix
  • update osv-scanner.toml only for confirmed false positives
  • leave the finding open and defer the release if there is no safe fix yet

Once the dependency bumps or ignore-list updates land (for images, as opposed to source code, note that this only happens upon release), manually rerun the osv-scanner GitHub Action or wait for its nightly run. Then rerun the skill or hack/osvtool for the release branch to confirm the branch is clean enough to publish. If you add or retire a release branch, update the allowlist in the OSV workflow before relying on the scan results for that branch.

Patch Release

A patch release is generated from an existing release branch, e.g. v2.2.x. After all the necessary backport pull requests have merged, you can proceed to the next section.

Publish the Release

Navigate to the Release workflow page.

Use the "Run workflow" drop-down in the right corner of the page to dispatch a release, then:

  • Select the branch to release from
    • Minor release: Select the main branch.
    • Patch release: Select the release branch, e.g. v2.2.x, that will be patched.
  • Enter the version for the release to create, e.g. v2.0.3. This will trigger the release process and result in a new GitHub release, v2.0.3 for example.
  • Click on the "validate release" option, which bootstraps an environment from the generated artifacts and runs the conformance suite against that deployed environment.
  • The workflow automatically generates release notes and publishes them with the GitHub release. If you need to preview them locally, see Generating Release Notes below.

The workflow generates release notes automatically (see Release Notes below). Once the workflow completes, review the release notes on the GitHub release and edit the description if anything was miscategorized.

Release Notes

The Release workflow runs make release-notes automatically and feeds the output to GoReleaser, so no manual step is required when cutting a release. Under the hood it invokes hack/generate-release-notes.sh, which:

  • Finds all PR numbers from commit messages between the previous tag and the new release
  • Fetches PR details via the GitHub API
  • Extracts content from release-note code blocks in PR descriptions
  • Categorizes entries by kind/ labels (breaking_change, feature, fix, deprecation, documentation, cleanup, install, bump)

To preview release notes locally — for example to sanity-check what an upcoming release will include — you can invoke the script directly:

GITHUB_TOKEN=<your_token> ./hack/generate-release-notes.sh -p v2.0.3 -c v2.1.0

This writes _output/RELEASE_NOTES.md. Run ./hack/generate-release-notes.sh --help for all options.

Verification

Verify the release has been published to the releases page and contains the expected assets.

Test

Follow the quickstart guide to ensure the steps work using the new release. Note: You need to manually replace the current version with the new version until the documentation is updated in the next step.

Update Documentation

The Kgateway documentation must be updated to reference the new version.

If needed, clone the Kgateway.dev repo:

git clone -o $REMOTE https://github.com/kgateway-dev/kgateway.dev.git && cd kgateway.dev

Latest Stable Versions

Bump the Kgateway version used by the docs. The following is an example of bumping from v2.0.3 to v2.0.4:

sed -i '' '1s/^2\.0\.3$/2.0.4/' assets/docs/versions/n-patch.md

Optionally, update the Gateway API version if Kgateway bumps this dependency. The following is an example of bumping Gateway API from v1.2.1 to v1.3.0:

GW_API_VERSION=$(cd ../kgateway && go list -m sigs.k8s.io/gateway-api | awk '{print $2}' | sed 's/^v//' && cd ../kgateway.dev)
sed -i '' "1s/.*/${GW_API_VERSION}/" assets/docs/versions/k8s-gw-version.md

Docs for previous Versions

The kgateway.dev repo does not use branches to support documentation for previous versions. It uses versioned folders and conrefs. See PR 447 as an example of updating v2.0.4 to v2.0.5 when v2.1.0 was the latest release.

Push Changes (All Versions)

Sign, commit, and push the changes.

FORK=<name_of_my_fork>
git commit -s -m "Bumps Kgateway release version"
git push $FORK

Submit a pull request to merge the changes from your fork to the kgateway.dev upstream.

Update Downstreams

The following projects consume Kgateway and should be updated or an issue created to reference the new release (not required for a patch release):

  • Create an issue and submit a pull request to llm-d-infra to bump the Kgateway version. See PR 146 as an example. Note The quickstart guide should be tested with the new Kgateway version before submitting the PR.