From bf8cf4d394cb90b1c8e379fe9e687bcacf3582d2 Mon Sep 17 00:00:00 2001 From: yyforyongyu Date: Thu, 12 Nov 2026 20:56:01 +0800 Subject: [PATCH 1/2] ci: prepare release drafts before tagging Build release-version commits before maintainers publish their signed tags. Stage the successful build as a draft and cover preparation and skipping behavior with focused local workflow tests. --- .github/workflows/release.yaml | 52 +++++++++++-- scripts/release-workflow_test.sh | 123 +++++++++++++++++++++++++++++++ 2 files changed, 169 insertions(+), 6 deletions(-) create mode 100755 scripts/release-workflow_test.sh diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index f449b250d2f..0110d1bb453 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -1,9 +1,17 @@ name: Release build on: + # Build the merged version bump before a maintainer publishes its tag. push: - tags: - - 'v*' + branches: + - 'v0.*-branch' + paths: + - 'build/version.go' + workflow_dispatch: + +permissions: + # Upload the prepared assets to a draft without publishing the release. + contents: write defaults: run: @@ -36,25 +44,57 @@ jobs: go-version: '${{ env.GO_VERSION }}' cache: 'false' - - name: Set env - run: echo "RELEASE_VERSION=${GITHUB_REF#refs/*/}" >> $GITHUB_ENV - + - name: Prepare release version + id: version + run: | + # Reuse the binary's version so tag selection follows build.Version. + version=$(go run ./cmd/lnd --version | awk '{print $3}') + + # Development branches use patch 99 and have no release to prepare. + if [[ "$version" =~ ^[0-9]+\.[0-9]+\.99(-|$) ]]; then + echo "Skipping development version $version" + exit 0 + fi + + # A fetched tag means preparation is over; preserve its assets. + tag="v$version" + if git show-ref --verify --quiet "refs/tags/$tag"; then + echo "Skipping already tagged release $tag" + exit 0 + fi + + # Satisfy the normal build checks locally; the human signs later. + git -c tag.gpgSign=false tag "$tag" + echo "RELEASE_VERSION=$tag" >> "$GITHUB_ENV" + + # An unset version skips preparation; failures still stop later steps. - name: check release notes are ready + if: env.RELEASE_VERSION != '' run: scripts/check-release-notes-consistency.sh release - name: build release for all architectures - run: make release tag=${{ env.RELEASE_VERSION }} + if: env.RELEASE_VERSION != '' + run: make release "tag=$RELEASE_VERSION" + # Stage the tested commit and assets without creating a public Git tag. - name: Create Release + if: env.RELEASE_VERSION != '' uses: lightninglabs/gh-actions/action-gh-release@c7149b6a7818d1c39b36b69e727569897b6f2c5a env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: name: lnd ${{ env.RELEASE_VERSION }} + tag_name: ${{ env.RELEASE_VERSION }} + target_commitish: ${{ github.sha }} draft: true prerelease: false files: lnd-${{ env.RELEASE_VERSION }}/* body: | + Prepared from commit `${{ github.sha }}` by + [this workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}). + Wait for that run to succeed, then sign and push this exact commit's + tag before publishing this draft. + # Database Migrations TODO diff --git a/scripts/release-workflow_test.sh b/scripts/release-workflow_test.sh new file mode 100755 index 00000000000..0334b25a1f6 --- /dev/null +++ b/scripts/release-workflow_test.sh @@ -0,0 +1,123 @@ +#!/bin/bash + +# Exercise the release workflow's actual preparation step with local Git and +# fixture CLI output, so checks cannot create public tags or release assets. +set -euo pipefail + +DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +WORK="$(mktemp -d)" +trap 'rm -rf "$WORK"' EXIT + +# Arrange the workflow contract check by loading YAML with Ruby's standard +# library, which also lets the execution cases reuse the actual shell block. +ruby -ryaml - "$DIR/../.github/workflows/release.yaml" "$WORK/prepare.sh" <<'RUBY' +workflow = YAML.load_file(ARGV.fetch(0)) +# YAML 1.1 treats the Actions key "on" as true; accept either parser spelling. +events = workflow['on'] || workflow[true] +steps = workflow.fetch('jobs').fetch('main').fetch('steps') + +# Act by reading the public trigger and draft settings rather than matching +# implementation text inside the workflow's shell commands. +push = events.fetch('push') +release = steps.find { |step| step['name'] == 'Create Release' }.fetch('with') +version = steps.find { |step| step['id'] == 'version' } + +# Assert that version-file pushes prepare drafts at an exact commit and that +# pushing the human-signed tag cannot rerun this release build. +raise 'release branch filter' unless push['branches'] == ['v0.*-branch'] +raise 'version path filter' unless push['paths'] == ['build/version.go'] +raise 'unexpected tag trigger' if push.key?('tags') +raise 'manual retry unavailable' unless events.key?('workflow_dispatch') +raise 'release must stay draft' unless release['draft'] == true +unless release['tag_name'] == '${{ env.RELEASE_VERSION }}' + raise 'prospective tag missing' +end +unless release['target_commitish'] == '${{ github.sha }}' + raise 'tested commit missing' +end +File.write(ARGV.fetch(1), version.fetch('run')) +RUBY + +# Supply only the established lnd version output; Git operations remain real. +mkdir "$WORK/bin" +cat > "$WORK/bin/go" <<'SH' +#!/bin/bash +# Reject other calls so the fixture cannot hide a different build operation. +[[ "$*" == 'run ./cmd/lnd --version' ]] || exit 1 +printf 'lnd version %s commit=fixture\n' "$TEST_VERSION" +SH +chmod +x "$WORK/bin/go" + +# new_repo isolates each case with a committed HEAD and a local bare origin. +# Disable commit signing only in the fixture so tests never use a human key. +new_repo() { + REPO="$WORK/$1" + git init --quiet "$REPO" + git -C "$REPO" -c user.name=Fixture -c user.email=fixture@example.com \ + -c commit.gpgSign=false commit --quiet --allow-empty -m fixture + git init --quiet --bare "$REPO.git" + git -C "$REPO" remote add origin "$REPO.git" + : > "$REPO/env" +} + +# Arrange a new release and a signing preference that CI must override without +# accessing a private key. Its origin initially has no published tag. +new_repo release +git -C "$REPO" config tag.gpgSign true + +# Act by executing the workflow's preparation block in the fixture checkout, +# supplying the same environment-file interface used by the Actions runner. +( + cd "$REPO" + PATH="$WORK/bin:$PATH" TEST_VERSION=0.21.9-beta GITHUB_ENV="$REPO/env" \ + bash -eo pipefail "$WORK/prepare.sh" +) + +# Assert that CI exports the derived version and creates only an unsigned +# local tag at the tested commit; nothing reaches even the local bare origin. +grep -qx 'RELEASE_VERSION=v0.21.9-beta' "$REPO/env" +test "$(git -C "$REPO" rev-parse refs/tags/v0.21.9-beta)" = \ + "$(git -C "$REPO" rev-parse HEAD)" +test "$(git -C "$REPO" cat-file -t refs/tags/v0.21.9-beta)" = commit +if git --git-dir="$REPO.git" show-ref --verify --quiet \ + refs/tags/v0.21.9-beta; then + echo 'FAIL: preparation published a tag' >&2 + exit 1 +fi +echo 'ok: new release prepares only a local unsigned tag' + +# Arrange the documented development version in a fresh repository, so no +# release from another case can accidentally make the skip assertions pass. +new_repo development + +# Act through the same workflow block with the development CLI version. +( + cd "$REPO" + PATH="$WORK/bin:$PATH" TEST_VERSION=0.21.99-beta GITHUB_ENV="$REPO/env" \ + bash -eo pipefail "$WORK/prepare.sh" +) + +# Assert that no release version is exported and no local tag is created, +# leaving the later notes, build, and upload steps without a release to run. +test ! -s "$REPO/env" +test -z "$(git -C "$REPO" tag --list)" +echo 'ok: development version skips release preparation' + +# Arrange an already present release tag and remember its object so a retry +# must preserve it rather than replacing it with the current checkout. +new_repo tagged +git -C "$REPO" -c tag.gpgSign=false tag v0.21.9-beta +TAG_OBJECT="$(git -C "$REPO" rev-parse refs/tags/v0.21.9-beta)" + +# Act by requesting preparation of that same version through the workflow. +( + cd "$REPO" + PATH="$WORK/bin:$PATH" TEST_VERSION=0.21.9-beta GITHUB_ENV="$REPO/env" \ + bash -eo pipefail "$WORK/prepare.sh" +) + +# Assert that already tagged releases export no preparation version and keep +# the original object, preventing a retry from replacing release assets. +test ! -s "$REPO/env" +test "$(git -C "$REPO" rev-parse refs/tags/v0.21.9-beta)" = "$TAG_OBJECT" +echo 'ok: already tagged release skips preparation' From 9c415d20a1ff008b76994f3a10fb9b6e6ec9be53 Mon Sep 17 00:00:00 2001 From: yyforyongyu Date: Thu, 12 Nov 2026 20:57:35 +0800 Subject: [PATCH 2/2] docs: describe automatic release drafts Wait for the draft preparation run before signing and pushing the exact tested release commit. Route RC and patch releases through the same procedure and explain cleanup before retrying stale draft preparation. --- docs/ci-runs.md | 2 +- docs/release.md | 58 +++++++++++++++++++++++++++++++ docs/release_branch_management.md | 38 ++++++++++++++------ 3 files changed, 87 insertions(+), 11 deletions(-) diff --git a/docs/ci-runs.md b/docs/ci-runs.md index fa6f33c18ac..e5f5c9c8f38 100644 --- a/docs/ci-runs.md +++ b/docs/ci-runs.md @@ -289,7 +289,7 @@ seed corpus without replacing existing seeds. | `ci-hold.yml` | PR opened, labeled, or unlabeled (`pull_request_target`) | Adds `ci-hold` to new PRs and re-runs CI when it's removed. | | `cancel-pr-ci.yml` | PR closed (`pull_request_target`) | Cancels the PR's unfinished CI runs. | | `govulncheck.yml` | Relevant Go and dependency changes, merge queue, master, Mondays at 09:00 UTC, or dispatch | Builds release binaries and scans them. Findings are advisory while the existing baseline is remediated; scan errors fail the job. | -| `release.yaml` | `v*` tag push | Checks release notes and builds a draft release with reproducible binaries. | +| `release.yaml` | Push changing `build/version.go` on `v0.*-branch`, or manual dispatch | Checks release notes and builds a draft release with reproducible binaries. | | `verify-release.yaml` | Published release or dispatch | Verifies signatures and release binaries. | | `docker.yml` | `v*` tag push or daily at midnight UTC | Builds and pushes multi-architecture images, and checks signing-key expiry without gating the image build. | | `backport.yml` | Merged PR with `backport-v*` labels | Opens backport PRs. See the [backport guide](backport-workflow.md). | diff --git a/docs/release.md b/docs/release.md index 3c205f9ab6e..c100b105548 100644 --- a/docs/release.md +++ b/docs/release.md @@ -8,6 +8,64 @@ this wasn't _fully_ solved in `go1.13`, as the build system still includes the directory the binary is built into the binary itself. As a result, our scripts utilize a workaround needed until `go1.13.2`. +## Preparing a Release + +Release managers prepare artifacts before publishing the signed Git tag. When +a version-bump pull request merges into a `v0.*-branch` release branch, a push +that changes `build/version.go` automatically starts the release workflow. +Consolidate the release-note fragments before merging the bump. The workflow +checks those notes, builds all release architectures, and uploads the assets +to a **draft** release. It creates an unsigned tag only inside its runner so +the normal tag and binary-version checks run; it never pushes that tag. + +The release workflow must be present on the release branch. Development +versions with patch number `.99` and versions whose tags already exist are +skipped. Later pushes of signed tags do not rerun the build or replace assets. + +For each release candidate, final release, or patch release: + +1. Merge the version bump and wait for the automatic release workflow to + succeed. The draft records its exact build commit and links to that run. + Confirm that the linked run succeeded and all expected assets are present; + a draft left by a failed upload is not ready for signing or publication. +2. Update your release-branch checkout to that exact commit. Compare + `git rev-parse HEAD` with the draft's build commit. If the upstream branch + has advanced, follow the retry procedure below to prepare its updated head + instead of signing another commit against the old assets. The tagging + helper still requires HEAD to match the current upstream branch. +3. Create the signed tag with the existing helper, then push it to the + upstream remote printed by the helper. For example: + + ```shell + # Sign the tested branch head after the helper verifies upstream/version. + ./scripts/tag-release.sh v0.21.0-beta.rc1 --branch v0.21.x-branch + # Publish the signed tag to that same upstream; the release stays a draft. + git push v0.21.0-beta.rc1 + ``` + +4. Review and finalize the draft's release notes, manifest signatures, and + required timestamp artifacts, then publish the draft manually. Push the + signed tag **before** publishing the draft so GitHub uses that signed tag + instead of creating an unsigned one. Existing release verification and + Docker image requirements still apply. + +### Retrying Preparation + +Notes or build failures leave the real tag unpublished. Correct the problem +on the release branch and use the workflow's **Run workflow** action to prepare +the current branch head again. Manual dispatch also requires the workflow to +exist on the repository's default branch. It reads the version from the +selected commit, so no tag input or local preflight command is needed. + +Before any same-version retry, including preparation after the branch +advances, stop any active preparation runs for that version and delete its +stale draft releases and assets through the Releases UI. Do not delete or +replace a real tag or a published release. The upload action cannot reliably +reuse drafts across paginated release lists and replaces matching assets +individually, so a failed retry can leave partial or mixed assets. Start with +a fresh draft and wait for its linked run to succeed before trusting its +build commit and assets, signing the tag, or publishing the release. + ## Building a New Release ### macOS diff --git a/docs/release_branch_management.md b/docs/release_branch_management.md index cd24ebf11bf..9ce591b6e58 100644 --- a/docs/release_branch_management.md +++ b/docs/release_branch_management.md @@ -73,15 +73,21 @@ When ready to begin a major release: ### Release Candidate Cycle -Create the first release candidate by tagging the version bump commit with the -release tagging helper: +After the version bump merges, wait for automatic +[draft preparation](release.md#preparing-a-release) to succeed. Create the +first release candidate by tagging that exact tested commit with the release +tagging helper: ```bash +# Sign the tested branch head after the helper verifies upstream/version. ./scripts/tag-release.sh v0.21.0-beta.rc1 --branch v0.21.x-branch +# Publish the signed tag to that upstream; publish the prepared draft later. git push v0.21.0-beta.rc1 ``` -This triggers CI to build release artifacts and Docker images. +The release artifacts are already attached to the draft. Pushing the tag does +not rebuild them; complete the manual publication steps in the preparation +guide. Existing Docker image requirements still apply. As testing uncovers issues, develop fixes on master and tag them with the `v0.21.0` milestone. Once merged, CI automation backports them to @@ -91,7 +97,9 @@ conflicts occur, CI creates backport PRs for manual resolution. When ready for the next release candidate: 1. Create a pull request against the release branch to update `build/version.go` to `0.21.0-beta.rc2` -2. After merging the PR, check out the release branch and tag the merge commit: +2. After merging the PR, wait for + [draft preparation](release.md#preparing-a-release) to succeed, then check + out its exact release-branch commit and sign it: `./scripts/tag-release.sh v0.21.0-beta.rc2 --branch v0.21.x-branch` 3. Push the new tag to the upstream remote printed by the helper: `git push v0.21.0-beta.rc2` @@ -103,7 +111,9 @@ Repeat this cycle (rc3, rc4, etc.) until the release is stable. For the final release, remove the RC suffix: 1. Create a pull request against the release branch to update `build/version.go` to `0.21.0-beta` -2. After merging the PR, check out the release branch and tag the merge commit: +2. After merging the PR, wait for + [draft preparation](release.md#preparing-a-release) to succeed, then check + out its exact release-branch commit and sign it: `./scripts/tag-release.sh v0.21.0-beta --branch v0.21.x-branch` 3. Push the new tag to the upstream remote printed by the helper: `git push v0.21.0-beta` @@ -113,9 +123,13 @@ releases. ### Release Tagging Helper -Use `scripts/tag-release.sh` whenever creating release tags. The helper performs -the required safety checks before creating the signed tag, then prints the push -command to run as the final explicit maintainer step. +Complete [draft preparation](release.md#preparing-a-release) before using +`scripts/tag-release.sh` to create a release tag. The helper checks the current +upstream head and version before signing, then prints the push command for +that upstream remote. After pushing the signed tag, finalize and publish the +prepared draft manually. If the branch moves or a preparation run fails, use +the [retry procedure](release.md#retrying-preparation) before signing; do not +reuse assets built from another commit. ## Minor Release Process @@ -130,7 +144,9 @@ When a critical fix is needed for version 0.21.0: 2. Tag the PR with the `v0.21.1` milestone 3. CI automation backports to `v0.21.x-branch` 4. Create a pull request against the release branch to update `build/version.go` to `0.21.1-beta.rc1` -5. After merging the PR, check out the release branch and tag the merge commit: +5. After merging the PR, wait for + [draft preparation](release.md#preparing-a-release) to succeed, then check + out its exact release-branch commit and sign it: `./scripts/tag-release.sh v0.21.1-beta.rc1 --branch v0.21.x-branch` 6. Push the new tag to the upstream remote printed by the helper: `git push v0.21.1-beta.rc1` @@ -141,7 +157,9 @@ rc2, rc3, etc. For the final patch release: 1. Create a pull request against the release branch to update `build/version.go` to `0.21.1-beta` -2. After merging the PR, check out the release branch and tag the merge commit: +2. After merging the PR, wait for + [draft preparation](release.md#preparing-a-release) to succeed, then check + out its exact release-branch commit and sign it: `./scripts/tag-release.sh v0.21.1-beta --branch v0.21.x-branch` 3. Push the new tag to the upstream remote printed by the helper: `git push v0.21.1-beta`