From 9a9a78b5a246877309386e88f2278a552cdb45e0 Mon Sep 17 00:00:00 2001 From: Daniel Norman Date: Tue, 3 Nov 2026 18:34:40 +0530 Subject: [PATCH] httpd: Build release archives in CI - Add build/ci to build the archives of an annotated release tag - Run it on the large_linux_arm Buildkite queue - Keep the archives as artifacts and show checksums in an annotation - Pass --load to docker, as a remote builder keeps the image in its cache - Add build/fetch to download the archives of the CI release job - Pick the job by its step key, so a failed test elsewhere does not hide it - Add build/compare to check a build against another - Document the CI build, the download and the comparison --- .buildkite/explorer-release.yml | 24 ++++++ .buildkite/pipeline.yml | 5 ++ explorer/.gitignore | 1 + explorer/RELEASE.md | 61 ++++++++++++---- explorer/crates/radicle-httpd/build/build | 9 ++- explorer/crates/radicle-httpd/build/ci | 45 ++++++++++++ explorer/crates/radicle-httpd/build/compare | 38 ++++++++++ explorer/crates/radicle-httpd/build/fetch | 81 +++++++++++++++++++++ 8 files changed, 246 insertions(+), 18 deletions(-) create mode 100644 .buildkite/explorer-release.yml create mode 100755 explorer/crates/radicle-httpd/build/ci create mode 100755 explorer/crates/radicle-httpd/build/compare create mode 100755 explorer/crates/radicle-httpd/build/fetch diff --git a/.buildkite/explorer-release.yml b/.buildkite/explorer-release.yml new file mode 100644 index 000000000..752efe742 --- /dev/null +++ b/.buildkite/explorer-release.yml @@ -0,0 +1,24 @@ +# Builds the radicle-httpd and radicle-search release archives from a +# `releases/httpd/` tag, and keeps them as Buildkite artifacts. A +# delegate downloads them with explorer/crates/radicle-httpd/build/fetch, then +# signs and uploads them, see explorer/RELEASE.md. +# +# garden-broker builds a tag push like a branch push: BUILDKITE_BRANCH is the +# tag name and BUILDKITE_COMMIT the tag object. build/ci checks that the build +# really is of an annotated tag with that name. +# +# The step runs on the agent rather than in a container, since the build itself +# runs in Docker. + +steps: + - label: "📦 httpd release build" + key: httpd-release-build + if: build.branch =~ /^releases\/httpd\// + # The build runs on linux/arm64, see explorer/crates/radicle-httpd/build/build. + agents: + queue: large_linux_arm + timeout_in_minutes: 90 + artifact_paths: + - "explorer/crates/radicle-httpd/build/artifacts/*" + commands: + - explorer/crates/radicle-httpd/build/ci diff --git a/.buildkite/pipeline.yml b/.buildkite/pipeline.yml index b9d5b5e10..0daa10401 100644 --- a/.buildkite/pipeline.yml +++ b/.buildkite/pipeline.yml @@ -13,6 +13,10 @@ # on the `explorer-check` key defined there, and Buildkite rejects a step whose # dependency is not yet part of the build. # +# A push of a `releases/httpd/` tag also starts a build, with the tag +# name as the branch. explorer-release.yml only runs then; the other suites run +# too, against the tagged commit. +# # Superseded builds are not cancelled. Buildkite has no YAML equivalent of the # GitHub Actions cancel-in-progress. @@ -23,3 +27,4 @@ steps: - buildkite-agent pipeline upload .buildkite/explorer-e2e.yml - buildkite-agent pipeline upload .buildkite/explorer-visual.yml - buildkite-agent pipeline upload .buildkite/explorer-rust.yml + - buildkite-agent pipeline upload .buildkite/explorer-release.yml diff --git a/explorer/.gitignore b/explorer/.gitignore index 26c37d2e2..63a5e4023 100644 --- a/explorer/.gitignore +++ b/explorer/.gitignore @@ -5,6 +5,7 @@ node_modules/ NOTES config/local* crates/radicle-httpd/build/artifacts +crates/radicle-httpd/build/artifacts-ci target target-docker diff --git a/explorer/RELEASE.md b/explorer/RELEASE.md index 13a88d60e..98e3d36f6 100644 --- a/explorer/RELEASE.md +++ b/explorer/RELEASE.md @@ -34,8 +34,11 @@ for which releases explorer supports. git config set gpg.format ssh git config set user.signingKey "$(rad self --ssh-key)" ``` -- Working `podman` setup (see [Podman Setup](#podman-setup) below) -- Required tools: `podman`, `rad`, `sha256sum` +- Working `podman` setup (see [Podman Setup](#podman-setup) below), or Docker +- Required tools: `podman` or `docker`, `rad`, `sha256sum`, `curl`, `jq`, + `ssh`, `scp`, `ssh-keygen` +- To download the CI build: a Buildkite API token with `read_builds` and + `read_artifacts` ## Prepare @@ -83,38 +86,65 @@ Normal patches add their highlights to `## Unreleased` in rad sync --announce ``` -## Build and upload +## Build -Do these steps after the tag is canonical. +Pushing the tag starts the `📦 httpd release build` step in Buildkite. It builds +the archives in Docker and keeps them as build artifacts. You can also build +them locally. Either way, one build is enough to publish, but a second build in +another environment is recommended: it shows that neither environment changed +the archives. -1. Check out the tag. The build reads the version from it with `git describe`: +1. Check out the tag. The scripts read the version from it with `git describe`: ```sh git switch --detach releases/httpd/ ``` -2. Run the reproducible build. A single run compiles the workspace and packages - **both** binaries, one archive per binary per target. It uses podman; set - `CONTAINER=docker` to use Docker: +2. Get the archives in one of these ways: + - Download the CI build. This needs a Buildkite API token with `read_builds` + and `read_artifacts`: - ```sh - crates/radicle-httpd/build/build - ``` + ```sh + export BUILDKITE_API_TOKEN= BUILDKITE_ORG= BUILDKITE_PIPELINE= + crates/radicle-httpd/build/fetch + ``` - This writes to `crates/radicle-httpd/build/artifacts/`: + - Build locally. A single run compiles the workspace and packages **both** + binaries, one archive per binary per target. It uses podman; set + `CONTAINER=docker` to use Docker: + + ```sh + crates/radicle-httpd/build/build + ``` + + Both write to `crates/radicle-httpd/build/artifacts/`: - `radicle-httpd--.tar.xz` (binary + man page) - `radicle-search--.tar.xz` (binary) each with a `.sha256` alongside. -3. Sign the archives with your Radicle key. This checks each archive against its +3. Recommended: compare a local build with the CI build. `build` overwrites + `artifacts/`, so build first, then fetch the CI build into another folder: + + ```sh + crates/radicle-httpd/build/build + crates/radicle-httpd/build/fetch -o crates/radicle-httpd/build/artifacts-ci + crates/radicle-httpd/build/compare crates/radicle-httpd/build/artifacts-ci + ``` + + Do not publish if the archives differ. `compare` takes any folder of archives + with their `.sha256`, so the build of another delegate works too. + +## Publish + +1. Sign the archives with your Radicle key. This checks each archive against its `.sha256` and writes a `.sig` alongside: ```sh crates/radicle-httpd/build/sign ``` -4. Upload. This publishes each binary into its own sibling folder on +2. Upload. This publishes each binary into its own sibling folder on [files.radicle.dev][files] and creates the version-less and `latest` symlinks for both: @@ -171,7 +201,8 @@ Do these steps after the tag is canonical. > - macOS binaries are unsigned and not notarized; download via CLI only > - The build always runs in a `linux/arm64` container, with the base images and > zig pinned, so that builds on different hosts give the same bytes. It runs -> natively on Apple silicon, and under emulation on amd64 hosts +> natively on Apple silicon and on the `large_linux_arm` Buildkite queue, and +> under emulation on amd64 hosts ## Podman Setup diff --git a/explorer/crates/radicle-httpd/build/build b/explorer/crates/radicle-httpd/build/build index 865c320b7..81e7f5e2f 100755 --- a/explorer/crates/radicle-httpd/build/build +++ b/explorer/crates/radicle-httpd/build/build @@ -24,6 +24,9 @@ main() { ;; docker) engine=docker + # A remote builder, as in Buildkite, only keeps the image in its cache + # unless asked to load it into Docker. + load=--load ;; *) echo "fatal: CONTAINER must be podman or docker, not '$CONTAINER'" >&2 @@ -62,9 +65,9 @@ main() { echo "Building image ($image) with $CONTAINER.." # Build on linux/arm64 on every host, so that builds on different hosts - # give the same bytes. Apple silicon runs it natively; amd64 hosts run it - # under emulation. - $engine build \ + # give the same bytes. Apple silicon and the Buildkite release queue run it + # natively; amd64 hosts run it under emulation. + $engine build $load \ --build-arg "RUST_VERSION=$rust_version" \ --build-arg SOURCE_DATE_EPOCH \ --build-arg TZ \ diff --git a/explorer/crates/radicle-httpd/build/ci b/explorer/crates/radicle-httpd/build/ci new file mode 100755 index 000000000..f6b56c146 --- /dev/null +++ b/explorer/crates/radicle-httpd/build/ci @@ -0,0 +1,45 @@ +#!/bin/sh +set -e + +# Builds the release archives in Buildkite, from a `releases/httpd/` +# tag. garden-broker passes the tag name as BUILDKITE_BRANCH and the tag object +# as BUILDKITE_COMMIT; Buildkite sets no BUILDKITE_TAG. + +tag="$BUILDKITE_BRANCH" + +case "$tag" in +releases/httpd/*) ;; +*) + echo "fatal: '$tag' is not a releases/httpd/ tag" >&2 + exit 1 + ;; +esac + +# Reject a branch that only has the name of a release tag. +if [ "$(git cat-file -t "$BUILDKITE_COMMIT")" != tag ]; then + echo "fatal: $BUILDKITE_COMMIT is not an annotated tag" >&2 + exit 1 +fi +name="$(git cat-file tag "$BUILDKITE_COMMIT" | sed -n 's/^tag //p')" +if [ "$name" != "$tag" ]; then + echo "fatal: tag object $BUILDKITE_COMMIT is named '$name', not '$tag'" >&2 + exit 1 +fi + +version="${tag#releases/httpd/}" +if ! echo "$version" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then + echo "fatal: '$version' is not a MAJOR.MINOR.PATCH version" >&2 + exit 1 +fi +export RADICLE_HTTPD_VERSION="$version" + +CONTAINER=docker "$(dirname "$0")/build" + +checksums="$("$(dirname "$0")/checksums" | sort -k2)" +buildkite-agent annotate --style info --context httpd-release <" >&2 + exit 1 +fi + +ours="$(dirname "$0")/artifacts" +theirs="$1" + +sums() { + if ! ls "$1"/*.tar.xz.sha256 >/dev/null 2>&1; then + echo "fatal: no checksums in $1" >&2 + exit 1 + fi + cat "$1"/*.tar.xz.sha256 | sort -k2 +} + +a="$(sums "$ours")" +b="$(sums "$theirs")" + +if [ "$a" = "$b" ]; then + echo "$a" + echo + echo "The archives in $ours and $theirs are the same." +else + echo "fatal: the archives differ ('<' $ours, '>' $theirs):" >&2 + printf '%s\n' "$a" >"${TMPDIR:-/tmp}/compare.$$.a" + printf '%s\n' "$b" >"${TMPDIR:-/tmp}/compare.$$.b" + diff "${TMPDIR:-/tmp}/compare.$$.a" "${TMPDIR:-/tmp}/compare.$$.b" >&2 || true + rm -f "${TMPDIR:-/tmp}/compare.$$.a" "${TMPDIR:-/tmp}/compare.$$.b" + exit 1 +fi diff --git a/explorer/crates/radicle-httpd/build/fetch b/explorer/crates/radicle-httpd/build/fetch new file mode 100755 index 000000000..a24b1f959 --- /dev/null +++ b/explorer/crates/radicle-httpd/build/fetch @@ -0,0 +1,81 @@ +#!/bin/sh +set -e + +# Downloads the release archives that Buildkite built from the tag +# `releases/httpd/`, see .buildkite/explorer-release.yml. + +usage() { + echo "Usage: $0 [-o ] " >&2 + exit 1 +} + +outdir="$(dirname "$0")/artifacts" +while getopts o: opt; do + case "$opt" in + o) outdir="$OPTARG" ;; + *) usage ;; + esac +done +shift $((OPTIND - 1)) +[ $# -eq 1 ] || usage +version="$1" + +for tool in curl jq sha256sum; do + if ! command -v "$tool" >/dev/null; then + echo "fatal: $tool is not installed" >&2 + exit 1 + fi +done + +for var in BUILDKITE_API_TOKEN BUILDKITE_ORG BUILDKITE_PIPELINE; do + if eval "[ -z \"\$$var\" ]"; then + echo "fatal: set $var; the token needs read_builds and read_artifacts" >&2 + exit 1 + fi +done + +api="https://api.buildkite.com/v2/organizations/$BUILDKITE_ORG/pipelines/$BUILDKITE_PIPELINE" + +get() { + curl -sSf -H "Authorization: Bearer $BUILDKITE_API_TOKEN" "$@" +} + +# The other suites run on the tag too, so look for a passed release job rather +# than a passed build: a flaky test elsewhere must not hide the archives. +match="$(get "$api/builds?branch=releases/httpd/$version" | jq -c ' + first(.[] | . as $build | .jobs[]? + | select(.step_key == "httpd-release-build" and .state == "passed") + | {number: $build.number, web_url: $build.web_url, job: .id}) // empty')" +if [ -z "$match" ]; then + echo "fatal: no passed httpd-release-build job for releases/httpd/$version" >&2 + exit 1 +fi +number="$(echo "$match" | jq -r .number)" +web_url="$(echo "$match" | jq -r .web_url)" +job="$(echo "$match" | jq -r .job)" + +echo "Downloading the archives of $web_url into $outdir.." +mkdir -p "$outdir" + +get "$api/builds/$number/jobs/$job/artifacts?per_page=100" | + jq -r '.[] | select(.path | startswith("explorer/crates/radicle-httpd/build/artifacts/")) | "\(.filename) \(.download_url)"' | + while read -r filename url; do + echo "$filename" + # The API redirects to storage that rejects the token, so follow the + # redirect without it. + location="$(get -o /dev/null -w '%{redirect_url}' "$url")" + curl -sSf -o "$outdir/$filename" "$location" + done + +for target in $(cat "$(dirname "$0")/TARGETS"); do + for bin in radicle-httpd radicle-search; do + filename="$bin-$version-$target.tar.xz" + if [ ! -f "$outdir/$filename" ]; then + echo "fatal: the build has no $filename" >&2 + exit 1 + fi + (cd "$outdir" && sha256sum --check --quiet "$filename.sha256") + done +done + +echo "Fetch successful."