diff --git a/README.md b/README.md index e58ea8326de..0fab95a6336 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,7 @@ Gloo Gateway is a feature-rich, fast, and flexible Kubernetes-native ingress con ## Contributing to Gloo Gateway The [devel](devel) folder should be the starting point for understanding the code, and contributing to the product. +For maintainer release instructions, see [RELEASE.md](RELEASE.md). ## Thanks **Gloo Gateway** would not be possible without the valuable open-source work of projects in the community. We would like to extend a special thank-you to [Envoy](https://www.envoyproxy.io). diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 00000000000..35c60775ea0 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,141 @@ +# Release Process + +This document is for maintainers who need to cut a release for `solo-io/gloo`. + +## Overview + +A release in this repo starts by tagging the target branch and creating the matching GitHub Release. That GitHub Release works together with the repo's release automation: Build Bot / Google Cloud Build publishes the release artifacts such as container images, the Helm chart, and `glooctl` binaries, while release-triggered GitHub Actions handle follow-up tasks such as copying docs and syncing APIs to `solo-apis`. After the automation completes, verify that the expected assets were published and follow up on any failed release jobs. + +Relevant implementation details: + +- [`cloudbuild.yaml`](cloudbuild.yaml) +- [`ci/cloudbuild/publish-artifacts.yaml`](ci/cloudbuild/publish-artifacts.yaml) +- [`Makefile`](Makefile) +- [`ci/upload_github_release_assets.go`](ci/upload_github_release_assets.go) +- [`.github/workflows/push-docs.yaml`](.github/workflows/push-docs.yaml) +- [`.github/workflows/push-solo-apis-branch.yaml`](.github/workflows/push-solo-apis-branch.yaml) + +## Release Checklist + +1. Start from the branch you intend to release. + + For example, use `main` for the current development line or an LTS branch such as `v1.21.x` for a patch release. + +2. Create and push an annotated tag. + + ```bash + git checkout + git pull --ff-only origin + git tag -a vX.Y.Z[-betaN|-rcN] -m "vX.Y.Z[-betaN|-rcN]" + git push origin vX.Y.Z[-betaN|-rcN] + ``` + +3. Create the GitHub Release from that tag. + + Use the GitHub Releases UI or `gh release create`. + Create it promptly after pushing the tag, and publish it rather than leaving it as a draft. + + ```bash + gh release create vX.Y.Z \ + --repo solo-io/gloo \ + --verify-tag \ + --title vX.Y.Z + ``` + + Add `--prerelease` for beta and release candidate builds. + +4. Monitor the release automation. + + There are three important pieces: + + - Build Bot / Cloud Build should run the `publish-artifacts` pipeline. This is the job that publishes images, the Helm chart, and `glooctl` release assets. + - `push-docs` runs on `release.created`. + - `Push API Changes to solo-apis` runs on `release.published`. + +5. Verify the GitHub release assets. + + Expected assets from `publish-glooctl`: + + - `glooctl-linux-amd64` + - `glooctl-linux-amd64.sha256` + - `glooctl-linux-arm64` + - `glooctl-linux-arm64.sha256` + - `glooctl-darwin-amd64` + - `glooctl-darwin-amd64.sha256` + - `glooctl-darwin-arm64` + - `glooctl-darwin-arm64.sha256` + - `glooctl-windows-amd64.exe` + - `glooctl-windows-amd64.exe.sha256` + + Quick check: + + ```bash + gh release view vX.Y.Z --repo solo-io/gloo --json assets,url + ``` + +6. Verify follow-up automation. + + - Confirm `push-docs` completed or capture the failure for follow-up. + - Confirm `Push API Changes to solo-apis` completed and review the resulting PR in `solo-apis` if one was opened. + +## Checking Cloud Build + +If the GitHub release exists but assets are still missing, inspect Build Bot / Cloud Build. + +The root Cloud Build config submits a child build named `publish-artifacts`, and the child build's `release-chart` step runs `publish-helm-chart` and `publish-glooctl`. + +If you have `gcloud` access, start with: + +```bash +gcloud builds list \ + --project=solo-public \ + --limit=20 \ + --sort-by=~createTime \ + --format='table(id,status,createTime,substitutions.TAG_NAME,substitutions.REPO_NAME,logUrl)' +``` + +Then inspect the matching build: + +```bash +gcloud builds describe BUILD_ID \ + --project=solo-public \ + --format='yaml(id,status,createTime,finishTime,substitutions,steps.id,logUrl)' +``` + +And view logs: + +```bash +gcloud builds log BUILD_ID --project=solo-public +``` + +Look for: + +- `substitutions.TAG_NAME: vX.Y.Z` +- the `publish-artifacts` child build +- the `release-chart` step +- `publish-glooctl` +- `upload_github_release_assets.go` + +If your team uses a different GCP project for Build Bot, substitute that project name accordingly. + +## Common Failure Modes + +### The release page exists but has no assets + +This usually means the GitHub Release object did not exist when `publish-glooctl` tried to upload assets, or the Cloud Build release job failed. + +Fix: + +1. Confirm the GitHub Release object exists for the tag. +2. Inspect the Build Bot / Cloud Build history for that tag. +3. Re-run or manually trigger the `publish-artifacts` release build if needed. + +### `push-docs` fails + +This workflow is separate from asset publishing. A `push-docs` failure does not explain missing GitHub release assets by itself. + +Check the workflow logs and fix the docs-copy issue independently. + +### `Push API Changes to solo-apis` succeeds but no change lands automatically + +That workflow pushes to `solo-apis`. Review and approve the resulting `solo-apis` PR if one is created. diff --git a/changelog/v1.22.2/release-docs.yaml b/changelog/v1.22.2/release-docs.yaml new file mode 100644 index 00000000000..d4f11139691 --- /dev/null +++ b/changelog/v1.22.2/release-docs.yaml @@ -0,0 +1,5 @@ +changelog: + - type: NON_USER_FACING + resolvesIssue: false + description: >- + Add maintainer release process documentation and link it from the README.