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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ jobs:
(cd contrib/pullgate && "$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh -x -- *.sh)
"$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh contrib/ansible/build.sh contrib/ansible/test/ci.sh
# The release build and the checks of the Release check workflow.
"$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh scripts/build-release.sh scripts/release-check/*.sh
"$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh scripts/build-release.sh scripts/verify-release.sh scripts/release-check/*.sh
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: go.mod
Expand Down
68 changes: 64 additions & 4 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -87,14 +87,18 @@ jobs:
path: dist/
if-no-files-found: error

# Signs and publishes the files from the build job. It runs no code from
# the repository.
publish:
# Signs the files from the build job and adds them to the draft release.
# It runs no code from the repository. It does not publish: verify checks
# the draft's files first.
upload:
needs: [release-please, build]
if: needs.release-please.outputs.release_created == 'true'
runs-on: ubuntu-latest
outputs:
# The SHA-256 and the name of each file of the draft that verify gets.
files: ${{ steps.draft.outputs.files }}
permissions:
contents: write # upload the files and publish the draft release
contents: write # upload the files to the draft release
id-token: write # sign the attestation (Sigstore)
attestations: write # store the attestation
env:
Expand Down Expand Up @@ -154,6 +158,62 @@ jobs:
env:
GH_TOKEN: ${{ github.token }}
run: gh release upload "$TAG" dist/*.tar.gz dist/SHA256SUMS "dist/nodkey_${VERSION}.sigstore.json" --clobber --repo "$GITHUB_REPOSITORY"
# The files of a draft can only be read with write access, so this
# job gets them back, and verify, which can only read, checks them.
- name: Download the files of the draft release
id: draft
env:
GH_TOKEN: ${{ github.token }}
run: |
set -euo pipefail
gh release download "$TAG" --dir draft --repo "$GITHUB_REPOSITORY"
# publish compares this list with the assets of the draft, so it
# publishes only the files that verify checked.
echo "files=$(cd draft && sha256sum -- * | LC_ALL=C sort -k2 | sha256sum | cut -d' ' -f1)" >>"$GITHUB_OUTPUT"
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: draft-files
path: draft/
if-no-files-found: error

# The verify gate: checks the files of the draft as a user would
# (verify-release.yml, docs/releasing.md "The verify gate"). It can only
# read. When it fails, the release stays a draft.
verify:
needs: [release-please, upload]
if: needs.release-please.outputs.release_created == 'true'
permissions:
contents: read
uses: ./.github/workflows/verify-release.yml
with:
version: ${{ needs.release-please.outputs.version }}
artifact: draft-files

# Publishes the draft release, only after verify passed. It runs no code
# from the repository.
publish:
needs: [release-please, upload, verify]
if: needs.release-please.outputs.release_created == 'true' && needs.verify.outputs.verified == 'true'
runs-on: ubuntu-latest
permissions:
contents: write # publish the draft release
env:
TAG: ${{ needs.release-please.outputs.tag_name }}
steps:
- name: Check that the draft still has the verified files
env:
GH_TOKEN: ${{ github.token }}
FILES: ${{ needs.upload.outputs.files }}
run: |
set -euo pipefail
# The digest of each asset, in the form of sha256sum. An asset
# without a digest gives an empty line, and the check fails.
now="$(gh release view "$TAG" --repo "$GITHUB_REPOSITORY" --json assets \
--jq '.assets[] | "\((.digest // "") | ltrimstr("sha256:")) \(.name)"' | LC_ALL=C sort -k2 | sha256sum | cut -d' ' -f1)"
if [ -z "$FILES" ] || [ "$now" != "$FILES" ]; then
echo "::error::The files of the draft changed after verify checked them. Nothing is published. See docs/releasing.md."
exit 1
fi
- name: Publish the release
env:
GH_TOKEN: ${{ github.token }}
Expand Down
167 changes: 167 additions & 0 deletions .github/workflows/verify-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,167 @@
name: Verify release

# The verify gate of a release (docs/releasing.md, "The verify gate").
# release.yml calls it with the files of the draft release, between the
# upload of the files and the publish. It can only read.
#
# Run by hand, it is a dry run: it checks the files of a published release,
# with one file broken on purpose if you ask, and then shows whether the
# publish would run. It publishes nothing.

on:
workflow_call:
inputs:
version:
description: The version X.Y.Z of the draft release
required: true
type: string
artifact:
description: The artifact with the files of the draft release
required: true
type: string
outputs:
verified:
description: true only when every check passed
value: ${{ jobs.verify.outputs.verified }}
workflow_dispatch:
inputs:
version:
description: A published release X.Y.Z to check (dry run)
required: true
type: string
break:
description: Break a file on purpose; the verify must then fail
required: true
default: none
type: choice
options:
- none
- tarball # one byte more in the pullgate tarball
- tarball-and-sums # the same, and SHA256SUMS made to match it
- extra-file # one more file in the release

permissions: {}

jobs:
# Dry run only: the files of a published release, maybe broken.
dry-run-files:
if: github.event_name == 'workflow_dispatch'
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: read
steps:
- name: Download the files of the release
env:
GH_TOKEN: ${{ github.token }}
VERSION: ${{ inputs.version }}
BREAK: ${{ inputs.break }}
run: |
set -euo pipefail
if ! printf '%s\n' "$VERSION" | grep -Eqx '[0-9]+\.[0-9]+\.[0-9]+'; then
echo "::error::The version is not X.Y.Z."
exit 1
fi
mkdir draft
gh release download "v$VERSION" --repo "$GITHUB_REPOSITORY" --dir draft
t="draft/nodkey_${VERSION}_pullgate.tar.gz"
case $BREAK in
none) ;;
tarball) printf x >>"$t" ;;
tarball-and-sums)
printf x >>"$t"
(cd draft && grep -v ' nodkey_.*_pullgate.tar.gz$' SHA256SUMS >sums && sha256sum "${t#draft/}" >>sums && mv sums SHA256SUMS) ;;
extra-file) echo "not a file of the release" >draft/extra.txt ;;
*) echo "::error::Unknown break '$BREAK'."; exit 1 ;;
esac
echo "broken on purpose: $BREAK"
ls -l draft
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: dry-run-files
path: draft/
if-no-files-found: error

verify:
needs: dry-run-files
# On a call from release.yml, dry-run-files is skipped.
if: always() && (needs.dry-run-files.result == 'success' || (github.event_name != 'workflow_dispatch' && needs.dry-run-files.result == 'skipped'))
runs-on: ubuntu-latest
timeout-minutes: 20
permissions:
contents: read
outputs:
verified: ${{ steps.verify.outputs.verified }}
env:
VERSION: ${{ inputs.version }}
ARTIFACT: ${{ github.event_name == 'workflow_dispatch' && 'dry-run-files' || inputs.artifact }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
# The tags: the dry run names the commit of an older release.
fetch-depth: 0
persist-credentials: false
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
# Only to read the build info of the binaries (go version -m).
go-version: stable
cache: false
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: ${{ env.ARTIFACT }}
path: draft
- name: Get gh 2.102.0 for install.sh
# install.sh downloads this gh and checks it against the SHA-256 in
# install.sh. In the container, github.com is a local server, so
# the file is fetched here first.
run: |
set -euo pipefail
mkdir -p "${RUNNER_TEMP}/gh"
curl --proto '=https' --tlsv1.2 -fsSL --retry 3 -o "${RUNNER_TEMP}/gh/gh_2.102.0_linux_amd64.tar.gz" \
https://github.com/cli/cli/releases/download/v2.102.0/gh_2.102.0_linux_amd64.tar.gz
- name: Verify the files of the draft
id: verify
env:
DRY_RUN: ${{ github.event_name == 'workflow_dispatch' }}
run: |
set -euo pipefail
if ! printf '%s\n' "$VERSION" | grep -Eqx '[0-9]+\.[0-9]+\.[0-9]+'; then
echo "::error::The version is not X.Y.Z."
exit 1
fi
if [ "$DRY_RUN" = true ]; then
# An older release: its own commit, and the kinds of files that
# it has.
export NODKEY_VERIFY_COMMIT NODKEY_VERIFY_KINDS
NODKEY_VERIFY_COMMIT="$(git rev-parse "refs/tags/v${VERSION}^{commit}")"
NODKEY_VERIFY_KINDS="linux_amd64 linux_arm64 pullgate"
if [ -n "$(git ls-tree "v${VERSION}" contrib/ansible/build.sh)" ]; then
NODKEY_VERIFY_KINDS="ansible $NODKEY_VERIFY_KINDS"
fi
fi
rc=0
sh scripts/verify-release.sh draft "$VERSION" "${RUNNER_TEMP}/gh/gh_2.102.0_linux_amd64.tar.gz" 2>&1 | tee verify.txt || rc=$?
{
echo "## Verify ${VERSION}"
echo
echo '```text'
cat verify.txt
echo '```'
} >>"$GITHUB_STEP_SUMMARY"
if [ "$rc" -ne 0 ]; then
echo "::error::A check of the draft failed; see the summary. The release stays a draft (docs/releasing.md)."
exit 1
fi
# publish needs this output: a skipped verify must not count as passed.
echo "verified=true" >>"$GITHUB_OUTPUT"

# Dry run only: in release.yml, the publish job needs verify in the same
# way. This job does nothing; it shows whether the publish would run.
would-publish:
if: github.event_name == 'workflow_dispatch' && needs.verify.outputs.verified == 'true'
needs: verify
runs-on: ubuntu-latest
timeout-minutes: 5
permissions: {}
steps:
- run: echo "The verify passed, so release.yml would publish the release now. This dry run publishes nothing."
3 changes: 3 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@ Planned. Each v1 issue adds its part.
(`.github/workflows/release-check.yml`, docs/releasing.md "Check a
release candidate"). Their tests are in `scripts_linux_test.go`, at the
root of the module. CI checks them with shellcheck.
`scripts/verify-release.sh` is the verify gate of a release: release.yml
runs it through `.github/workflows/verify-release.yml` on the files of
the draft, before it publishes (docs/releasing.md "The verify gate").
- `cmd/nodkey/` - the one binary. Subcommands: `broker`, `try`, `run`,
`ssh-agent`, `ssh-grant`, `preapprove`, `agent-browser-plugin`, `keygen`,
`audit verify`, `update`, `version`, `doctor`.
Expand Down
6 changes: 6 additions & 0 deletions THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -653,6 +653,12 @@ before they install anything (DESIGN.md section 18). What they trust:
a file. Its update check uses a made-up bundle and a fake gh, so it
proves nothing about the attestation; only the release workflow on
`main` can make one.
- The release is published only after the `verify` job has checked the
files of the draft, with read access only: their names, `SHA256SUMS`,
the attestation with the production identity, the version in each
binary, and an install with `install.sh` as a user does it
(docs/releasing.md, "The verify gate"). So a broken or wrong file stops
the release while it is still a draft, before anybody can download it.
- Both trust root on the host where they run, and the way the person got
root. As root, the script runs only the programs of the system, removes
the variables that change what they do (such as `TAR_OPTIONS`), and
Expand Down
67 changes: 57 additions & 10 deletions docs/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ After every push to `main`, the **Release** workflow runs release-please.
line of the changelog in it.** This text becomes the release notes.
5. When you merge it, release-please creates the tag (for example `v0.2.0`)
and a **draft** GitHub release with the release notes.
6. Then two more jobs run in the same workflow:
6. Then four more jobs run in the same workflow:
- `build` can only read the repository. It checks that the tag is the
commit of this workflow run. Then it runs
[`scripts/build-release.sh`](../scripts/build-release.sh), the one
Expand All @@ -181,28 +181,75 @@ After every push to `main`, the **Release** workflow runs release-please.
`nodkey_<version>_pullgate.tar.gz`. It makes the Ansible recipe
with `contrib/ansible/build.sh` and packs it into
`nodkey_<version>_ansible.tar.gz`, and writes `SHA256SUMS`.
- `publish` gets these files from `build`. It checks them against
- `upload` gets these files from `build`. It checks them against
`SHA256SUMS` and checks the tag again. Then it makes a signed build
provenance attestation for the tarballs. It saves the attestation as
one more file, `nodkey_<version>.sigstore.json` (a Sigstore bundle
for all tarballs), and checks all tarballs with it, with no login,
as in [Verify a download](#verify-a-download). Then it uploads the
files to the draft release and publishes it.
files to the draft release, and downloads them back from the draft.
- `verify` checks the files of the draft before anybody can see them
(see [The verify gate](#the-verify-gate)). It can only read.
- `publish` runs only when `verify` passed. It publishes the draft.

The release is never public without its files. Immutable releases are on
for this repository: after a release is published, nobody can change its
files or move its tag. This is why the files are added while the release is
still a draft.

### If `build` or `publish` fails
### The verify gate

The `verify` job ([`verify-release.yml`](../.github/workflows/verify-release.yml),
with [`scripts/verify-release.sh`](../scripts/verify-release.sh)) checks
the files of the draft release, as a user gets them:

1. The draft has exactly the expected files: the four tarballs,
`SHA256SUMS` and the bundle, and nothing else.
2. `SHA256SUMS` names each tarball once, and each tarball matches it.
3. The attestation in the bundle verifies each tarball, offline, with
the identity of [Verify a download](#verify-a-download). The bundle
names exactly the tarballs of `SHA256SUMS`.
4. Each binary is built for its CPU, from the commit of the release, as
version `v<version>`, from a clean checkout (its build info). The
amd64 binary also runs and prints `nodkey <version>`.
5. `install.sh` of the release installs the draft's tarball as root in a
clean `debian:trixie` container, with the same checks that a user
runs: the pinned gh and the real bundle. Only `github.com` and
`api.github.com` are a local HTTPS server there, because the files of
a draft are not public yet.

`publish` needs `verify`. When `verify` fails, nothing is published: the
release stays a draft, and nobody but the maintainers can see it.

**Dry run.** To see the gate work without a release, run the
**Verify release** workflow by hand (Actions, "Verify release", "Run
workflow"), with a published version and a way to break a file:

The release stays a draft. **Re-run failed jobs** uses the same commit and
the same workflow file as the first run. So a re-run only helps when the
failure was temporary, for example a network error.
```sh
gh workflow run verify-release.yml --repo code6x/nodkey -f version=0.7.0 -f break=tarball
```

For any other problem, fix it in a new `fix:` pull request, then merge the
next release pull request. That release gets a new version. You can delete
the old draft release. Its tag stays, because tags cannot be deleted.
It downloads the files of that release, breaks one if you ask, and runs
the same checks. With `break=none` it passes, and the job
`would-publish` runs. With a broken file, `verify` fails, and
`would-publish` is skipped, as `publish` is in a release. A dry run
publishes nothing.

### If `build`, `upload`, `verify` or `publish` fails

The release stays a draft. Nothing is public.

1. **Look.** Open the failed job. For `verify`, the summary of the run
lists each check with `ok` or `FAILED`.
2. **Re-run** only for a temporary failure, for example a network error.
**Re-run failed jobs** uses the same commit and the same workflow file
as the first run, so it does not help for any other problem.
3. **Fix** any other problem in a new `fix:` pull request.
4. **Delete the draft release** (Releases, the draft, Delete). The tag
stays: the ruleset for `v*` tags does not let anybody delete it (see
[Repository settings](#repository-settings)).
5. **Release again**: merge the next release pull request. That release
gets a new version.

## Check a release candidate

Expand Down
Loading
Loading