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
52 changes: 46 additions & 6 deletions .github/workflows/release.yaml
Original file line number Diff line number Diff line change
@@ -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:
Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/ci-runs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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). |
Expand Down
58 changes: 58 additions & 0 deletions docs/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <upstream-remote> 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
Expand Down
38 changes: 28 additions & 10 deletions docs/release_branch_management.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <upstream-remote> 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
Expand All @@ -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 <upstream-remote> v0.21.0-beta.rc2`
Expand All @@ -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 <upstream-remote> v0.21.0-beta`
Expand All @@ -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

Expand All @@ -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 <upstream-remote> v0.21.1-beta.rc1`
Expand All @@ -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 <upstream-remote> v0.21.1-beta`
Expand Down
123 changes: 123 additions & 0 deletions scripts/release-workflow_test.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
#!/bin/bash

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: this guards the workflow contract (triggers, draft settings, prepare-step semantics), but nothing in CI runs it, so a future edit to release.yaml could silently break the contract it pins. Worth wiring into an existing shell/static-check job (it only needs bash, git, ruby — no Docker) in a follow-up.


# 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'
Loading