Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 93 additions & 8 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,36 +17,45 @@ permissions:
contents: read

jobs:
publish:
preflight:
if: github.event_name == 'push' && github.ref_type == 'tag'
runs-on: ubuntu-latest
permissions:
contents: write
packages: write
id-token: write
steps:
- name: Checkout
uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
with:
fetch-depth: 0

- name: Validate release ref
env:
GH_TOKEN: ${{ github.token }}
run: |
if [[ ! "${GITHUB_REF_NAME}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "release tag must be a stable semantic version such as 7.3.0" >&2
exit 1
fi
git fetch origin main
git merge-base --is-ancestor "${GITHUB_SHA}" origin/main
if release_response="$(gh api \
--method GET \
--include \
-H "Accept: application/vnd.github+json" \
-H "X-GitHub-Api-Version: 2022-11-28" \
"/repos/${GITHUB_REPOSITORY}/releases/tags/${GITHUB_REF_NAME}" \
2>&1)"; then
echo "release ${GITHUB_REF_NAME} already exists; refusing to publish it again" >&2
exit 1
elif ! grep -Eq '^HTTP/[0-9.]+ 404 ' <<<"$release_response"; then
echo "could not confirm that release ${GITHUB_REF_NAME} is unused" >&2
printf '%s\n' "$release_response" >&2
exit 1
fi

- name: Set up Go
uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
with:
go-version-file: go.mod

- name: Set up QEMU
uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3

- name: Cache Go modules
uses: actions/cache@caa296126883cff596d87d8935842f9db880ef25 # v5
with:
Expand All @@ -61,6 +70,54 @@ jobs:
git diff --exit-code -- go.mod go.sum
go test -race ./...

- name: Set up Python
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
with:
python-version: "3.13"
cache: pip
cache-dependency-path: requirements-docs.txt

- name: Validate documentation
run: |
python -m pip install --disable-pip-version-check -r requirements-docs.txt
mkdocs build --strict

- name: Validate GoReleaser configuration
uses: goreleaser/goreleaser-action@e435ccd777264be153ace6237001ef4d979d3a7a # v6
with:
version: v2.18.0
args: check
Comment thread
soulteary marked this conversation as resolved.
Resolved

publish:
if: github.event_name == 'push' && github.ref_type == 'tag'
needs: preflight
runs-on: ubuntu-latest
permissions:
contents: write
packages: write
id-token: write
steps:
- name: Checkout
uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
with:
fetch-depth: 0

- name: Set up Go
uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
with:
go-version-file: go.mod

- name: Set up QEMU
uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3

- name: Cache Go modules
uses: actions/cache@caa296126883cff596d87d8935842f9db880ef25 # v5
with:
path: ~/go/pkg/mod
key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
restore-keys: |
${{ runner.os }}-go-

- name: Login to Docker Hub
uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
with:
Expand Down Expand Up @@ -163,3 +220,31 @@ jobs:
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
"$image"
done

documentation:
if: github.event_name == 'push' && github.ref_type == 'tag'
needs: verify
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Checkout
uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
with:
fetch-depth: 0

- name: Set up Python
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
with:
python-version: "3.13"
cache: pip
cache-dependency-path: requirements-docs.txt

- name: Install documentation dependencies
run: python -m pip install --disable-pip-version-check -r requirements-docs.txt

- name: Configure Git identity
run: git config user.name github-actions && git config user.email github-actions@github.com

- name: Deploy release documentation
run: mike deploy --push --update-aliases "${GITHUB_REF_NAME}" latest && mike set-default --push latest
8 changes: 1 addition & 7 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,6 @@ on:
push:
branches:
- main
tags:
- "*.*.*"
paths:
- "docs/**"
- "example/**"
Expand Down Expand Up @@ -53,7 +51,7 @@ jobs:
run: mkdocs build --strict

deploy:
if: github.event_name == 'push'
if: github.event_name == 'push' && github.ref_type == 'branch'
needs: build
runs-on: ubuntu-latest
permissions:
Expand All @@ -80,7 +78,3 @@ jobs:
- name: Deploy development documentation
if: github.ref_type == 'branch'
run: mike deploy --push --update-aliases dev

- name: Deploy release documentation
if: github.ref_type == 'tag'
run: mike deploy --push --update-aliases "${{ github.ref_name }}" latest && mike set-default --push latest
68 changes: 32 additions & 36 deletions docs/en-US/Release-Guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,17 +15,18 @@ The 7.3.0 release includes the following changes after 7.2.0:
`trimSpace`, without exposing arbitrary filesystem reads;
- update examples, container tags, integrity commands, and migration downloads
to 7.3.0;
- make Release CI tag-only and split publishing, attestation, and verification
into retry-safe jobs.
- make Release CI tag-only and split validation, publishing, attestation,
verification, and release documentation into retry-safe jobs.

## Release invariants

- The release tag is exactly `MAJOR.MINOR.PATCH`, without a `v` prefix.
- The tagged commit is already on `main`, and all required checks passed on it.
- A version is tagged once. Never move, delete, or reuse a published tag.
- The Release workflow creates the GitHub Release and both registries' images.
- `publish` runs once. `attest`, `verify`, or Documentation may be retried
independently without running GoReleaser again.
- `preflight` performs all build checks before credentials or publishing are
used. `publish` runs once. `attest`, `verify`, or `documentation` may be
retried independently without running GoReleaser again.

## Prerequisites

Expand All @@ -36,60 +37,50 @@ Before preparing a tag:
and Benchmarks on the resulting `main` commit.
3. Confirm the Docker Hub credentials and GitHub repository/package permissions
are available to Actions.
4. Install Go according to `go.mod`, GitHub CLI, and GoReleaser v2.18.0
locally. For documentation, use either MkDocs or Python 3 with `venv`; when
`mkdocs` is not on `PATH`, the preflight script installs the pinned
`requirements-docs.txt` dependencies in a temporary virtual environment;
this fallback needs network access on its first run.
4. Install Git. Go, Python, MkDocs, GoReleaser, Syft, Cosign, and GitHub CLI are
provided by GitHub Actions and are not local release dependencies.

For 7.3.0, PR #177 and PR #178 must both be present in the selected `main`
commit.

## Exact publishing sequence

Run these commands from a clean clone. `release-preflight.sh` refuses to run
from a branch other than `main`, from a dirty or stale checkout, or when the tag
already exists.
From an up-to-date, clean `main` checkout, run one command:

```bash
git fetch origin main --tags
git switch main
git pull --ff-only origin main

RELEASE_VERSION=7.3.0
./scripts/release-preflight.sh "$RELEASE_VERSION"

RELEASE_COMMIT="$(git rev-parse HEAD)"
git tag -a "$RELEASE_VERSION" "$RELEASE_COMMIT" -m "Release $RELEASE_VERSION"
git push origin "refs/tags/$RELEASE_VERSION"
./scripts/release.sh 7.3.0
```

Push only the one tag shown above. Do not use `git push --tags`; it can publish
an unrelated local tag. Do not create a draft or empty GitHub Release before
the push, because GoReleaser owns that operation.
The command runs a fast Git-only preflight, displays the exact commit, and asks
you to type `7.3.0` before it creates and pushes one annotated tag. It refuses a
dirty checkout, a non-`main` branch, a checkout that differs from `origin/main`,
an invalid version, stale version references, or an existing local/remote tag.

Do not create a draft or empty GitHub Release first; GoReleaser owns that
operation. The script pushes only `refs/tags/7.3.0`, never all local tags.

The tag push starts these paths:

| Order | Workflow/job | Side effects | Retry rule |
|---|---|---|---|
| 1 | Release / `publish` | Tests, builds, GitHub Release, archives, SBOMs, signed container manifests | Run once only |
| 2 | Release / `attest` | Downloads published assets and creates GitHub provenance | Retry this job only |
| 3 | Release / `verify` | Verifies assets, Sigstore bundle, provenance, image UID, and image signatures | Retry this job only |
| Parallel | Documentation | Builds `7.3.0`, updates `latest`, and sets the documentation default | Retry independently |
| 1 | Release / `preflight` | Validates the tag and `main` ancestry, runs race tests, builds strict documentation, and checks GoReleaser configuration | No publishing side effects; safe to retry |
| 2 | Release / `publish` | Builds the GitHub Release, archives, SBOMs, and signed container manifests | Run once only |
| 3 | Release / `attest` | Downloads published assets and creates GitHub provenance | Retry this job only |
| 4 | Release / `verify` | Verifies assets, Sigstore bundle, provenance, image UID, and image signatures | Retry this job only |
| 5 | Release / `documentation` | Builds `7.3.0`, updates `latest`, and sets the documentation default | Retry this job only |

Wait for both workflows; a visible GitHub Release is not completion by itself.
Wait for the Release workflow; a visible GitHub Release is not completion by
itself.

```bash
RELEASE_VERSION=7.3.0
RELEASE_RUN_ID="$(gh run list --workflow build.yml --branch "$RELEASE_VERSION" --limit 1 --json databaseId --jq '.[0].databaseId')"
gh run watch "$RELEASE_RUN_ID" --exit-status

DOCS_RUN_ID="$(gh run list --workflow docs.yml --branch "$RELEASE_VERSION" --limit 1 --json databaseId --jq '.[0].databaseId')"
gh run watch "$DOCS_RUN_ID" --exit-status
```

## Post-release verification

After both workflows pass:
After the Release workflow passes:

```bash
gh release view "$RELEASE_VERSION" --repo soulteary/webhook \
Expand Down Expand Up @@ -121,14 +112,19 @@ Do not immediately press **Re-run all jobs**.

| Failure point | Safe action |
|---|---|
| Preparation PR or local preflight | Fix the branch and rerun checks; no release exists yet |
| Local preflight or confirmation | Fix/update the checkout and rerun the command; no release exists yet |
| CI `preflight` | Fix `main`, prepare a new version, and push a new tag; publishing did not start |
| `publish`, before **Run GoReleaser** starts | Re-run the failed `publish` job |
| `publish`, after **Run GoReleaser** starts | Do not rerun; inspect the GitHub Release and both registries for partial immutable artifacts |
| `attest` | Re-run failed jobs; `publish` remains completed |
| `verify` | Re-run failed jobs or the `verify` job only |
| Documentation | Re-run only the Documentation workflow |
| `documentation` | Re-run the failed `documentation` job only |

If GoReleaser started and any versioned release asset or image exists, do not
delete the tag and reuse the version. Preserve the evidence, fix the cause on
`main`, and publish the next patch version (for example, 7.3.1). This avoids
serving different bytes under the same immutable version.

If the local tag was created but the push failed, inspect it with
`git show 7.3.0`, then retry only `git push origin refs/tags/7.3.0`. Do not rerun
`release.sh`, because its duplicate-tag guard will stop.
Loading
Loading