From 9cdbdeec60cd796501927797439da33ef1490ae2 Mon Sep 17 00:00:00 2001 From: Alex Kanitz Date: Mon, 2 Nov 2026 23:54:04 +0100 Subject: [PATCH 1/9] ci: add a calendar-version release workflow Replace the Deploy workflow, which published to GHCR for every push to main, with release and scan workflows modelled on cloud-registry-ui: versions are vYYYY.M.MICRO and the image goes to Docker Hub as elixircloud/landing-page. Production follows `latest`, which the release workflow moves to the highest release. CI now runs on pushes to dev only, as the release workflow needs a run for the push of the release commit to dev, and runs for pushes are no longer cancelled by later ones, which would have left a release commit without a run. Closes #167 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011FSoqMUX3EU35poH13xMgG --- .github/workflows/ci.yml | 23 +- .github/workflows/deploy.yml | 140 ------------ .github/workflows/release.yml | 413 ++++++++++++++++++++++++++++++++++ .github/workflows/scan.yml | 77 +++++++ .trivyignore.yaml | 15 ++ README.md | 190 +++++++++++++--- docker-compose.yaml | 11 +- 7 files changed, 678 insertions(+), 191 deletions(-) delete mode 100644 .github/workflows/deploy.yml create mode 100644 .github/workflows/release.yml create mode 100644 .github/workflows/scan.yml create mode 100644 .trivyignore.yaml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2c90f32..f633a6b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,7 +1,8 @@ -# Checks every pull request and push to dev and main: the pull request title, -# the build and the Docker image. The gate `passed` ("CI passed") is the only -# check that the rules for dev need to require. Pushes to main stay covered -# because the Deploy workflow publishes after CI for them. Runs also when a pull +# Checks every pull request and push to dev: the pull request title, the build +# and the Docker image. The gate `passed` ("CI passed") is the only check that +# the rules for dev need to require. The Release workflow requires a successful +# run for the push of the release commit to dev; main needs no runs, as it only +# moves forward to commits of dev that are released. Runs also when a pull # request is edited, so that the title check follows the title; all jobs run # then, as a run that skipped the build would report "CI passed" for the # commit. @@ -11,21 +12,25 @@ on: pull_request: types: [opened, synchronize, reopened, edited] push: - branches: [dev, main] + branches: [dev] permissions: contents: read -# Cancel superseded runs. Runs for edits that leave the title unchanged (e.g. -# of the description, also by bots) share a group of their own, so that they -# cancel each other but not the run for the pull request's commit +# Cancel superseded runs of a pull request. Runs for pushes get a group of their +# own and aren't cancelled, as the Release workflow needs the run of the release +# commit, also when other commits follow it quickly. Runs for edits that leave +# the title unchanged (e.g. of the description, also by bots) share a group of +# their own, so that they cancel each other but not the run for the pull +# request's commit concurrency: group: >- ci-${{ + github.event_name == 'push' && github.sha || github.event.action == 'edited' && !github.event.changes.title && format('{0}-edited', github.ref) || github.ref }} - cancel-in-progress: true + cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: # Pull request titles become the commit messages on `dev` (squash merges): diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml deleted file mode 100644 index 6f4a1a2..0000000 --- a/.github/workflows/deploy.yml +++ /dev/null @@ -1,140 +0,0 @@ -# Publishes the production image to GHCR once CI passed for a commit of main -# (the workflow runs when CI for a push to main completed), or when run by -# hand (`workflow_dispatch`, e.g., to roll back). The job `check` requires a -# successful run of the CI workflow for a push of the commit to main, so a -# commit whose CI failed or never ran is not deployed (see README). The host running https://elixir-on.cloud/ picks the image up -# automatically through Watchtower (see docker-compose.yaml). -name: Deploy - -on: - # Safe here: runs only commits of main for which the job `check` found a - # successful push run of CI; nothing of a pull request is checked out - workflow_run: # zizmor: ignore[dangerous-triggers] - workflows: [CI] - types: [completed] - branches: [main] - # Manual runs deploy the latest commit of main, or the commit `sha` of main - # (e.g., to roll back); only from main, whose workflow file has the check - workflow_dispatch: - inputs: - sha: - description: "Full SHA of the commit of main to deploy (default: the latest)" - required: false - type: string - -permissions: - contents: read - -env: - IMAGE: ghcr.io/${{ github.repository_owner }}/landing-page - -jobs: - # The commit to deploy and whether to deploy it - check: - name: Check CI - # Skipped, and so is `publish`, for runs of CI that were not successful - # pushes (the run of CI shows the failure) - if: >- - (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main') - || (github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push') - runs-on: ubuntu-latest - timeout-minutes: 5 - permissions: - contents: read - actions: read # read the CI runs of the commit - outputs: - sha: ${{ steps.check.outputs.sha }} - deploy: ${{ steps.check.outputs.deploy }} - steps: - # The checks here don't run the tests: require a successful run of the - # CI workflow for a push of the commit to main (runs for pull requests - # test merge commits, not the commit itself, and the API query finds no - # such run for commits that were never pushed to main). Re-runs that - # succeeded count. `workflow_run` events carry the commit that CI ran - # for; their `github.sha` is the latest commit of main, which may be - # a newer one - - name: Check that CI passed for the commit - id: check - env: - GH_TOKEN: ${{ github.token }} - REPOSITORY: ${{ github.repository }} - EVENT: ${{ github.event_name }} - SHA: ${{ github.event.workflow_run.head_sha || inputs.sha || github.sha }} - run: | - if [[ ! "${SHA}" =~ ^[0-9a-f]{40}$ ]]; then - echo "::error::'${SHA}' is not a full commit SHA" - exit 1 - fi - runs="$(gh api "repos/${REPOSITORY}/actions/workflows/ci.yml/runs?head_sha=${SHA}&event=push&branch=main&status=success&per_page=1" \ - --jq .total_count)" - if [[ ! "${runs}" =~ ^[0-9]+$ || "${runs}" -lt 1 ]]; then - echo "::error::No successful run of the CI workflow (ci.yml) for a push of ${SHA} to main; once CI passed for it, re-run this workflow" - exit 1 - fi - echo "sha=${SHA}" >> "${GITHUB_OUTPUT}" - # A run of CI that completes after the one of a newer commit must - # not replace the newer image (the host runs `latest`); the newer - # commit's own run deploys it. Manual runs may deploy older - # commits, e.g., to roll back - deploy=true - if [[ "${EVENT}" == "workflow_run" ]]; then - head="$(gh api "repos/${REPOSITORY}/branches/main" --jq .commit.sha)" - if [[ "${head}" != "${SHA}" ]]; then - echo "::notice::${SHA} is not the latest commit of main (${head}): not deployed" - deploy=false - fi - fi - echo "deploy=${deploy}" >> "${GITHUB_OUTPUT}" - - publish: - name: Publish image - needs: check - if: needs.check.outputs.deploy == 'true' - # One deploy at a time, never cancelled. On the job, not the workflow, so - # that runs that deploy nothing (failed CI) don't replace a pending deploy - concurrency: - group: deploy - cancel-in-progress: false - runs-on: ubuntu-latest - permissions: - contents: read - packages: write # push the image to GHCR - steps: - # Exactly the commit that CI passed for - - uses: actions/checkout@v7 - with: - ref: ${{ needs.check.outputs.sha }} - persist-credentials: false - - - uses: docker/setup-buildx-action@v4 - - - name: Log in to GHCR - uses: docker/login-action@v4 - with: - registry: ghcr.io - username: ${{ github.actor }} - password: ${{ secrets.GITHUB_TOKEN }} - - # "latest" is what the host runs; the commit SHA tag allows rollbacks. - - name: Image tags - id: meta - uses: docker/metadata-action@v6 - with: - images: ${{ env.IMAGE }} - tags: | - type=raw,value=latest - type=raw,value=sha-${{ needs.check.outputs.sha }} - - - name: Build and push - uses: docker/build-push-action@v7 - with: - context: . - push: true - tags: ${{ steps.meta.outputs.tags }} - labels: | - ${{ steps.meta.outputs.labels }} - org.opencontainers.image.revision=${{ needs.check.outputs.sha }} - # Public value, not a secret: it is visible in the page source. - build-args: GA_MEASUREMENT_ID=${{ vars.GA_MEASUREMENT_ID }} - cache-from: type=gha - cache-to: type=gha,mode=max diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..6f9d3a9 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,413 @@ +# Release when a version tag (`vYYYY.M.MICRO`, see "Releasing" in `README.md`) +# is pushed: check the tag, the version in `package.json` and that CI passed +# for its commit (`prepare`); build and push the Docker image (with SBOM and +# provenance attestations) by digest, untagged (`push`); scan exactly that +# digest for vulnerabilities in a job of its own, without the release +# credentials and signing identity (`scan`); and only then attest its build +# provenance, sign it (Sigstore keyless signing), tag it, and create the GitHub +# release with GitHub's generated notes (`publish`). `push` and `publish` each +# need approval in the `release` environment (required reviewer). Re-running +# all jobs builds, scans, signs and tags a new digest, but stops before building +# if the version tag exists (released images don't change); re-running failed +# jobs reuses the digest already pushed. Once `publish` has tagged the image, +# re-run only the failed jobs: a new attempt of all jobs stops at the existing +# tag and supersedes the attempt whose failed jobs could finish the release. +# Release commits are on `dev`, and `main` is moved forward to them before they +# are tagged. Adapted from cloud-registry-ui's release workflow; unlike there, +# versions are calendar versions without pre-releases, there is no +# `CITATION.cff`, and the image has one build argument. + +name: Release + +on: + push: + tags: ['v*'] + +permissions: + contents: read + +# Fully qualified (`docker.io/`), as the attestation needs it. The Docker Hub +# organization is the repository variable `DOCKERHUB_ORG` (by default +# `elixircloud`), so that forks can publish to their own organization +env: + IMAGE_NAME: docker.io/${{ vars.DOCKERHUB_ORG || 'elixircloud' }}/landing-page + +# One run per tag, so that a run waiting for approval is not cancelled by the +# run of another tag; `latest` is decided at the end of each run, from freshly +# fetched tags on `main` +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: false + +jobs: + prepare: + name: Prepare release + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: read + actions: read # read the CI runs of the release commit + outputs: + version: ${{ steps.version.outputs.version }} + sha: ${{ steps.version.outputs.sha }} + steps: + - name: Check out repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + # Full history and all tags, to check that the release commit is on + # `main` + fetch-depth: 0 + # "Releasing" in `README.md` runs the checks of this job that need no tag + # before tagging: keep them in sync. Guards against accidental releases, + # e.g., of unmerged commits; the `release` environment's protection rules + # (required reviewer) are what actually control publishing + - name: Check release tag and commit + id: version + env: + TAG: ${{ github.ref_name }} + GH_TOKEN: ${{ github.token }} + REPOSITORY: ${{ github.repository }} + run: | + # vYYYY.M.MICRO; month and MICRO without leading zeros + pattern='^v20[0-9]{2}\.([1-9]|1[0-2])\.(0|[1-9][0-9]*)$' + if [[ ! "${TAG}" =~ ${pattern} ]]; then + echo "::error::Tag '${TAG}' is not a release version (vYYYY.M.MICRO, e.g., v2026.11.0)" + exit 1 + fi + # Annotated, with a signature that GitHub verified + if [[ "$(git cat-file -t "refs/tags/${TAG}")" != "tag" ]]; then + echo "::error::Tag '${TAG}' is not annotated (git tag -s)" + exit 1 + fi + verified="$(gh api "repos/${REPOSITORY}/git/tags/$(git rev-parse "refs/tags/${TAG}")" \ + --jq .verification.verified)" + if [[ "${verified}" != "true" ]]; then + echo "::error::Tag '${TAG}' has no signature verified by GitHub (git tag -s)" + exit 1 + fi + if ! git merge-base --is-ancestor HEAD origin/main; then + echo "::error::Release commit is not on 'main' (move 'main' to it first: git push origin :main)" + exit 1 + fi + { + echo "version=${TAG#v}" + echo "sha=$(git rev-parse HEAD)" + } >> "${GITHUB_OUTPUT}" + # The version of the release is set in the release commit, so that the + # sources and the tag agree + - name: Check version in package.json + env: + VERSION: ${{ steps.version.outputs.version }} + run: | + package="$(jq -r .version package.json)" + if [[ "${package}" != "${VERSION}" ]]; then + echo "::error::Version in package.json ('${package}') doesn't match the tag ('${VERSION}')" + exit 1 + fi + # The checks above don't run the tests: require a successful run of the + # CI workflow for a push of the release commit to `dev` (before `main` + # moved to it); runs for pull requests test merge commits, not the commit + # itself. Re-runs that succeeded count + - name: Check that CI passed for the release commit + env: + GH_TOKEN: ${{ github.token }} + REPOSITORY: ${{ github.repository }} + SHA: ${{ steps.version.outputs.sha }} + run: | + runs="$(gh api "repos/${REPOSITORY}/actions/workflows/ci.yml/runs?head_sha=${SHA}&branch=dev&event=push&status=success&per_page=1" \ + --jq .total_count)" + if [[ ! "${runs}" =~ ^[0-9]+$ || "${runs}" -lt 1 ]]; then + echo "::error::No successful run of the CI workflow (ci.yml) for a push of ${SHA} to dev; once CI passed for it, re-run this workflow" + exit 1 + fi + + # Builds the image of the release commit once and pushes it by digest only + # (untagged, with SBOM and provenance attestations), for `scan` to scan and + # `publish` to sign and tag. Digests of runs that fail (or fail the scan) are + # never signed or tagged, but stay on Docker Hub, untagged (pullable by digest + # only) + push: + name: Push image + needs: prepare + runs-on: ubuntu-latest + timeout-minutes: 30 + # Docker Hub secrets (required reviewer) + environment: release + permissions: + contents: read + outputs: + digest: ${{ steps.push.outputs.digest }} + steps: + # The commit checked by `prepare` + - name: Check out repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + ref: ${{ needs.prepare.outputs.sha }} + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1 + # OCI labels with the version, commit and source; `tags` only sets the + # version label (the image is tagged by digest in `publish`, after the + # scan) + - name: Generate image labels + id: meta + uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0 + with: + images: ${{ env.IMAGE_NAME }} + flavor: latest=false + tags: type=raw,value=${{ needs.prepare.outputs.version }} + - name: Log in to Docker Hub + uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0 + with: + username: ${{ secrets.DOCKERHUB_LOGIN }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + # Released images don't change: if the version tag exists (e.g. when + # re-running all jobs of a release), stop before building + - name: Check that the version isn't released yet + env: + VERSION: ${{ needs.prepare.outputs.version }} + run: | + # The digest of the version tag, if it exists; errors other than "not + # found" stop the run, so that it never passes by mistake + status=0 + output="$(docker buildx imagetools inspect "${IMAGE_NAME}:${VERSION}" \ + --format '{{ json .Manifest }}' 2>&1)" || status=$? + current="" + if [[ "${status}" == 0 ]]; then + current="$(jq -r .digest <<< "${output}")" + elif ! grep -qiE 'not found|manifest unknown' <<< "${output}"; then + echo "::error::Cannot check whether ${IMAGE_NAME}:${VERSION} exists: ${output}" + exit 1 + fi + if [[ -n "${current}" ]]; then + echo "::error::${IMAGE_NAME}:${VERSION} exists already (${current}); release a new version instead" + exit 1 + fi + - name: Build and push image by digest + id: push + uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0 + with: + context: . + outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true + sbom: true + provenance: mode=max + labels: ${{ steps.meta.outputs.labels }} + # Public value, not a secret: it is visible in the page source. It + # goes into the build because the pages are rendered at build time + build-args: GA_MEASUREMENT_ID=${{ vars.GA_MEASUREMENT_ID }} + + # Scans exactly the pushed digest (`@`; public, so pulling it + # needs no login) with Trivy (shared action of elixir-cloud-aai/.github, + # pinned to the commit of a release; fails on fixable critical and high + # vulnerabilities, except those accepted in `.trivyignore.yaml`). Kept apart + # from `push` and `publish`, so that Trivy never runs next to the Docker Hub + # credentials, the `contents: write` token and the signing identity + scan: + name: Scan image + needs: [prepare, push] + runs-on: ubuntu-latest + timeout-minutes: 20 + permissions: + contents: read + steps: + # For `.trivyignore.yaml` + - name: Check out repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + ref: ${{ needs.prepare.outputs.sha }} + - name: Check image digest + env: + DIGEST: ${{ needs.push.outputs.digest }} + run: | + if [[ ! "${DIGEST}" =~ ^sha256:[0-9a-f]{64}$ ]]; then + echo "::error::Invalid image digest '${DIGEST}'" + exit 1 + fi + - name: Scan image + uses: elixir-cloud-aai/.github/actions/scan-image@743e82d290a53768454999e413756a924e383259 # v1.0.0 + with: + image: ${{ env.IMAGE_NAME }}@${{ needs.push.outputs.digest }} + category: release + upload: 'false' + + publish: + name: Publish image + needs: [prepare, push, scan] + runs-on: ubuntu-latest + timeout-minutes: 30 + environment: + name: release + url: ${{ github.server_url }}/${{ github.repository }}/releases/tag/${{ github.ref_name }} + permissions: + contents: write # create the GitHub release + id-token: write # Sigstore signing certificates + attestations: write # GitHub artifact attestations + env: + VERSION: ${{ needs.prepare.outputs.version }} + DIGEST: ${{ needs.push.outputs.digest }} + steps: + # The commit checked by `prepare`, with all tags, to find the previous + # release + - name: Check out repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + ref: ${{ needs.prepare.outputs.sha }} + fetch-depth: 0 + - name: Check image digest + run: | + if [[ ! "${DIGEST}" =~ ^sha256:[0-9a-f]{64}$ ]]; then + echo "::error::Invalid image digest '${DIGEST}'" + exit 1 + fi + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1 + - name: Log in to Docker Hub + uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0 + with: + username: ${{ secrets.DOCKERHUB_LOGIN }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + # Released images don't change: a version tag of another digest stops the + # run before this digest is attested and signed (the same digest, e.g. + # when re-running failed jobs, is fine) + - name: Check the version tag + run: | + # The digest of the version tag, if it exists; errors other than "not + # found" stop the run, so that it never passes by mistake + status=0 + output="$(docker buildx imagetools inspect "${IMAGE_NAME}:${VERSION}" \ + --format '{{ json .Manifest }}' 2>&1)" || status=$? + current="" + if [[ "${status}" == 0 ]]; then + current="$(jq -r .digest <<< "${output}")" + elif ! grep -qiE 'not found|manifest unknown' <<< "${output}"; then + echo "::error::Cannot check whether ${IMAGE_NAME}:${VERSION} exists: ${output}" + exit 1 + fi + if [[ -n "${current}" && "${current}" != "${DIGEST}" ]]; then + echo "::error::${IMAGE_NAME}:${VERSION} already points to ${current}; release a new version instead" + exit 1 + fi + # Of the scanned digest + - name: Attest build provenance + uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2 + with: + subject-name: ${{ env.IMAGE_NAME }} + subject-digest: ${{ env.DIGEST }} + push-to-registry: true + # No artifact metadata storage record (needs another permission) + create-storage-record: false + - name: Install cosign + uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2 + # The signature covers the digest, and so every tag of it + - name: Sign image + run: cosign sign --yes "${IMAGE_NAME}@${DIGEST}" + # Decided last, from freshly fetched tags (the repository is public, so no + # credentials are needed), so that neither a re-run of an older release + # nor a concurrent release moves `latest` back: the highest release among + # the tags on `main`, so that stray tags are ignored. `sort -V` orders + # calendar versions correctly (v2026.9.0 before v2026.11.0) + - name: Check whether this is the highest release + id: latest + env: + TAG: ${{ github.ref_name }} + REPOSITORY_URL: ${{ github.server_url }}/${{ github.repository }}.git + run: | + latest=false + git init --quiet repo + cd repo + git fetch --quiet --filter=blob:none --tags "${REPOSITORY_URL}" \ + "+refs/heads/main:refs/remotes/origin/main" + highest="$(git tag -l 'v*' --merged origin/main \ + | grep -E '^v20[0-9]{2}\.([1-9]|1[0-2])\.(0|[1-9][0-9]*)$' \ + | sort -V | tail -n 1 || true)" + if [[ "${highest}" == "${TAG}" ]]; then + latest=true + fi + echo "latest=${latest}" >> "${GITHUB_OUTPUT}" + # Tags `YYYY.M.MICRO` (and `latest`, which production follows, see + # `docker-compose.yaml`) point to the checked, scanned and signed digest: + # a single source is copied as is + - name: Tag image + env: + LATEST: ${{ steps.latest.outputs.latest }} + run: | + tags=("${IMAGE_NAME}:${VERSION}") + if [[ "${LATEST}" == "true" ]]; then + tags+=("${IMAGE_NAME}:latest") + fi + for tag in "${tags[@]}"; do + docker buildx imagetools create --tag "${tag}" "${IMAGE_NAME}@${DIGEST}" + actual="$(docker buildx imagetools inspect "${tag}" \ + --format '{{ json .Manifest }}' | jq -r .digest)" + if [[ "${actual}" != "${DIGEST}" ]]; then + echo "::error::${tag} points to ${actual}, expected ${DIGEST}" + exit 1 + fi + done + # A draft first, published last, so that immutable releases (a repository + # setting) can still get their notes; re-runs finish the draft of an + # earlier attempt and leave a published release as it is. GitHub's + # generated notes list the merged pull requests since the previous + # published release by version in the history of the release commit, on + # an earlier commit (tags without a release, e.g. of a failed run, don't + # count; without one, GitHub picks the start, e.g. all changes for the + # first release); the maintainers check them and add the curated sections + # afterwards (the notes of published releases stay editable) + - name: Create release + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + TAG: ${{ github.ref_name }} + LATEST: ${{ steps.latest.outputs.latest }} + run: | + # only "not found" means no release: other errors stop the run, so + # that a re-run never creates a second draft + status=0 + state="$(gh release view "${TAG}" --json isDraft --jq 'if .isDraft then "draft" else "published" end' 2>&1)" || status=$? + if [[ "${status}" != 0 ]]; then + if [[ "${state}" != *"release not found"* ]]; then + echo "::error::Cannot check whether release ${TAG} exists: ${state}" + exit 1 + fi + state=none + fi + if [[ ! "${state}" =~ ^(draft|published|none)$ ]]; then + echo "::error::Unexpected state of release ${TAG}: ${state}" + exit 1 + fi + if [[ "${state}" == "published" ]]; then + echo "Release ${TAG} is already published: left as it is" + exit 0 + fi + if [[ "${state}" == "none" ]]; then + published="$(gh release list --limit 1000 --exclude-drafts \ + --json tagName --jq '.[].tagName')" + previous="" + head="$(git rev-parse HEAD)" + while read -r tag; do + if [[ "$(git rev-parse "${tag}^{commit}")" == "${head}" ]]; then + continue + fi + if grep -qxF -- "${tag}" <<< "${published}"; then + previous="${tag}" + break + fi + done < <(git tag -l 'v*' --merged HEAD --sort=-v:refname) + args=(-f "tag_name=${TAG}") + if [[ -n "${previous}" ]]; then + args+=(-f "previous_tag_name=${previous}") + fi + notes="$(mktemp)" + gh api "repos/${GH_REPO}/releases/generate-notes" "${args[@]}" \ + --jq .body > "${notes}" + gh release create "${TAG}" \ + --draft \ + --verify-tag \ + --title "${TAG}" \ + --notes-file "${notes}" + fi + gh release edit "${TAG}" --title "${TAG}" \ + --latest="${LATEST}" --draft=false diff --git a/.github/workflows/scan.yml b/.github/workflows/scan.yml new file mode 100644 index 0000000..d2b88a6 --- /dev/null +++ b/.github/workflows/scan.yml @@ -0,0 +1,77 @@ +# Scan the image of the latest release weekly for known vulnerabilities with +# Trivy (shared action of elixir-cloud-aai/.github, pinned to the commit of a +# release), so that vulnerabilities found after a release are reported: the +# findings that have a fix are uploaded to code scanning, a full report +# (findings without a fix included) is uploaded as the workflow artifact +# `trivy-report-release-image` (JSON and table), and the workflow fails on +# critical and high vulnerabilities that have a fix (fixed by a new release). +# Accepted findings are listed in `.trivyignore.yaml`. The release scanned is +# the GitHub release marked as latest or, as long as there is none, the newest +# published one; its image is tagged with the version (`YYYY.M.MICRO`, without +# the `v` of the Git tag). Without a release, the run only says so. Scheduled +# runs use this workflow and `.trivyignore.yaml` as on the default branch, and +# file their findings under it. The image is public, so no Docker Hub secrets +# are needed; its organization is the repository variable `DOCKERHUB_ORG` (by +# default `elixircloud`, as in `release.yml`; forks set it to the organization +# they publish to). Adapted from cloud-registry-ui's scan workflow. + +name: Scan + +on: + schedule: + # Mondays, 05:37 UTC + - cron: '37 5 * * 1' + workflow_dispatch: + +permissions: + contents: read + +# One scan at a time, so that a run that picked an older release can't upload +# its findings after a newer run +concurrency: + group: ${{ github.workflow }} + cancel-in-progress: false + +jobs: + scan: + name: Scheduled scan + runs-on: ubuntu-latest + timeout-minutes: 20 + permissions: + contents: read + security-events: write # upload SARIF to code scanning + steps: + # For `.trivyignore.yaml` + - name: Check out repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + # Published releases (drafts left out) with version tags only, so that the + # image reference stays well-formed: the latest release if there is one, + # otherwise the newest (by creation date) + - name: Find the release to scan + id: release + env: + GH_TOKEN: ${{ github.token }} + IMAGE_NAME: docker.io/${{ vars.DOCKERHUB_ORG || 'elixircloud' }}/landing-page + run: | + # as in the `prepare` job of `release.yml` + pattern='^v20[0-9]{2}\.([1-9]|1[0-2])\.(0|[1-9][0-9]*)$' + releases="$(gh release list --repo "${GITHUB_REPOSITORY}" --exclude-drafts \ + --limit 1000 --json tagName,isLatest)" + tag="$(jq -r --arg pattern "${pattern}" \ + '[.[] | select(.tagName | test($pattern))] | (map(select(.isLatest)) + .)[0].tagName // ""' \ + <<< "${releases}")" + if [[ -z "${tag}" ]]; then + echo "::notice::No release yet, nothing to scan" + exit 0 + fi + echo "Scanning ${IMAGE_NAME}:${tag#v}" + echo "image=${IMAGE_NAME}:${tag#v}" >> "$GITHUB_OUTPUT" + - name: Scan image + if: ${{ steps.release.outputs.image != '' }} + uses: elixir-cloud-aai/.github/actions/scan-image@743e82d290a53768454999e413756a924e383259 # v1.0.0 + with: + image: ${{ steps.release.outputs.image }} + category: release-image + report: 'true' diff --git a/.trivyignore.yaml b/.trivyignore.yaml new file mode 100644 index 0000000..ee9faeb --- /dev/null +++ b/.trivyignore.yaml @@ -0,0 +1,15 @@ +# Vulnerabilities accepted in the Docker image (`Dockerfile`), which the scans +# (release and weekly scan workflows) ignore: each with the reason (`statement`) +# and an expiry date (`expired_at`), after which Trivy reports it again, so that +# the decision is reviewed. Limit entries to the affected package versions +# (`purls`), so that other packages with the same vulnerability are still +# reported. Example: +# +# vulnerabilities: +# - id: CVE-2026-12345 +# purls: ["pkg:npm/example@1.2.3"] +# statement: Only used at build time, not by the site +# expired_at: 2027-01-31 +# +# See https://trivy.dev/latest/docs/configuration/filtering/#trivyignoreyaml +vulnerabilities: [] diff --git a/README.md b/README.md index 8ecb404..93f3af3 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,8 @@ [![License][badge-license]][badge-url-license] [![Website][badge-website]][website] [![Build_status][badge-build-status]][badge-url-build-status] -[![Deploy][badge-deploy]][badge-url-deploy] +[![GitHub_tag][badge-github-tag]][badge-url-github-tag] +[![Docker_image][badge-docker]][badge-url-docker] The source of the website of [ELIXIR On-Cloud][website]: standards-based products and architecture patterns for federated analytics in biomedical @@ -68,50 +69,163 @@ services, products and Nodes, and that every referenced image exists. ## Deployment Pull requests go to `dev`, the default branch. `main` only moves forward to -versions that should go live: maintainers fast-forward it to a commit of `dev` -that passed CI, which deploys that commit: +commits of `dev` that are released, and release tags are on `main` (see +[Releasing](#releasing)). A release publishes the image +[`elixircloud/landing-page`][badge-url-docker] on Docker Hub, tagged with its +version (e.g. `2026.11.0`) and, if it is the highest release, `latest`. Moving +`main` or merging into `dev` publishes nothing. -```bash -git fetch origin -git push origin :main -``` - -Once CI has passed for a push to `main`, the [Deploy -workflow](.github/workflows/deploy.yml) publishes the image to the GitHub -Container Registry (`ghcr.io`, tagged `latest` and with the commit SHA). A -commit whose CI failed is not deployed. - -- Skipped commits: if a newer commit of `main` exists when CI for an older - one completes, the older one is skipped, so that `latest` never moves - back; the newer one is deployed once its CI passed. If that CI fails, fix - forward, or deploy the older commit by hand (below). -- Manual deploys (Actions, "Deploy", "Run workflow", on `main`): leave `sha` - empty to deploy the latest commit of `main`, or give the full SHA of a - commit of `main`, e.g., to roll back. They too require a successful CI run - for a push of that commit to `main` and otherwise fail, saying so (re-run - the workflow once CI has passed). - -On the host, -[`docker-compose.yaml`](docker-compose.yaml) runs the site together with -[Watchtower](https://containrrr.dev/watchtower/), which pulls new images every -5 minutes and restarts the site: +On the host, [`docker-compose.yaml`](docker-compose.yaml) runs the site together +with [Watchtower](https://containrrr.dev/watchtower/), which pulls new images +every 5 minutes and restarts the site, so a new release goes live within minutes +of its image being tagged `latest`: ```bash -git clone https://github.com/elixir-cloud-aai/landing-page.git +git clone --branch main https://github.com/elixir-cloud-aai/landing-page.git cd landing-page docker compose up -d ``` -The site listens on port 80 (change it in `docker-compose.yaml`). TLS is -expected to be terminated by a reverse proxy in front of it. +Watchtower updates the image only: when `docker-compose.yaml` changes, run +`git pull` and `docker compose up -d` on the host. The site listens on port 80 +(change it in `docker-compose.yaml`). TLS is expected to be terminated by a +reverse proxy in front of it. To build locally instead of pulling, run +`docker compose up -d --build`. Vercel builds preview deployments for pull requests and `dev`, which has a stable preview URL: `vercel.json` turns off deployments of `main`, as the -production site is served from the host above. - -To roll back, pin the `site` image to a previous `sha-` tag and run -`docker compose up -d`. To build locally instead of pulling, run -`docker compose up -d --build`. +production site is served from the host above. Previews are also why there are +no pre-releases. + +### Rolling back + +Releases can't be changed or moved, and `latest` never moves back by itself, so +a rollback pins the host to an earlier version, and the fix is a new release: + +1. Find the last good version under [Releases][badge-url-github-tag], e.g. + `v2026.11.0`. The image tag has no `v`. +2. On the host, in `docker-compose.yaml`, replace the `latest` of the `site` + image with that version, e.g. `elixircloud/landing-page:2026.11.0`, and run + `docker compose up -d`. Check the site, and that `docker compose ps` lists + the version. While pinned, the host doesn't pick up new releases. +3. Fix the problem and release a new version. +4. Once that version is out, undo the pin with + `git checkout docker-compose.yaml` and run `docker compose up -d`. + +## Releasing + +Versions are calendar versions, `vYYYY.M.MICRO`, as nothing depends on the +website's API: the year and month of the release, with the month not +zero-padded, and `MICRO` counting the releases of that month, from 0. For +example, the first release of November 2026 is `v2026.11.0` and the next one +`v2026.11.1`; the first one of December is `v2026.12.0`. Check the [existing +versions][badge-url-github-tag] for the next `MICRO`. A version that was tagged +is used up, also if its release failed. + +Releases are cut by the maintainers: + +1. Open a release-prep pull request into `dev` that sets the version in + `package.json` and `package-lock.json`, without the `v`, and merge it. The + version in `package.json` must match the tag, so each release needs this + change: + + ```bash + npm version 2026.11.0 --no-git-tag-version + ``` + +2. Wait until CI has passed for the push to `dev` of the commit that the merge + created on `dev` (``, not the head of the pull request): the release + workflow requires a successful CI run for a push of the tagged commit (runs + for pull requests test merge commits, not the commit itself). +3. CI doesn't scan the image yet + ([#166](https://github.com/elixir-cloud-aai/landing-page/issues/166)), but + the release workflow does, and a fixable critical or high vulnerability fails + the release after the tag. So check out the commit, build its image and scan + it with the same flags first: + + ```bash + docker build -t landing-page:release-check . + trivy image --ignorefile .trivyignore.yaml --severity CRITICAL,HIGH \ + --ignore-unfixed --exit-code 1 landing-page:release-check + ``` + + Fix what it finds (e.g., by bumping the Node.js image of the `Dockerfile` or + a dependency) or, with a reason and an expiry date, accept it in + `.trivyignore.yaml`. Either takes another pull request: release the commit + that its merge created, once CI has passed for it. +4. Run the release workflow's checks that need no tag, as it runs them (keep + these commands in sync with the job `prepare` of + [`release.yml`](.github/workflows/release.yml)), in Bash. Run them before + tagging: the release workflow checks the tagged commit, so a check that fails + after the tag is pushed (other than a CI run that hasn't finished yet) fails + again on re-runs, and the release then needs a new version. The commands + expect `origin` to be `elixir-cloud-aai/landing-page`. + + ```bash + version=YYYY.M.MICRO # e.g. 2026.11.0 + sha="" + git fetch origin && sha="$(git rev-parse --verify "^{commit}")" # the full SHA + ( + [[ -n "${sha}" ]] || { echo "Fetch failed, or the commit is unknown"; exit 1; } + git merge-base --is-ancestor "${sha}" origin/dev || { echo "${sha} is not on dev"; exit 1; } + pattern='^v20[0-9]{2}\.([1-9]|1[0-2])\.(0|[1-9][0-9]*)$' + [[ "v${version}" =~ ${pattern} ]] || { echo "Not a release version: v${version}"; exit 1; } + # The file of the commit, not of the working tree + [[ "$(git show "${sha}:package.json" | jq -r .version)" == "${version}" ]] || { echo "Wrong version in package.json"; exit 1; } + runs="$(gh api "repos/elixir-cloud-aai/landing-page/actions/workflows/ci.yml/runs?head_sha=${sha}&branch=dev&event=push&status=success&per_page=1" --jq .total_count)" + (( runs >= 1 )) || { echo "No successful CI run for the push of ${sha} to dev"; exit 1; } + git merge-base --is-ancestor origin/main "${sha}" || { echo "main can't be fast-forwarded to ${sha}"; exit 1; } + ) && echo "All checks passed" + ``` + + Only if all checks passed, move `main` to the commit and tag it with a + signed, annotated tag. Each command runs only if the one before it succeeded: a tag + on a commit that isn't on `main` would use up the version. + + ```bash + git push origin "${sha}:main" && # fails unless it is a fast-forward + git tag -s "v${version}" "${sha}" -m "v${version}" && + git push origin "v${version}" + ``` + +5. Approve the jobs of the [release + workflow](.github/workflows/release.yml) in the `release` environment, after + checking that the run is for the tag you pushed. It checks that GitHub + verified the tag's signature, that its commit is on `main`, the version and + the CI run; pushes, scans, signs and tags the image, and publishes the GitHub + release with the generated notes. If a job fails, use "Re-run failed jobs", + not "Re-run all jobs": once the image is tagged, a new attempt of all jobs + stops at the existing tag and can't finish the release. If `prepare` fails + because CI hasn't finished for the commit, re-run the workflow once it + passed. +6. Edit the release notes into the org's format: an intro paragraph; the + sections `## Breaking changes`, `## Features`, `## Security`, `## Fixes`, + `## Documentation` and `## Maintenance`, without the empty ones, each bullet + ending with its issue and pull request numbers; then the generated notes + under `## Commits` instead of `## What's Changed`, and last their + `**Full Changelog**` line. +7. Check the site within a few minutes: Watchtower deploys the new image. + +The repository needs, once: an environment `release` with a required reviewer, +deployments limited to `v*` tags, and access to the secrets `DOCKERHUB_LOGIN` +and `DOCKERHUB_TOKEN` (allowed to push `elixircloud/landing-page`; create that +repository on Docker Hub, public, before the first release); a ruleset that +lets only maintainers create `v*` tags and keeps them from being moved or +deleted; a ruleset for `main` that lets only maintainers update it and protects +it against non-fast-forward pushes; and immutable releases. Forks can publish +to their own Docker Hub organization by setting the repository variable +`DOCKERHUB_ORG`. The optional variable `GA_MEASUREMENT_ID` goes into the image +at build time (see the `Dockerfile`). + +Tags, published releases and released images can't be changed: if a release +fails after its tag was pushed and re-running its failed jobs doesn't help, +release the next version, with its own release-prep pull request. + +The workflow `Scan` ([`scan.yml`](.github/workflows/scan.yml)) scans the image +of the latest release every Monday, and can be run by hand. It uploads the +fixable findings to code scanning and a full report as a workflow artifact, and +fails on fixable critical and high vulnerabilities: release a new version with +the fix. ## Contributing @@ -126,10 +240,12 @@ Pull request titles become the commit messages on `dev`: they follow CI checks the title (job `PR title`) and rechecks it when you edit it. [badge-build-status]: -[badge-deploy]: +[badge-docker]: +[badge-github-tag]: [badge-license]: [badge-url-build-status]: -[badge-url-deploy]: +[badge-url-docker]: +[badge-url-github-tag]: [badge-url-license]: [badge-website]: [contributors]: diff --git a/docker-compose.yaml b/docker-compose.yaml index 2c7494c..3e8b7ba 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -1,16 +1,17 @@ # Production deployment for https://elixir-on.cloud/ # -# The Deploy workflow pushes a new image to GHCR once CI passed for a push to -# main. Watchtower checks GHCR every 5 minutes and restarts the site when the -# image changes, so the host never needs inbound access from GitHub. +# The Release workflow tags the image of the highest release `latest` on Docker +# Hub. Watchtower checks Docker Hub every 5 minutes and restarts the site when +# the image changes, so the host never needs inbound access from GitHub. # # docker compose up -d # start (or update this file and re-run) # docker compose logs -f site # follow the site's logs # -# To build locally instead of pulling: docker compose up -d --build +# To roll back, replace `latest` with a previous version (see "Deployment" in +# README.md). To build locally instead of pulling: docker compose up -d --build services: site: - image: ghcr.io/elixir-cloud-aai/landing-page:latest + image: elixircloud/landing-page:latest container_name: landing-page build: context: . From a42775ba6a690daca9f1e8ec42a321ca274dd8f3 Mon Sep 17 00:00:00 2001 From: Alex Kanitz Date: Tue, 3 Nov 2026 00:05:29 +0100 Subject: [PATCH 2/9] ci: guard `latest` and document the host move Reject tags for months in the future and leave them out when deciding `latest`: tags can't be removed, and such a tag would keep every later release from moving `latest`, which production follows. Warn when a release doesn't move `latest`. Document moving the host from GHCR to Docker Hub, which is only safe after the first release, as `latest` on Docker Hub is an image from 2024 until then. Pull before pinning in rollbacks, as `docker compose up` ignores a failed pull for a service that can be built. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011FSoqMUX3EU35poH13xMgG --- .github/workflows/release.yml | 29 +++++++++++----- README.md | 63 +++++++++++++++++++++++++---------- docker-compose.yaml | 5 +-- 3 files changed, 70 insertions(+), 27 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6f9d3a9..2dc2fc4 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -75,6 +75,13 @@ jobs: echo "::error::Tag '${TAG}' is not a release version (vYYYY.M.MICRO, e.g., v2026.11.0)" exit 1 fi + # A tag can't be removed, and a version in the future would stay the + # highest one, which keeps later releases from becoming `latest` + IFS=. read -r year month _ <<< "${TAG#v}" + if (( year * 100 + month > $(date -u +%Y%m) )); then + echo "::error::Tag '${TAG}' is for a month in the future" + exit 1 + fi # Annotated, with a signature that GitHub verified if [[ "$(git cat-file -t "refs/tags/${TAG}")" != "tag" ]]; then echo "::error::Tag '${TAG}' is not annotated (git tag -s)" @@ -307,8 +314,10 @@ jobs: # Decided last, from freshly fetched tags (the repository is public, so no # credentials are needed), so that neither a re-run of an older release # nor a concurrent release moves `latest` back: the highest release among - # the tags on `main`, so that stray tags are ignored. `sort -V` orders - # calendar versions correctly (v2026.9.0 before v2026.11.0) + # the tags on `main`, so that stray tags are ignored, leaving out months + # in the future, which `prepare` rejects. `sort -V` orders calendar + # versions correctly (v2026.9.0 before v2026.11.0). Production follows + # `latest`, so a release that doesn't move it says so - name: Check whether this is the highest release id: latest env: @@ -322,9 +331,12 @@ jobs: "+refs/heads/main:refs/remotes/origin/main" highest="$(git tag -l 'v*' --merged origin/main \ | grep -E '^v20[0-9]{2}\.([1-9]|1[0-2])\.(0|[1-9][0-9]*)$' \ + | awk -F '[v.]' -v now="$(date -u +%Y%m)" '$2 * 100 + $3 <= now' \ | sort -V | tail -n 1 || true)" if [[ "${highest}" == "${TAG}" ]]; then latest=true + else + echo "::warning::${highest} is higher than ${TAG}: 'latest' stays as it is, and production doesn't update" fi echo "latest=${latest}" >> "${GITHUB_OUTPUT}" # Tags `YYYY.M.MICRO` (and `latest`, which production follows, see @@ -350,12 +362,13 @@ jobs: # A draft first, published last, so that immutable releases (a repository # setting) can still get their notes; re-runs finish the draft of an # earlier attempt and leave a published release as it is. GitHub's - # generated notes list the merged pull requests since the previous - # published release by version in the history of the release commit, on - # an earlier commit (tags without a release, e.g. of a failed run, don't - # count; without one, GitHub picks the start, e.g. all changes for the - # first release); the maintainers check them and add the curated sections - # afterwards (the notes of published releases stay editable) + # generated notes list the pull requests merged since the previous + # release: the highest version tag in the history of the release commit, + # on another commit, that has a published release. Tags without one (e.g. + # of a failed run) don't count; without any, GitHub picks the start, e.g. + # all changes for the first release. The maintainers check the notes and + # add the curated sections afterwards (the notes of published releases + # stay editable) - name: Create release env: GH_TOKEN: ${{ github.token }} diff --git a/README.md b/README.md index 93f3af3..09a0a92 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,8 @@ version (e.g. `2026.11.0`) and, if it is the highest release, `latest`. Moving On the host, [`docker-compose.yaml`](docker-compose.yaml) runs the site together with [Watchtower](https://containrrr.dev/watchtower/), which pulls new images every 5 minutes and restarts the site, so a new release goes live within minutes -of its image being tagged `latest`: +of its image being tagged `latest` (once the host has moved to Docker Hub, see +[below](#moving-the-host-to-docker-hub)): ```bash git clone --branch main https://github.com/elixir-cloud-aai/landing-page.git @@ -94,8 +95,27 @@ reverse proxy in front of it. To build locally instead of pulling, run Vercel builds preview deployments for pull requests and `dev`, which has a stable preview URL: `vercel.json` turns off deployments of `main`, as the -production site is served from the host above. Previews are also why there are -no pre-releases. +production site is served from the host above. + +### Moving the host to Docker Hub + +Images used to be published to the GitHub Container Registry (`ghcr.io`), and a +host set up then keeps following `ghcr.io/elixir-cloud-aai/landing-page:latest`, +to which nothing is published any more. It has to move by hand, once, and only +after the first release has finished: until then, `latest` on Docker Hub is an +old image from 2024, and a host that pulls it would serve that old site. + +1. Check that the first release has been published, and that `latest` on + [Docker Hub][badge-url-docker] was pushed with it. +2. On the host, check out `main`, pull it, and run + `docker pull elixircloud/landing-page:latest` and `docker compose up -d`. + Check the site. +3. Keep the images on `ghcr.io` until a release from Docker Hub has proven good. + +Until the host has moved, roll back by pinning the `site` image to a previous +tag `ghcr.io/elixir-cloud-aai/landing-page:sha-`, and running +`docker compose up -d`. Those images are also the only fallback if the first +release from Docker Hub turns out bad. ### Rolling back @@ -104,13 +124,16 @@ a rollback pins the host to an earlier version, and the fix is a new release: 1. Find the last good version under [Releases][badge-url-github-tag], e.g. `v2026.11.0`. The image tag has no `v`. -2. On the host, in `docker-compose.yaml`, replace the `latest` of the `site` - image with that version, e.g. `elixircloud/landing-page:2026.11.0`, and run - `docker compose up -d`. Check the site, and that `docker compose ps` lists - the version. While pinned, the host doesn't pick up new releases. -3. Fix the problem and release a new version. -4. Once that version is out, undo the pin with - `git checkout docker-compose.yaml` and run `docker compose up -d`. +2. On the host, pull that version, so that a wrong version fails here: + `docker pull elixircloud/landing-page:2026.11.0`. (`docker compose up` would + ignore the failure and build the image from the checkout instead.) +3. In `docker-compose.yaml`, replace the `latest` of the `site` image with that + version, e.g. `elixircloud/landing-page:2026.11.0`, and run + `docker compose up -d`. Check the site. While pinned, the host doesn't pick + up new releases. +4. Fix the problem and release a new version. +5. Once that version is out, set the image back to `latest` and run + `docker compose up -d`. ## Releasing @@ -120,7 +143,8 @@ zero-padded, and `MICRO` counting the releases of that month, from 0. For example, the first release of November 2026 is `v2026.11.0` and the next one `v2026.11.1`; the first one of December is `v2026.12.0`. Check the [existing versions][badge-url-github-tag] for the next `MICRO`. A version that was tagged -is used up, also if its release failed. +is used up, also if its release failed. Months in the future (UTC) are rejected. +There are no pre-releases, as the Vercel previews cover that. Releases are cut by the maintainers: @@ -164,12 +188,15 @@ Releases are cut by the maintainers: ```bash version=YYYY.M.MICRO # e.g. 2026.11.0 sha="" - git fetch origin && sha="$(git rev-parse --verify "^{commit}")" # the full SHA + # Replace with the commit from step 2; this gets the full SHA + git fetch origin && sha="$(git rev-parse --verify "^{commit}")" ( [[ -n "${sha}" ]] || { echo "Fetch failed, or the commit is unknown"; exit 1; } git merge-base --is-ancestor "${sha}" origin/dev || { echo "${sha} is not on dev"; exit 1; } pattern='^v20[0-9]{2}\.([1-9]|1[0-2])\.(0|[1-9][0-9]*)$' [[ "v${version}" =~ ${pattern} ]] || { echo "Not a release version: v${version}"; exit 1; } + IFS=. read -r year month _ <<< "${version}" + (( year * 100 + month <= $(date -u +%Y%m) )) || { echo "Version is in the future: v${version}"; exit 1; } # The file of the commit, not of the working tree [[ "$(git show "${sha}:package.json" | jq -r .version)" == "${version}" ]] || { echo "Wrong version in package.json"; exit 1; } runs="$(gh api "repos/elixir-cloud-aai/landing-page/actions/workflows/ci.yml/runs?head_sha=${sha}&branch=dev&event=push&status=success&per_page=1" --jq .total_count)" @@ -179,8 +206,8 @@ Releases are cut by the maintainers: ``` Only if all checks passed, move `main` to the commit and tag it with a - signed, annotated tag. Each command runs only if the one before it succeeded: a tag - on a commit that isn't on `main` would use up the version. + signed, annotated tag. Each command runs only if the one before it succeeded: + a tag on a commit that isn't on `main` would use up the version. ```bash git push origin "${sha}:main" && # fails unless it is a fast-forward @@ -204,12 +231,14 @@ Releases are cut by the maintainers: ending with its issue and pull request numbers; then the generated notes under `## Commits` instead of `## What's Changed`, and last their `**Full Changelog**` line. -7. Check the site within a few minutes: Watchtower deploys the new image. +7. Check the site within a few minutes: Watchtower deploys the new image, if + this is the highest release (the workflow warns otherwise). After the first + release, [move the host to Docker Hub](#moving-the-host-to-docker-hub). The repository needs, once: an environment `release` with a required reviewer, deployments limited to `v*` tags, and access to the secrets `DOCKERHUB_LOGIN` -and `DOCKERHUB_TOKEN` (allowed to push `elixircloud/landing-page`; create that -repository on Docker Hub, public, before the first release); a ruleset that +and `DOCKERHUB_TOKEN` (allowed to push `elixircloud/landing-page`, a public +repository on Docker Hub); a ruleset that lets only maintainers create `v*` tags and keeps them from being moved or deleted; a ruleset for `main` that lets only maintainers update it and protects it against non-fast-forward pushes; and immutable releases. Forks can publish diff --git a/docker-compose.yaml b/docker-compose.yaml index 3e8b7ba..3554be7 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -7,8 +7,9 @@ # docker compose up -d # start (or update this file and re-run) # docker compose logs -f site # follow the site's logs # -# To roll back, replace `latest` with a previous version (see "Deployment" in -# README.md). To build locally instead of pulling: docker compose up -d --build +# To move a host from GHCR (only after the first release) or to roll back, see +# "Deployment" in README.md. To build locally instead of pulling: +# docker compose up -d --build services: site: image: elixircloud/landing-page:latest From 3698bb55ea57b51f165038d8f7e04f5617c330c9 Mon Sep 17 00:00:00 2001 From: Alex Kanitz Date: Tue, 3 Nov 2026 00:13:01 +0100 Subject: [PATCH 3/9] docs: harden the release and rollback steps Stop the tag commands if `sha` is empty, as pushing ":main" would delete the branch. Pull before un-pinning, so that the host doesn't restart from its old local `latest`. Use the guarded steps for GHCR rollbacks too, and restore the compose file before moving the host. Pick MICRO from the tags rather than the releases, as a failed release uses up its version. Word the warning about `latest` for an empty result. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011FSoqMUX3EU35poH13xMgG --- .github/workflows/release.yml | 2 +- README.md | 38 ++++++++++++++++++++--------------- 2 files changed, 23 insertions(+), 17 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 2dc2fc4..afebac2 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -336,7 +336,7 @@ jobs: if [[ "${highest}" == "${TAG}" ]]; then latest=true else - echo "::warning::${highest} is higher than ${TAG}: 'latest' stays as it is, and production doesn't update" + echo "::warning::Highest release on main is ${highest:-none}, not ${TAG}: 'latest' stays as it is, and production doesn't update; release a version above it" fi echo "latest=${latest}" >> "${GITHUB_OUTPUT}" # Tags `YYYY.M.MICRO` (and `latest`, which production follows, see diff --git a/README.md b/README.md index 09a0a92..2f29bfa 100644 --- a/README.md +++ b/README.md @@ -107,15 +107,17 @@ old image from 2024, and a host that pulls it would serve that old site. 1. Check that the first release has been published, and that `latest` on [Docker Hub][badge-url-docker] was pushed with it. -2. On the host, check out `main`, pull it, and run +2. On the host, undo local changes to the file with + `git checkout docker-compose.yaml`, and note them first if you need to apply + them again (e.g., another port). Check out `main`, pull it, and run `docker pull elixircloud/landing-page:latest` and `docker compose up -d`. Check the site. 3. Keep the images on `ghcr.io` until a release from Docker Hub has proven good. -Until the host has moved, roll back by pinning the `site` image to a previous -tag `ghcr.io/elixir-cloud-aai/landing-page:sha-`, and running -`docker compose up -d`. Those images are also the only fallback if the first -release from Docker Hub turns out bad. +Until the host has moved, roll back with the steps below, using the image +`ghcr.io/elixir-cloud-aai/landing-page:sha-`. Those +images are also the only fallback if the first release from Docker Hub turns +out bad. ### Rolling back @@ -132,8 +134,10 @@ a rollback pins the host to an earlier version, and the fix is a new release: `docker compose up -d`. Check the site. While pinned, the host doesn't pick up new releases. 4. Fix the problem and release a new version. -5. Once that version is out, set the image back to `latest` and run - `docker compose up -d`. +5. Once that version is out, set the image back to + `elixircloud/landing-page:latest`, and run + `docker pull elixircloud/landing-page:latest` and `docker compose up -d`, so + that the host doesn't restart from its old local `latest`. ## Releasing @@ -141,9 +145,10 @@ Versions are calendar versions, `vYYYY.M.MICRO`, as nothing depends on the website's API: the year and month of the release, with the month not zero-padded, and `MICRO` counting the releases of that month, from 0. For example, the first release of November 2026 is `v2026.11.0` and the next one -`v2026.11.1`; the first one of December is `v2026.12.0`. Check the [existing -versions][badge-url-github-tag] for the next `MICRO`. A version that was tagged -is used up, also if its release failed. Months in the future (UTC) are rejected. +`v2026.11.1`; the first one of December is `v2026.12.0`. For the next `MICRO`, +check the tags, not the releases (`git fetch --tags origin`, then +`git tag -l 'v2026.11.*'`): a version that was tagged is used up, also if its +release failed. Months in the future (UTC) are rejected. There are no pre-releases, as the Vercel previews cover that. Releases are cut by the maintainers: @@ -210,8 +215,9 @@ Releases are cut by the maintainers: a tag on a commit that isn't on `main` would use up the version. ```bash - git push origin "${sha}:main" && # fails unless it is a fast-forward - git tag -s "v${version}" "${sha}" -m "v${version}" && + # ${sha:?} stops if it is empty: pushing ":main" would delete the branch + git push origin "${sha:?}:main" && # fails unless it is a fast-forward + git tag -s "v${version:?}" "${sha}" -m "v${version}" && git push origin "v${version}" ``` @@ -238,10 +244,10 @@ Releases are cut by the maintainers: The repository needs, once: an environment `release` with a required reviewer, deployments limited to `v*` tags, and access to the secrets `DOCKERHUB_LOGIN` and `DOCKERHUB_TOKEN` (allowed to push `elixircloud/landing-page`, a public -repository on Docker Hub); a ruleset that -lets only maintainers create `v*` tags and keeps them from being moved or -deleted; a ruleset for `main` that lets only maintainers update it and protects -it against non-fast-forward pushes; and immutable releases. Forks can publish +repository on Docker Hub); a ruleset that lets only maintainers create `v*` tags +and keeps them from being moved or deleted; a ruleset for `main` that lets only +maintainers update it and protects it against deletion and non-fast-forward +pushes; and immutable releases. Forks can publish to their own Docker Hub organization by setting the repository variable `DOCKERHUB_ORG`. The optional variable `GA_MEASUREMENT_ID` goes into the image at build time (see the `Dockerfile`). From 7e56a2947ae7a615d77f25df97148ed1cf601d84 Mon Sep 17 00:00:00 2001 From: Alex Kanitz Date: Tue, 3 Nov 2026 00:14:15 +0100 Subject: [PATCH 4/9] docs: rewrap the release paragraphs Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011FSoqMUX3EU35poH13xMgG --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 2f29bfa..0184f58 100644 --- a/README.md +++ b/README.md @@ -148,8 +148,8 @@ example, the first release of November 2026 is `v2026.11.0` and the next one `v2026.11.1`; the first one of December is `v2026.12.0`. For the next `MICRO`, check the tags, not the releases (`git fetch --tags origin`, then `git tag -l 'v2026.11.*'`): a version that was tagged is used up, also if its -release failed. Months in the future (UTC) are rejected. -There are no pre-releases, as the Vercel previews cover that. +release failed. Months in the future (UTC) are rejected. There are no +pre-releases, as the Vercel previews cover that. Releases are cut by the maintainers: @@ -247,10 +247,10 @@ and `DOCKERHUB_TOKEN` (allowed to push `elixircloud/landing-page`, a public repository on Docker Hub); a ruleset that lets only maintainers create `v*` tags and keeps them from being moved or deleted; a ruleset for `main` that lets only maintainers update it and protects it against deletion and non-fast-forward -pushes; and immutable releases. Forks can publish -to their own Docker Hub organization by setting the repository variable -`DOCKERHUB_ORG`. The optional variable `GA_MEASUREMENT_ID` goes into the image -at build time (see the `Dockerfile`). +pushes; and immutable releases. Forks can publish to their own Docker Hub +organization by setting the repository variable `DOCKERHUB_ORG`. The optional +variable `GA_MEASUREMENT_ID` goes into the image at build time (see the +`Dockerfile`). Tags, published releases and released images can't be changed: if a release fails after its tag was pushed and re-running its failed jobs doesn't help, From 23b8a112234d6282c44f8b66b59b2dd9d06c1054 Mon Sep 17 00:00:00 2001 From: Alex Kanitz Date: Tue, 3 Nov 2026 01:53:21 +0100 Subject: [PATCH 5/9] docs: describe the release after the CI scan CI now scans the image in `Scan build`, so the release steps no longer need a local scan before tagging. Say that CI runs for pushes to dev only, make the header of ci.yml one description after the merge, and record that the GHCR images are removed by hand. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011FSoqMUX3EU35poH13xMgG --- .github/workflows/ci.yml | 18 +++++++++--------- .trivyignore.yaml | 6 +++--- README.md | 37 +++++++++++++++---------------------- 3 files changed, 27 insertions(+), 34 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ddb6418..30c21ac 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,12 +1,12 @@ -# Checks every pull request and push to dev: the pull request title, the build -# and the Docker image. The gate `passed` ("CI passed") is the only check that -# the rules for dev need to require. The Release workflow requires a successful -# run for the push of the release commit to dev; main needs no runs, as it only -# moves forward to commits of dev that are released. Runs also when a pull -# request is edited, so that the title check follows the title; all jobs run -# then, as a run that skipped the build would report "CI passed" for the -# commit. CI also runs the tests (with coverage, reported to Codecov), audits -# the production dependencies and scans the image for known vulnerabilities. +# Checks every pull request and push to dev: the pull request title, the tests +# (with coverage, reported to Codecov), the build, an audit of the production +# dependencies, and the Docker image and its scan for known vulnerabilities. The +# gate `passed` ("CI passed") is the only check that the rules for dev need to +# require. The Release workflow requires a successful run for the push of the +# release commit to dev; main needs no runs, as it only moves forward to commits +# of dev that are released. Runs also when a pull request is edited, so that the +# title check follows the title; all jobs run then, as a run that skipped the +# build would report "CI passed" for the commit. name: CI on: diff --git a/.trivyignore.yaml b/.trivyignore.yaml index ee9faeb..4085eb7 100644 --- a/.trivyignore.yaml +++ b/.trivyignore.yaml @@ -1,7 +1,7 @@ # Vulnerabilities accepted in the Docker image (`Dockerfile`), which the scans -# (release and weekly scan workflows) ignore: each with the reason (`statement`) -# and an expiry date (`expired_at`), after which Trivy reports it again, so that -# the decision is reviewed. Limit entries to the affected package versions +# (CI, release and weekly scan workflows) ignore: each with the reason +# (`statement`) and an expiry date (`expired_at`), after which Trivy reports it +# again, so that the decision is reviewed. Limit entries to the affected package versions # (`purls`), so that other packages with the same vulnerability are still # reported. Example: # diff --git a/README.md b/README.md index fd059d3..ce00e86 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ services, products and Nodes, and that every referenced image exists. ### Checks -[CI](.github/workflows/ci.yml) runs these jobs on every pull request and push: +[CI](.github/workflows/ci.yml) runs these jobs on every pull request and push to `dev`: - `PR title`: the title follows Conventional Commits and has at most 50 characters (see [Contributing](#contributing)). @@ -150,7 +150,8 @@ old image from 2024, and a host that pulls it would serve that old site. them again (e.g., another port). Check out `main`, pull it, and run `docker pull elixircloud/landing-page:latest` and `docker compose up -d`. Check the site. -3. Keep the images on `ghcr.io` until a release from Docker Hub has proven good. +3. Keep the images on `ghcr.io` until a release from Docker Hub has proven good, + then remove them by hand. Until the host has moved, roll back with the steps below, using the image `ghcr.io/elixir-cloud-aai/landing-page:sha-`. Those @@ -203,24 +204,16 @@ Releases are cut by the maintainers: 2. Wait until CI has passed for the push to `dev` of the commit that the merge created on `dev` (``, not the head of the pull request): the release workflow requires a successful CI run for a push of the tagged commit (runs - for pull requests test merge commits, not the commit itself). -3. CI doesn't scan the image yet - ([#166](https://github.com/elixir-cloud-aai/landing-page/issues/166)), but - the release workflow does, and a fixable critical or high vulnerability fails - the release after the tag. So check out the commit, build its image and scan - it with the same flags first: - - ```bash - docker build -t landing-page:release-check . - trivy image --ignorefile .trivyignore.yaml --severity CRITICAL,HIGH \ - --ignore-unfixed --exit-code 1 landing-page:release-check - ``` - - Fix what it finds (e.g., by bumping the Node.js image of the `Dockerfile` or - a dependency) or, with a reason and an expiry date, accept it in + for pull requests test merge commits, not the commit itself). CI also scans + the image with the flags of the release scan (job `Scan build`), so that a + fixable critical or high vulnerability fails CI before the tag rather than + the release. Fix it (e.g., by bumping the Node.js image of the `Dockerfile` + or a dependency) or, with a reason and an expiry date, accept it in `.trivyignore.yaml`. Either takes another pull request: release the commit - that its merge created, once CI has passed for it. -4. Run the release workflow's checks that need no tag, as it runs them (keep + that its merge created, once CI has passed for it. Vulnerabilities published + between the CI run and the release can still fail the release scan: tag soon + after CI has passed. +3. Run the release workflow's checks that need no tag, as it runs them (keep these commands in sync with the job `prepare` of [`release.yml`](.github/workflows/release.yml)), in Bash. Run them before tagging: the release workflow checks the tagged commit, so a check that fails @@ -259,7 +252,7 @@ Releases are cut by the maintainers: git push origin "v${version}" ``` -5. Approve the jobs of the [release +4. Approve the jobs of the [release workflow](.github/workflows/release.yml) in the `release` environment, after checking that the run is for the tag you pushed. It checks that GitHub verified the tag's signature, that its commit is on `main`, the version and @@ -269,13 +262,13 @@ Releases are cut by the maintainers: stops at the existing tag and can't finish the release. If `prepare` fails because CI hasn't finished for the commit, re-run the workflow once it passed. -6. Edit the release notes into the org's format: an intro paragraph; the +5. Edit the release notes into the org's format: an intro paragraph; the sections `## Breaking changes`, `## Features`, `## Security`, `## Fixes`, `## Documentation` and `## Maintenance`, without the empty ones, each bullet ending with its issue and pull request numbers; then the generated notes under `## Commits` instead of `## What's Changed`, and last their `**Full Changelog**` line. -7. Check the site within a few minutes: Watchtower deploys the new image, if +6. Check the site within a few minutes: Watchtower deploys the new image, if this is the highest release (the workflow warns otherwise). After the first release, [move the host to Docker Hub](#moving-the-host-to-docker-hub). From c787d2338f1202c296ce5a9c1cf5ed35401490a8 Mon Sep 17 00:00:00 2001 From: Alex Kanitz Date: Fri, 20 Nov 2026 19:43:08 +0100 Subject: [PATCH 6/9] ci: align the release workflow with the model Follow cloud-registry-ui's current release workflow: - Curated notes in docs/releases/.md, checked in `prepare` (publish-release with check-only) and published by a new job `publish` ("Publish release") with the shared action, instead of generated notes to edit by hand. - The image job is now `release-image` ("Release image") and needs only `contents: read`; jobs are named "Push release image" and "Scan release image", unique across the workflows. - CI's Lint job checks the notes with the same checker, and requires the notes of the version in package.json once it is a release version. - Pins of login-action, cosign-installer and scan-image as in the model and CI. README: release-prep step with the notes, the pre-tag block checks the notes and existing releases, and the publish step no longer edits the notes after the release. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 31 +++++- .github/workflows/release.yml | 186 ++++++++++++++++------------------ .github/workflows/scan.yml | 2 +- README.md | 67 ++++++++---- 4 files changed, 164 insertions(+), 122 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c25ab62..5e116ab 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -63,7 +63,8 @@ jobs: # Lints all JavaScript and TypeScript sources with ESLint (Next.js's # recommended flat config with typescript-eslint, plus the project's rules - # in `eslint.config.js`); fails on errors and warnings + # in `eslint.config.js`); fails on errors and warnings. Also checks the + # curated release notes in `docs/releases/` lint: name: Lint runs-on: ubuntu-latest @@ -86,6 +87,34 @@ jobs: - name: Lint run: npm run lint + # The release workflow publishes the curated notes as they are and checks + # their format only after the tag is pushed: check them here, with the + # checker of the action that `release.yml` pins (keep the commit in + # sync), so that a release-prep pull request fails instead. Once + # `package.json` has a release version (`YYYY.M.MICRO`), its notes must + # exist, so that a pull request that sets a new version brings them + # (`0.1.0`, from before the first release, has none) + - name: Check release notes + env: + CHECKER: https://raw.githubusercontent.com/elixir-cloud-aai/.github/31f22fccc1f3c597ed7c1d1f75b2f85522155348/actions/publish-release/publish.py + run: | + version="$(jq -r .version package.json)" + if [[ "v${version}" =~ ^v20[0-9]{2}\.([1-9]|1[0-2])\.(0|[1-9][0-9]*)$ \ + && ! -f "docs/releases/${version}.md" ]]; then + echo "::error file=package.json::No release notes docs/releases/${version}.md for version ${version}" + exit 1 + fi + shopt -s nullglob + notes=(docs/releases/*.md) + if (( ${#notes[@]} == 0 )); then + echo "No release notes yet" + exit 0 + fi + curl -fsSL "${CHECKER}" -o "${RUNNER_TEMP}/publish.py" + for file in "${notes[@]}"; do + python3 -I "${RUNNER_TEMP}/publish.py" check "${file}" + done + test: name: Test runs-on: ubuntu-latest diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index afebac2..d9ad86a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,21 +1,28 @@ # Release when a version tag (`vYYYY.M.MICRO`, see "Releasing" in `README.md`) -# is pushed: check the tag, the version in `package.json` and that CI passed -# for its commit (`prepare`); build and push the Docker image (with SBOM and -# provenance attestations) by digest, untagged (`push`); scan exactly that -# digest for vulnerabilities in a job of its own, without the release -# credentials and signing identity (`scan`); and only then attest its build -# provenance, sign it (Sigstore keyless signing), tag it, and create the GitHub -# release with GitHub's generated notes (`publish`). `push` and `publish` each -# need approval in the `release` environment (required reviewer). Re-running -# all jobs builds, scans, signs and tags a new digest, but stops before building -# if the version tag exists (released images don't change); re-running failed -# jobs reuses the digest already pushed. Once `publish` has tagged the image, -# re-run only the failed jobs: a new attempt of all jobs stops at the existing -# tag and supersedes the attempt whose failed jobs could finish the release. -# Release commits are on `dev`, and `main` is moved forward to them before they -# are tagged. Adapted from cloud-registry-ui's release workflow; unlike there, -# versions are calendar versions without pre-releases, there is no -# `CITATION.cff`, and the image has one build argument. +# is pushed: check the tag, the version in `package.json`, the curated release +# notes (`docs/releases/.md`) and that CI passed for its commit +# (`prepare`); build and push the Docker image (with SBOM and provenance +# attestations) by digest, untagged (`push`); scan exactly that digest for +# vulnerabilities in a job of its own, without the release credentials and +# signing identity (`scan`); and only then attest its build provenance, sign it +# (Sigstore keyless signing) and tag it (`release-image`). Last, create the +# GitHub release with the curated notes followed by GitHub's generated notes +# (`publish`, shared action `elixir-cloud-aai/.github/actions/publish-release`). +# `push` and `release-image` each need approval in the `release` environment +# (required reviewer). Re-running all jobs builds, scans, signs and tags a new +# digest, but stops before building if the version tag exists (released images +# don't change); re-running failed jobs reuses the digest already pushed. Once +# `release-image` has tagged the image, re-run only the failed jobs: a new +# attempt of all jobs stops at the existing tag and supersedes the attempt whose +# failed jobs could finish the release. `prepare` fails if a published release +# of the tag exists already (it can't see drafts); `publish` fails on a draft of +# the tag, and on a published release unless an earlier attempt created it, so +# re-run only the failed jobs. Release commits are on `dev`, and `main` is moved +# forward to them before they are tagged. Adapted from cloud-registry-ui's +# release workflow; unlike there, versions are calendar versions without +# pre-releases (none is below 1.0.0, so no release is a GitHub pre-release), +# months in the future are rejected, there is no `CITATION.cff`, and the image +# has one build argument. name: Release @@ -112,6 +119,17 @@ jobs: echo "::error::Version in package.json ('${package}') doesn't match the tag ('${VERSION}')" exit 1 fi + # The GitHub release (`publish`) starts with the curated notes of the + # tagged commit, so they must exist and be in the organization's format + # before anything is published; also checks that the tag points to the + # release commit and that no published release of it exists. Keep the + # pin in sync with `publish` and with the checker in `ci.yml` + - name: Check release notes + uses: elixir-cloud-aai/.github/actions/publish-release@31f22fccc1f3c597ed7c1d1f75b2f85522155348 # v1.1.0 + with: + notes: docs/releases/${{ steps.version.outputs.version }}.md + commit: ${{ steps.version.outputs.sha }} + check-only: 'true' # The checks above don't run the tests: require a successful run of the # CI workflow for a push of the release commit to `dev` (before `main` # moved to it); runs for pull requests test merge commits, not the commit @@ -131,11 +149,11 @@ jobs: # Builds the image of the release commit once and pushes it by digest only # (untagged, with SBOM and provenance attestations), for `scan` to scan and - # `publish` to sign and tag. Digests of runs that fail (or fail the scan) are + # `release-image` to sign and tag. Digests of runs that fail (or fail the scan) are # never signed or tagged, but stay on Docker Hub, untagged (pullable by digest # only) push: - name: Push image + name: Push release image needs: prepare runs-on: ubuntu-latest timeout-minutes: 30 @@ -155,7 +173,7 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1 # OCI labels with the version, commit and source; `tags` only sets the - # version label (the image is tagged by digest in `publish`, after the + # version label (the image is tagged by digest in `release-image`, after the # scan) - name: Generate image labels id: meta @@ -165,7 +183,7 @@ jobs: flavor: latest=false tags: type=raw,value=${{ needs.prepare.outputs.version }} - name: Log in to Docker Hub - uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0 + uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550 # v4.8.0 with: username: ${{ secrets.DOCKERHUB_LOGIN }} password: ${{ secrets.DOCKERHUB_TOKEN }} @@ -208,10 +226,11 @@ jobs: # needs no login) with Trivy (shared action of elixir-cloud-aai/.github, # pinned to the commit of a release; fails on fixable critical and high # vulnerabilities, except those accepted in `.trivyignore.yaml`). Kept apart - # from `push` and `publish`, so that Trivy never runs next to the Docker Hub - # credentials, the `contents: write` token and the signing identity + # from `push`, `release-image` and `publish`, so that Trivy never runs next + # to the Docker Hub credentials, the `contents: write` token and the signing + # identity scan: - name: Scan image + name: Scan release image needs: [prepare, push] runs-on: ubuntu-latest timeout-minutes: 20 @@ -233,36 +252,33 @@ jobs: exit 1 fi - name: Scan image - uses: elixir-cloud-aai/.github/actions/scan-image@743e82d290a53768454999e413756a924e383259 # v1.0.0 + uses: elixir-cloud-aai/.github/actions/scan-image@31f22fccc1f3c597ed7c1d1f75b2f85522155348 # v1.1.0 with: image: ${{ env.IMAGE_NAME }}@${{ needs.push.outputs.digest }} category: release upload: 'false' - publish: - name: Publish image + # Attests, signs and tags the scanned digest + release-image: + name: Release image needs: [prepare, push, scan] runs-on: ubuntu-latest timeout-minutes: 30 - environment: - name: release - url: ${{ github.server_url }}/${{ github.repository }}/releases/tag/${{ github.ref_name }} + environment: release permissions: - contents: write # create the GitHub release + contents: read id-token: write # Sigstore signing certificates attestations: write # GitHub artifact attestations env: VERSION: ${{ needs.prepare.outputs.version }} DIGEST: ${{ needs.push.outputs.digest }} steps: - # The commit checked by `prepare`, with all tags, to find the previous - # release + # The commit checked by `prepare` - name: Check out repository uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false ref: ${{ needs.prepare.outputs.sha }} - fetch-depth: 0 - name: Check image digest run: | if [[ ! "${DIGEST}" =~ ^sha256:[0-9a-f]{64}$ ]]; then @@ -272,7 +288,7 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1 - name: Log in to Docker Hub - uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0 + uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550 # v4.8.0 with: username: ${{ secrets.DOCKERHUB_LOGIN }} password: ${{ secrets.DOCKERHUB_TOKEN }} @@ -307,7 +323,7 @@ jobs: # No artifact metadata storage record (needs another permission) create-storage-record: false - name: Install cosign - uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2 + uses: sigstore/cosign-installer@756fe2d284c7292c4e9b62c8a28f1e5629c59532 # v4.1.3 # The signature covers the digest, and so every tag of it - name: Sign image run: cosign sign --yes "${IMAGE_NAME}@${DIGEST}" @@ -359,68 +375,38 @@ jobs: exit 1 fi done - # A draft first, published last, so that immutable releases (a repository - # setting) can still get their notes; re-runs finish the draft of an - # earlier attempt and leave a published release as it is. GitHub's - # generated notes list the pull requests merged since the previous - # release: the highest version tag in the history of the release commit, - # on another commit, that has a published release. Tags without one (e.g. - # of a failed run) don't count; without any, GitHub picks the start, e.g. - # all changes for the first release. The maintainers check the notes and - # add the curated sections afterwards (the notes of published releases - # stay editable) + + # Creates the GitHub release of the tag once the image is released: the + # curated notes of the tagged commit (`docs/releases/.md`), then + # GitHub's generated notes under `## Commits`, with the `**Full Changelog**` + # line last; the latest release by version (calendar versions are never + # pre-releases). No environment: it needs no secrets, only + # `contents: write`. The tag must still point to the release commit. Fails + # on a draft of the tag, and on a published release unless an earlier + # attempt of this job created it (then it passes without changes). One at a + # time, so that the latest release is decided in order; a cancelled pending + # run is re-run like a failed one. The latest GitHub release (the action, by + # version among published releases) and the image's `latest` tag + # (`release-image`, by version among the tags on `main`) are decided + # separately, by the same rule: the highest version + publish: + name: Publish release + needs: [prepare, release-image] + runs-on: ubuntu-latest + timeout-minutes: 10 + concurrency: + group: ${{ github.workflow }}-publish-release + cancel-in-progress: false + permissions: + contents: write # create the release + steps: + - name: Check out repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + ref: ${{ needs.prepare.outputs.sha }} - name: Create release - env: - GH_TOKEN: ${{ github.token }} - GH_REPO: ${{ github.repository }} - TAG: ${{ github.ref_name }} - LATEST: ${{ steps.latest.outputs.latest }} - run: | - # only "not found" means no release: other errors stop the run, so - # that a re-run never creates a second draft - status=0 - state="$(gh release view "${TAG}" --json isDraft --jq 'if .isDraft then "draft" else "published" end' 2>&1)" || status=$? - if [[ "${status}" != 0 ]]; then - if [[ "${state}" != *"release not found"* ]]; then - echo "::error::Cannot check whether release ${TAG} exists: ${state}" - exit 1 - fi - state=none - fi - if [[ ! "${state}" =~ ^(draft|published|none)$ ]]; then - echo "::error::Unexpected state of release ${TAG}: ${state}" - exit 1 - fi - if [[ "${state}" == "published" ]]; then - echo "Release ${TAG} is already published: left as it is" - exit 0 - fi - if [[ "${state}" == "none" ]]; then - published="$(gh release list --limit 1000 --exclude-drafts \ - --json tagName --jq '.[].tagName')" - previous="" - head="$(git rev-parse HEAD)" - while read -r tag; do - if [[ "$(git rev-parse "${tag}^{commit}")" == "${head}" ]]; then - continue - fi - if grep -qxF -- "${tag}" <<< "${published}"; then - previous="${tag}" - break - fi - done < <(git tag -l 'v*' --merged HEAD --sort=-v:refname) - args=(-f "tag_name=${TAG}") - if [[ -n "${previous}" ]]; then - args+=(-f "previous_tag_name=${previous}") - fi - notes="$(mktemp)" - gh api "repos/${GH_REPO}/releases/generate-notes" "${args[@]}" \ - --jq .body > "${notes}" - gh release create "${TAG}" \ - --draft \ - --verify-tag \ - --title "${TAG}" \ - --notes-file "${notes}" - fi - gh release edit "${TAG}" --title "${TAG}" \ - --latest="${LATEST}" --draft=false + uses: elixir-cloud-aai/.github/actions/publish-release@31f22fccc1f3c597ed7c1d1f75b2f85522155348 # v1.1.0 + with: + notes: docs/releases/${{ needs.prepare.outputs.version }}.md + commit: ${{ needs.prepare.outputs.sha }} diff --git a/.github/workflows/scan.yml b/.github/workflows/scan.yml index d2b88a6..3701f01 100644 --- a/.github/workflows/scan.yml +++ b/.github/workflows/scan.yml @@ -70,7 +70,7 @@ jobs: echo "image=${IMAGE_NAME}:${tag#v}" >> "$GITHUB_OUTPUT" - name: Scan image if: ${{ steps.release.outputs.image != '' }} - uses: elixir-cloud-aai/.github/actions/scan-image@743e82d290a53768454999e413756a924e383259 # v1.0.0 + uses: elixir-cloud-aai/.github/actions/scan-image@31f22fccc1f3c597ed7c1d1f75b2f85522155348 # v1.1.0 with: image: ${{ steps.release.outputs.image }} category: release-image diff --git a/README.md b/README.md index 97c45d5..c21bfc1 100644 --- a/README.md +++ b/README.md @@ -114,7 +114,9 @@ services, products and Nodes, and that every referenced image exists. - `PR title`: the title follows Conventional Commits and has at most 50 characters (see [Contributing](#contributing)). - `Lint`: lints all JavaScript and TypeScript sources with ESLint - (`npm run lint`); errors and warnings fail it. + (`npm run lint`); errors and warnings fail it. It also checks the curated + release notes in `docs/releases/` (see [Releasing](#releasing)), and that + those of the version in `package.json` exist once it is a release version. - `Test`: runs the tests with coverage and reports it to [Codecov][badge-url-coverage]. [`codecov.yml`](codecov.yml) states the target of this repo (70%, working up from about 38%); the status only reports for @@ -232,15 +234,29 @@ pre-releases, as the Vercel previews cover that. Releases are cut by the maintainers: -1. Open a release-prep pull request into `dev` that sets the version in - `package.json` and `package-lock.json`, without the `v`, and merge it. The - version in `package.json` must match the tag, so each release needs this - change: +1. Open a release-prep pull request into `dev`: add the curated release notes + as `docs/releases/.md` (without the `v`, e.g. + `docs/releases/2026.11.0.md`), and set the version in `package.json` and + `package-lock.json`, also without the `v`. Merge it. The version in + `package.json` must match the tag, so each release needs this change: ```bash npm version 2026.11.0 --no-git-tag-version ``` + The release workflow publishes the notes as the start of the GitHub + release, so they follow the organization's format, which CI (job `Lint`) + and the release workflow's first job check: an intro paragraph saying what + the release brings, then the sections `## Breaking changes`, `## Features`, + `## Security`, `## Fixes`, `## Documentation` and `## Maintenance` (in this + order, empty ones left out), holding bullets only, each ending with its + issue and pull request numbers, e.g., `(#12, #34)`. Links must be absolute + (e.g., `https://elixir-on.cloud/demo`), as they must also work on GitHub; + no `## Commits` section and no `**Full Changelog**` line, which the + workflow adds. The shared action + [`publish-release`](https://github.com/elixir-cloud-aai/.github/tree/main/actions/publish-release) + describes the format and its checks. + 2. Wait until CI has passed for the push to `dev` of the commit that the merge created on `dev` (``, not the head of the pull request): the release workflow requires a successful CI run for a push of the tagged commit (runs @@ -273,8 +289,16 @@ Releases are cut by the maintainers: [[ "v${version}" =~ ${pattern} ]] || { echo "Not a release version: v${version}"; exit 1; } IFS=. read -r year month _ <<< "${version}" (( year * 100 + month <= $(date -u +%Y%m) )) || { echo "Version is in the future: v${version}"; exit 1; } - # The file of the commit, not of the working tree + # The files of the commit, not of the working tree [[ "$(git show "${sha}:package.json" | jq -r .version)" == "${version}" ]] || { echo "Wrong version in package.json"; exit 1; } + # The notes of the commit, with the checker of the action that + # `release.yml` pins (as the job `Lint` of `ci.yml` does) + notes="$(mktemp -d)" && git show "${sha}:docs/releases/${version}.md" > "${notes}/notes.md" && + curl -fsSL "https://raw.githubusercontent.com/elixir-cloud-aai/.github/31f22fccc1f3c597ed7c1d1f75b2f85522155348/actions/publish-release/publish.py" -o "${notes}/publish.py" && + python3 -I "${notes}/publish.py" check "${notes}/notes.md" || { echo "Release notes docs/releases/${version}.md missing or not in the format"; exit 1; } + # Also drafts, which the release workflow can't see before it fails on them + release="$(gh release view "v${version}" --repo elixir-cloud-aai/landing-page 2>&1)" && { echo "A release or draft of v${version} exists: delete a draft"; exit 1; } + [[ "${release}" == *"release not found"* ]] || { echo "Cannot check the releases: ${release}"; exit 1; } runs="$(gh api "repos/elixir-cloud-aai/landing-page/actions/workflows/ci.yml/runs?head_sha=${sha}&branch=dev&event=push&status=success&per_page=1" --jq .total_count)" (( runs >= 1 )) || { echo "No successful CI run for the push of ${sha} to dev"; exit 1; } git merge-base --is-ancestor origin/main "${sha}" || { echo "main can't be fast-forwarded to ${sha}"; exit 1; } @@ -295,20 +319,23 @@ Releases are cut by the maintainers: 4. Approve the jobs of the [release workflow](.github/workflows/release.yml) in the `release` environment, after checking that the run is for the tag you pushed. It checks that GitHub - verified the tag's signature, that its commit is on `main`, the version and - the CI run; pushes, scans, signs and tags the image, and publishes the GitHub - release with the generated notes. If a job fails, use "Re-run failed jobs", - not "Re-run all jobs": once the image is tagged, a new attempt of all jobs - stops at the existing tag and can't finish the release. If `prepare` fails - because CI hasn't finished for the commit, re-run the workflow once it - passed. -5. Edit the release notes into the org's format: an intro paragraph; the - sections `## Breaking changes`, `## Features`, `## Security`, `## Fixes`, - `## Documentation` and `## Maintenance`, without the empty ones, each bullet - ending with its issue and pull request numbers; then the generated notes - under `## Commits` instead of `## What's Changed`, and last their - `**Full Changelog**` line. -6. Check the site within a few minutes: Watchtower deploys the new image, if + verified the tag's signature, that its commit is on `main`, the version, the + release notes and the CI run; pushes, scans, signs and tags the image + (`Release image`), and then, without another approval, creates the GitHub + release (`Publish release`): the curated notes of the tagged commit, then + GitHub's generated notes under `## Commits` (without their + `## What's Changed` header, with "New Contributors"), and GitHub's + `**Full Changelog**` line last. Releases aren't edited after publishing (by + convention): fix mistakes in the notes of the next release. If a job fails, + use "Re-run failed jobs", not "Re-run all jobs": once the image is tagged, a + new attempt of all jobs stops at the existing tag and can't finish the + release, and once the GitHub release exists, `prepare` fails; a re-run of + `Publish release` passes without changes if an earlier attempt created the + release after all. `prepare` can't see draft releases and `Publish release` + fails on them, so delete any draft of the tag before you push the tag. If + `prepare` fails because CI hasn't finished for the commit, re-run the + workflow once it passed. +5. Check the site within a few minutes: Watchtower deploys the new image, if this is the highest release (the workflow warns otherwise). After the first release, [move the host to Docker Hub](#moving-the-host-to-docker-hub). From 0afce94fda3b391d8d7f6abc83a3a98ef4fe7972 Mon Sep 17 00:00:00 2001 From: Alex Kanitz Date: Fri, 20 Nov 2026 20:29:19 +0100 Subject: [PATCH 7/9] ci: check the notes checker against the pins Dependabot bumps only the `uses:` pins of publish-release: the Lint job now fails when its checker or the README's pre-tag block uses another commit, so that CI, the pre-tag checks and `prepare` run the same checker. README: name the release jobs in order and which wait for approval, fix the Audit bullet (nothing deploys from main any more), and list the tools the pre-tag block needs. Rewrap two comments. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 16 ++++++++++++++-- .github/workflows/release.yml | 10 +++++----- .trivyignore.yaml | 6 +++--- README.md | 16 ++++++++++------ 4 files changed, 32 insertions(+), 16 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5e116ab..bef8f6d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -96,8 +96,19 @@ jobs: # (`0.1.0`, from before the first release, has none) - name: Check release notes env: - CHECKER: https://raw.githubusercontent.com/elixir-cloud-aai/.github/31f22fccc1f3c597ed7c1d1f75b2f85522155348/actions/publish-release/publish.py + CHECKER_SHA: 31f22fccc1f3c597ed7c1d1f75b2f85522155348 # v1.1.0 run: | + # Dependabot bumps only the `uses:` pins of `release.yml`: the + # checker here and in the README's pre-tag block must follow them + pins="$(grep -ohE 'publish-release@[0-9a-f]{40}' .github/workflows/release.yml | sort -u)" + if [[ "${pins}" != "publish-release@${CHECKER_SHA}" ]]; then + echo "::error file=.github/workflows/ci.yml::The checker (${CHECKER_SHA}) doesn't match the publish-release pins of release.yml: ${pins//$'\n'/, }" + exit 1 + fi + if ! grep -qF "elixir-cloud-aai/.github/${CHECKER_SHA}/actions/publish-release/publish.py" README.md; then + echo "::error file=README.md::The pre-tag block of README.md doesn't use the checker ${CHECKER_SHA}" + exit 1 + fi version="$(jq -r .version package.json)" if [[ "v${version}" =~ ^v20[0-9]{2}\.([1-9]|1[0-2])\.(0|[1-9][0-9]*)$ \ && ! -f "docs/releases/${version}.md" ]]; then @@ -110,7 +121,8 @@ jobs: echo "No release notes yet" exit 0 fi - curl -fsSL "${CHECKER}" -o "${RUNNER_TEMP}/publish.py" + curl -fsSL "https://raw.githubusercontent.com/elixir-cloud-aai/.github/${CHECKER_SHA}/actions/publish-release/publish.py" \ + -o "${RUNNER_TEMP}/publish.py" for file in "${notes[@]}"; do python3 -I "${RUNNER_TEMP}/publish.py" check "${file}" done diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d9ad86a..8ed4c86 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -149,9 +149,9 @@ jobs: # Builds the image of the release commit once and pushes it by digest only # (untagged, with SBOM and provenance attestations), for `scan` to scan and - # `release-image` to sign and tag. Digests of runs that fail (or fail the scan) are - # never signed or tagged, but stay on Docker Hub, untagged (pullable by digest - # only) + # `release-image` to sign and tag. Digests of runs that fail (or fail the + # scan) are never signed or tagged, but stay on Docker Hub, untagged + # (pullable by digest only) push: name: Push release image needs: prepare @@ -173,8 +173,8 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1 # OCI labels with the version, commit and source; `tags` only sets the - # version label (the image is tagged by digest in `release-image`, after the - # scan) + # version label (the image is tagged by digest in `release-image`, after + # the scan) - name: Generate image labels id: meta uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0 diff --git a/.trivyignore.yaml b/.trivyignore.yaml index 4085eb7..766461f 100644 --- a/.trivyignore.yaml +++ b/.trivyignore.yaml @@ -1,9 +1,9 @@ # Vulnerabilities accepted in the Docker image (`Dockerfile`), which the scans # (CI, release and weekly scan workflows) ignore: each with the reason # (`statement`) and an expiry date (`expired_at`), after which Trivy reports it -# again, so that the decision is reviewed. Limit entries to the affected package versions -# (`purls`), so that other packages with the same vulnerability are still -# reported. Example: +# again, so that the decision is reviewed. Limit entries to the affected +# package versions (`purls`), so that other packages with the same +# vulnerability are still reported. Example: # # vulnerabilities: # - id: CVE-2026-12345 diff --git a/README.md b/README.md index c21bfc1..54cbd52 100644 --- a/README.md +++ b/README.md @@ -128,8 +128,8 @@ services, products and Nodes, and that every referenced image exists. To run it locally: `npm audit --omit=dev --audit-level=high`. Development tools are not audited, as they don't reach the site. The job checks npm's advisory database as it is when the job runs, so a newly published advisory - fails every new run, without a change to the code, and also holds back - deployments of commits without a green run. Fix it by updating the package + fails every new run, without a change to the code, and also keeps commits + without a green run from being released (the release workflow requires one). Fix it by updating the package (`npm update ` within its version range, otherwise `npm install @`, or the dependency that pulls it in). There is no list of accepted advisories: if no fix exists yet, a maintainer @@ -275,7 +275,8 @@ Releases are cut by the maintainers: tagging: the release workflow checks the tagged commit, so a check that fails after the tag is pushed (other than a CI run that hasn't finished yet) fails again on re-runs, and the release then needs a new version. The commands - expect `origin` to be `elixir-cloud-aai/landing-page`. + expect `origin` to be `elixir-cloud-aai/landing-page`, and need `jq`, `curl`, + `python3` (3.10 or later) and `gh` (logged in). ```bash version=YYYY.M.MICRO # e.g. 2026.11.0 @@ -318,10 +319,13 @@ Releases are cut by the maintainers: 4. Approve the jobs of the [release workflow](.github/workflows/release.yml) in the `release` environment, after - checking that the run is for the tag you pushed. It checks that GitHub + checking that the run is for the tag you pushed. Its jobs run in this order, + and two of them wait for approval: `Prepare release` checks that GitHub verified the tag's signature, that its commit is on `main`, the version, the - release notes and the CI run; pushes, scans, signs and tags the image - (`Release image`), and then, without another approval, creates the GitHub + release notes and the CI run; `Push release image` (approval) builds and + pushes the image by digest; `Scan release image` scans that digest; + `Release image` (approval) attests, signs and tags it; and then + `Publish release`, without another approval, creates the GitHub release (`Publish release`): the curated notes of the tagged commit, then GitHub's generated notes under `## Commits` (without their `## What's Changed` header, with "New Contributors"), and GitHub's From c2dfdf87fcc075e4e638080360cb3adbb49e3402 Mon Sep 17 00:00:00 2001 From: Alex Kanitz Date: Fri, 20 Nov 2026 21:26:43 +0100 Subject: [PATCH 8/9] docs: warn against updating hosts before release Until the first release, `latest` on Docker Hub is the 2024 image: a host that pulls this compose file and restarts would serve it. Warn in docker-compose.yaml and the Deployment section, and tell operators to check that the host is on `main`. The pre-tag block now stops if the tag exists already, and the Checks section says that Dependabot's pin bumps of publish-release need the checker commit updated by hand. Co-Authored-By: Claude Opus 5.5 --- README.md | 14 +++++++++++++- docker-compose.yaml | 4 +++- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0bc491b..e39d191 100644 --- a/README.md +++ b/README.md @@ -117,6 +117,11 @@ services, products and Nodes, and that every referenced image exists. (`npm run lint`); errors and warnings fail it. It also checks the curated release notes in `docs/releases/` (see [Releasing](#releasing)), and that those of the version in `package.json` exist once it is a release version. + Its checker must be the commit that `release.yml` pins for `publish-release`, + as must the one in the pre-tag block of [Releasing](#releasing): Dependabot + bumps only the pins, so its pull requests that bump them fail `Lint` until + `CHECKER_SHA` in `ci.yml` and the URL in the README are updated by hand on + their branch. - `Test`: runs the tests with coverage and reports it to [Codecov][badge-url-coverage]. [`codecov.yml`](codecov.yml) states the target of this repo (70%, working up from about 38%); the status only reports for @@ -166,7 +171,12 @@ docker compose up -d ``` Watchtower updates the image only: when `docker-compose.yaml` changes, run -`git pull` and `docker compose up -d` on the host. The site listens on port 80 +`git pull` and `docker compose up -d` on the host. **Until the first release +has finished, don't pull or restart a host that still serves the image from +`ghcr.io`:** `latest` on Docker Hub is then an image from 2024, and the +compose file of this version would put it live. Check the host's branch first +(`git branch --show-current`; it must be `main`), and move the host as +described [below](#moving-the-host-to-docker-hub). The site listens on port 80 (change it in `docker-compose.yaml`). TLS is expected to be terminated by a reverse proxy in front of it. To build locally instead of pulling, run `docker compose up -d --build`. @@ -299,6 +309,8 @@ Releases are cut by the maintainers: notes="$(mktemp -d)" && git show "${sha}:docs/releases/${version}.md" > "${notes}/notes.md" && curl -fsSL "https://raw.githubusercontent.com/elixir-cloud-aai/.github/31f22fccc1f3c597ed7c1d1f75b2f85522155348/actions/publish-release/publish.py" -o "${notes}/publish.py" && python3 -I "${notes}/publish.py" check "${notes}/notes.md" || { echo "Release notes docs/releases/${version}.md missing or not in the format"; exit 1; } + # A tag is used up, also if its release failed + [[ -z "$(git ls-remote --tags origin "refs/tags/v${version}")" ]] || { echo "Tag v${version} exists already: use the next MICRO"; exit 1; } # Also drafts, which the release workflow can't see before it fails on them release="$(gh release view "v${version}" --repo elixir-cloud-aai/landing-page 2>&1)" && { echo "A release or draft of v${version} exists: delete a draft"; exit 1; } [[ "${release}" == *"release not found"* ]] || { echo "Cannot check the releases: ${release}"; exit 1; } diff --git a/docker-compose.yaml b/docker-compose.yaml index 3554be7..678dbca 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -7,7 +7,9 @@ # docker compose up -d # start (or update this file and re-run) # docker compose logs -f site # follow the site's logs # -# To move a host from GHCR (only after the first release) or to roll back, see +# Until the first release has finished, `latest` on Docker Hub is an image +# from 2024: don't pull or `docker compose up` a host that runs the GHCR image +# with this file before then. To move a host from GHCR or to roll back, see # "Deployment" in README.md. To build locally instead of pulling: # docker compose up -d --build services: From 1d073ea5fddb07e04839badc39fc5cc4c0b1940c Mon Sep 17 00:00:00 2001 From: Alex Kanitz Date: Fri, 20 Nov 2026 21:48:08 +0100 Subject: [PATCH 9/9] docs: stop the pre-tag block if tags can't be listed A failing `git ls-remote` gave empty output, so the check for an existing tag passed. Also drop a doubled job name in step 4 and rewrap the Audit bullet. Co-Authored-By: Claude Opus 5.5 --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e39d191..bb66995 100644 --- a/README.md +++ b/README.md @@ -136,8 +136,9 @@ services, products and Nodes, and that every referenced image exists. `devDependencies` (a test checks this). The job checks npm's advisory database as it is when the job runs, so a newly published advisory fails every new run, without a change to the code, and also keeps commits - without a green run from being released (the release workflow requires one). Fix it by updating the package - (`npm update ` within its version range, otherwise + without a green run from being released (the release workflow requires one). + Fix it by updating the package (`npm update ` within its version + range, otherwise `npm install @`, or the dependency that pulls it in). There is no list of accepted advisories: if no fix exists yet, a maintainer decides, in a pull request, whether to change the job for the time being. @@ -310,7 +311,8 @@ Releases are cut by the maintainers: curl -fsSL "https://raw.githubusercontent.com/elixir-cloud-aai/.github/31f22fccc1f3c597ed7c1d1f75b2f85522155348/actions/publish-release/publish.py" -o "${notes}/publish.py" && python3 -I "${notes}/publish.py" check "${notes}/notes.md" || { echo "Release notes docs/releases/${version}.md missing or not in the format"; exit 1; } # A tag is used up, also if its release failed - [[ -z "$(git ls-remote --tags origin "refs/tags/v${version}")" ]] || { echo "Tag v${version} exists already: use the next MICRO"; exit 1; } + tags="$(git ls-remote --tags origin "refs/tags/v${version}")" || { echo "Cannot list the tags"; exit 1; } + [[ -z "${tags}" ]] || { echo "Tag v${version} exists already: use the next MICRO"; exit 1; } # Also drafts, which the release workflow can't see before it fails on them release="$(gh release view "v${version}" --repo elixir-cloud-aai/landing-page 2>&1)" && { echo "A release or draft of v${version} exists: delete a draft"; exit 1; } [[ "${release}" == *"release not found"* ]] || { echo "Cannot check the releases: ${release}"; exit 1; } @@ -340,7 +342,7 @@ Releases are cut by the maintainers: pushes the image by digest; `Scan release image` scans that digest; `Release image` (approval) attests, signs and tags it; and then `Publish release`, without another approval, creates the GitHub - release (`Publish release`): the curated notes of the tagged commit, then + release: the curated notes of the tagged commit, then GitHub's generated notes under `## Commits` (without their `## What's Changed` header, with "New Contributors"), and GitHub's `**Full Changelog**` line last. Releases aren't edited after publishing (by