Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Merge main into feat/apt-repository

Claudef7b2d06ead13
diff --cc .github/workflows/release.yml
index 19553424,96b494f4..d0de39a6
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@@ -2,19 -2,18 +2,21 @@@ name: Releas
# Full hands-off release on a pushed v* tag:
# 1. goreleaser — builds tarballs, publishes the GitHub release + changelog,
- # updates the Homebrew tap, and attests the .deb files it built.
-# and updates the Homebrew tap. Signs the .deb/.rpm and
-# checksums.txt when the Linux signing key secret exists.
++# updates the Homebrew tap, and attests the .deb files it built. Signs the
++# .deb/.rpm and checksums.txt when the Linux signing key secret exists.
# 2. package — (after goreleaser) builds, signs, notarizes, and staples the
# macOS .pkg for both arches and attaches them plus the
# package update manifest to the same release.
- # 3. windows-package — (after goreleaser) builds the Windows MSI from the archive
+ # 3. windows-package — (after goreleaser) builds the Windows MSI from the archive and the pinned Vector
# goreleaser just published, installs it to prove it works, and
# attaches it. Unsigned for now, so it needs no secrets.
-# 4. finalize — (after all three) adds the .pkg, .msi and install.sh to checksums.txt and
-# records a GitHub build-provenance attestation for every file
-# checksums.txt lists. Re-signs the extended checksums.txt when
-# the Linux signing key secret exists.
+# 4. finalize — (after goreleaser, package and windows-package) adds the .pkg, .msi and
+# install.sh to checksums.txt and records a GitHub build-provenance
- # attestation for every file checksums.txt lists.
++# attestation for every file checksums.txt lists. Re-signs the extended
++# checksums.txt when the Linux signing key secret exists.
+# 5. apt-repository — (after goreleaser) adds the released .deb files, each checked against
+# goreleaser's attestation, to the signed apt repository in object storage. Skipped
+# until its APT_* secrets and variables are configured.
#
# Triggered only by pushed version tags, so outside contributors (whose fork PRs
# never receive secrets) cannot run it. All release secrets live in the protected
@@@ -101,28 -135,11 +143,29 @@@ jobs
env:
GITHUB_TOKEN: ${{ github.token }}
HOMEBREW_TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+ NFPM_PASSPHRASE: ${{ secrets.BEACON_LINUX_SIGNING_KEY_PASSPHRASE }}
GORELEASER_CURRENT_TAG: ${{ github.ref_name }}
GORELEASER_PREVIOUS_TAG: ${{ steps.tags.outputs.previous }}
- run: goreleaser release --clean --parallelism 1
+ run: goreleaser release --clean --parallelism 1 ${BEACON_GORELEASER_SKIP:-}
+ # The apt repository signs only packages this attests: goreleaser's own output, hashed here
+ # from dist/ in the release-environment job that built it, never from the release. Its
+ # predicate type is this repository's own, which finalize never writes. finalize re-hashes
+ # the release's assets, which anyone who can edit a release can swap together with
+ # checksums.txt, and its job can be re-run without approval; so an attestation from it
+ # proves only what the release held when it ran. The apt job asks for this predicate type.
+ #
+ # Non-fatal: the release is already published by now, and a failure here (a Sigstore or
+ # attestation API error) must not skip the .pkg, MSI and finalize, which need this job to
+ # succeed. Without the attestation the apt job refuses this tag's packages and fails alone.
+ - name: Attest the Linux packages goreleaser built
+ continue-on-error: true
+ uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
+ with:
+ subject-path: cli/beacon/dist/*.deb
+ predicate-type: https://github.com/Asymptote-Labs/agent-beacon/attestations/goreleaser-deb/v1
+ predicate: '{"builder":"goreleaser","job":"goreleaser"}'
+
package:
needs: goreleaser
runs-on: macos-latest
diff --cc CLAUDE.md
index 11ed0f0c,fd345997..649031e0
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@@ -275,12 -277,13 +277,19 @@@ A pushed `v*` tag runs the full releas
1. `goreleaser` (ubuntu, `environment: release`) builds the collector dists,
publishes the GitHub release + changelog and tarballs, and updates the
- Homebrew tap. It then attests the `.deb` files from its own `dist/` with
+ Homebrew tap. When the `BEACON_LINUX_SIGNING_KEY` secret exists, nfpm
+ signs the `.deb`/`.rpm` with it, and GoReleaser's `signs` entry signs
+ `checksums.txt` as `checksums.txt.sig` and attaches the public key
+ (`beacon-release-key.{asc,gpg}`, staged by the workflow under
+ `cli/beacon/release-key/`). GoReleaser uploads into a draft and publishes
+ last, so a pinned installer never sees a latest release without its `.sig`.
+ Without the secret the workflow passes `--skip=sign` and they ship unsigned.
++ It then attests the `.deb` files from its own `dist/` (signed, when the key exists) with
+ `actions/attest` and this repository's predicate type
+ (`.../attestations/goreleaser-deb/v1`), which the apt repository requires
+ (`id-token: write`, `attestations: write` on that job). The step is
+ `continue-on-error`, because the release is already published by then: a
+ failed attestation fails only the apt job, never the `.pkg`, MSI or finalize.
2. `package` (macOS, `needs: goreleaser`, `environment: release`) builds the
Apple Silicon `beacon`/`beacon-hooks` package payload plus arch-matched
collector and Vector binaries for `darwin_arm64`, then signs, notarizes,
@@@ -296,43 -301,15 +307,51 @@@
appends the `.pkg`, `.msi` and `install.sh` to `checksums.txt` from the released bytes and
records a GitHub build-provenance attestation (Sigstore, keyless, through the
workflow's OIDC token) for every file `checksums.txt` lists. It needs
- `id-token: write` and `attestations: write` and no `release`-environment secrets.
+ `id-token: write` and `attestations: write`, and runs in the `release`
+ environment only so that, when `BEACON_LINUX_SIGNING_KEY` exists, it can sign
+ the extended `checksums.txt` again before uploading it; a failure before that
+ leaves GoReleaser's matching pair in place. GitHub replaces assets one at a time,
+ so it uploads `checksums.txt` then its `.sig`, reads both back and re-uploads
+ until the published pair is what it signed, and fails loudly otherwise;
+ `install.sh` and the self-updater fetch the pair once more before refusing a
+ signature that does not verify, which covers the seconds between the uploads.
+ Anything else that rewrites `checksums.txt` must come before that step.
+5. `apt-repository` (ubuntu, `needs: goreleaser`, `environment: release`,
+ `contents: read`/`attestations: read`) adds the released `.deb` files to the signed apt
+ repository
+ (`deb <APT_REPO_URL> stable main`) in an S3-compatible bucket, because 85-90 MB packages
+ outgrow a git-backed Pages repo. `packaging/linux/apt/build-apt-repo.sh` reads back only the
+ published index (InRelease, and each `Packages` through the by-hash path it names, so a
+ publish that stopped partway reads consistently and resumes), verifies it against the
+ committed public keys `packaging/linux/apt/beacon-archive-keyring.asc` before re-signing (so
+ an edited index is never re-signed), refuses to replace a published version, and fails unless
+ every key in the secret is a committed one and signed. Every `.deb` (this tag's and each
+ backfilled one) must pass `gh attestation verify --predicate-type` against the goreleaser
+ job's attestation of the bytes it built, from `release.yml` at `refs/tags/<tag>`. Never the
+ release's replaceable `checksums.txt`, and never finalize's provenance, which re-hashes those
+ same replaceable assets and whose job re-runs without approval. It is pinned
+ (`--source-digest`/`--signer-digest`) to the tag's commit, which must be an ancestor of this
+ run's commit: anyone who can push a `v*` tag can run their own `release.yml` and mint an
+ attestation for that path and ref, so only packages built from this release's history are
+ trusted (the checkout uses `fetch-depth: 0` for the check). Its control fields must name
+ `beacon`, the tag's version and the architecture; this tag's must pass, and a backfilled one
+ that fails (no attestation, or a tag outside the history) is left out with a warning. Rotating the
+ key is a reviewed commit in two steps: commit the new public key beside the old and put both
+ secret keys in `APT_GPG_PRIVATE_KEY`, so every release is signed by both and hosts that trust
+ only the old key keep updating while they fetch the new keyring; then remove the old key from
+ the file and the secret. Hosts install the keyring once and the package does not ship it, so
+ one that never refetches it breaks at step two. A published index counts as signed with at
+ least one good signature from a committed key and no bad one. First publish is decided by a `head-object` on
+ `dists/stable/InRelease` (404 only; any other error fails). Each run adds its own tag plus any
+ of the last `APT_BACKFILL_RELEASES` (10) stable releases up to it that the index lacks, because
+ the `apt-repository` concurrency group cancels a pending job when a third arrives; that also
+ repairs an index rolled back in the bucket within the window.
+ `verify-apt-repo.sh` runs a real, isolated `apt-get update`/`download` against the staged
+ tree (the index, then each staged package by its own version and architecture, since the
+ tree holds only what the run adds) and again against the public URL for the tag's version;
+ CI's `apt-repository` job runs `test-apt-repo.sh`.
+ Upload order is pool, index, then `Release.gpg`/`Release`/`InRelease` with `Acquire-By-Hash`.
+ Skipped with a notice until every `APT_*` setting exists, and for prerelease (`-`) tags.
Every third-party action in `release.yml`, `release-extension.yml` and
`npm-publish-sdk.yml` is pinned to a full commit SHA with the version in a
@@@ -345,9 -322,24 +364,27 @@@ Required `release`-environment secrets
`DEVELOPER_ID_INSTALLER_CERT_P12`, `DEVELOPER_ID_INSTALLER_CERT_PASSWORD`,
`NOTARY_API_KEY_P8`, `NOTARY_API_KEY_ID`, `NOTARY_API_ISSUER`; plus Variables
`DEVELOPER_ID_APP_IDENTITY`, `DEVELOPER_ID_INSTALLER_IDENTITY`, `APPLE_TEAM_ID`.
+The apt repository adds secrets `APT_GPG_PRIVATE_KEY` (armored, no passphrase; both keys during a rotation),
+`APT_S3_ACCESS_KEY_ID`, `APT_S3_SECRET_ACCESS_KEY` and Variables `APT_S3_BUCKET`,
+`APT_REPO_URL` (https), plus optional `APT_S3_ENDPOINT` (R2/GCS) and `APT_S3_REGION`.
+ Optional: `BEACON_LINUX_SIGNING_KEY` (ASCII-armored OpenPGP secret key) and
+ `BEACON_LINUX_SIGNING_KEY_PASSPHRASE`, which turn on Linux signing.
+
+ Linux signing is trusted only through the fingerprints, one per line, in
+ `cli/beacon/internal/endpoint/selfupdate/release-key.fingerprint`. The
+ self-updater embeds that file and the goreleaser before-hook stamps it into the
+ released `install.sh`, so pinning is a change to that file alone. Empty means
+ checksum-only, as before. Once set, `install.sh` and `beacon endpoint update
+ --apply` on Linux refuse a package unless a `checksums.txt` signed by a pinned
+ key lists it. Publish the fingerprint in `docs/platforms/linux.mdx#release-signing`.
+ To rotate, add the new fingerprint in a release still signed by the old key. Then
+ sign `checksums.txt` with both keys and ship both in `beacon-release-key.gpg` (the
+ GoReleaser `signs` entry and the `finalize` step sign with one key today, so extend
+ both first; `gpgv` and
+ `validSigFrom` accept either pinned key), and keep the old fingerprint pinned until
+ the fleet has moved. A host that skipped the transition pins only the old key, cannot
+ verify a new-key-only release, and must reinstall.
+
Keep one-time Apple-side onboarding steps out of the repo and share them with
the release maintainer directly. Never use `pull_request_target` or build
untrusted PR code in the signing job.