Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

Sign and notarize the macOS CLI in the release workflow (ADR 0210)

Rach Pradhan7ca2342826ad
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 3af1c096..c35869d3 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,8 +1,19 @@
name: release
-# Pushing a tag like v0.2.0 cross-compiles harness for the four desktop
-# targets and publishes a GitHub Release with tarballs + checksums. The
+# Pushing a tag like v0.2.0 cross-compiles harness for the six release
+# targets and publishes a draft GitHub Release with tarballs + checksums. The
# version baked into `--version` comes from the tag via -Dversion.
+#
+# The two macOS CLI binaries are Developer ID signed and notarized on a macOS
+# runner BEFORE anything is uploaded (ADR 0210), so the release only ever
+# receives final bytes and SHA256SUMS is computed once from them. That needs
+# all five repository secrets:
+# MACOS_CERT_P12 / MACOS_CERT_PASSWORD - base64 "Developer ID Application"
+# certificate + private key (.p12) and its export password.
+# AC_API_KEY_P8 / AC_API_KEY_ID / AC_API_ISSUER_ID - App Store Connect API
+# key (raw .p8 contents) for notarytool.
+# Without them the signing job succeeds as a no-op, the release carries the
+# unsigned macOS tarballs, and docs/notarization.md is the manual fallback.
on:
push:
tags: ["v*", "!v*-*"]
@@ -11,7 +22,7 @@ permissions:
contents: write
jobs:
- release:
+ build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
@@ -43,7 +54,189 @@ jobs:
tar -czf "$name.tar.gz" "$name"
rm -r "$name"
done
+
+ - uses: actions/upload-artifact@v7
+ with:
+ name: cli-tarballs
+ path: graff-*.tar.gz
+ if-no-files-found: error
+
+ # Sign + notarize the macOS CLI binaries, exactly as docs/notarization.md
+ # does by hand. No-op (success) unless all five secrets are configured.
+ macos-sign:
+ needs: build
+ runs-on: macos-latest
+ timeout-minutes: 60
+ outputs:
+ signed: ${{ steps.signing.outputs.enabled }}
+ steps:
+ - name: Select signed distribution path
+ id: signing
+ env:
+ MACOS_CERT_P12: ${{ secrets.MACOS_CERT_P12 }}
+ MACOS_CERT_PASSWORD: ${{ secrets.MACOS_CERT_PASSWORD }}
+ AC_API_KEY_P8: ${{ secrets.AC_API_KEY_P8 }}
+ AC_API_KEY_ID: ${{ secrets.AC_API_KEY_ID }}
+ AC_API_ISSUER_ID: ${{ secrets.AC_API_ISSUER_ID }}
+ run: |
+ if [[ -n "$MACOS_CERT_P12" && -n "$MACOS_CERT_PASSWORD" && \
+ -n "$AC_API_KEY_P8" && -n "$AC_API_KEY_ID" && \
+ -n "$AC_API_ISSUER_ID" ]]; then
+ echo 'enabled=true' >> "$GITHUB_OUTPUT"
+ else
+ echo 'enabled=false' >> "$GITHUB_OUTPUT"
+ msg='macOS signing secrets are not all set; the release keeps the unsigned macOS tarballs. Sign them by hand per docs/notarization.md.'
+ echo "::notice::$msg"
+ echo "$msg" >> "$GITHUB_STEP_SUMMARY"
+ fi
+
+ - uses: actions/download-artifact@v7
+ if: steps.signing.outputs.enabled == 'true'
+ with:
+ name: cli-tarballs
+ path: dist
+
+ - name: Import Developer ID certificate
+ if: steps.signing.outputs.enabled == 'true'
+ env:
+ MACOS_CERT_P12: ${{ secrets.MACOS_CERT_P12 }}
+ MACOS_CERT_PASSWORD: ${{ secrets.MACOS_CERT_PASSWORD }}
+ run: |
+ set -euo pipefail
+ keychain="$RUNNER_TEMP/release.keychain-db"
+ pass="$(openssl rand -hex 16)"
+ security create-keychain -p "$pass" "$keychain"
+ security set-keychain-settings -lut 3600 "$keychain"
+ security unlock-keychain -p "$pass" "$keychain"
+ printf '%s' "$MACOS_CERT_P12" | base64 -d >"$RUNNER_TEMP/cert.p12"
+ security import "$RUNNER_TEMP/cert.p12" -k "$keychain" \
+ -P "$MACOS_CERT_PASSWORD" -T /usr/bin/codesign
+ rm -f "$RUNNER_TEMP/cert.p12"
+ # Allow codesign to use the imported key without a UI prompt.
+ security set-key-partition-list -S apple-tool:,apple: \
+ -s -k "$pass" "$keychain" >/dev/null
+ security list-keychains -d user -s "$keychain" login.keychain-db
+ identity="$(security find-identity -v -p codesigning "$keychain" \
+ | sed -n 's/.*"\(Developer ID Application: [^"]*\)".*/\1/p' | head -1)"
+ [ -n "$identity" ] || { echo "p12 contains no Developer ID Application identity" >&2; exit 1; }
+ echo "Signing as: $identity"
+ echo "CODESIGN_IDENTITY=$identity" >>"$GITHUB_ENV"
+
+ - name: Sign and notarize the macOS CLI
+ if: steps.signing.outputs.enabled == 'true'
+ env:
+ AC_API_KEY_P8: ${{ secrets.AC_API_KEY_P8 }}
+ AC_API_KEY_ID: ${{ secrets.AC_API_KEY_ID }}
+ AC_API_ISSUER_ID: ${{ secrets.AC_API_ISSUER_ID }}
+ run: |
+ set -euo pipefail
+ # No AppleDouble (._*) members when re-tarring on macOS.
+ export COPYFILE_DISABLE=1
+ key="$RUNNER_TEMP/ac_api_key.p8"
+ printf '%s' "$AC_API_KEY_P8" >"$key"
+ notary=(--key "$key" --key-id "$AC_API_KEY_ID" --issuer "$AC_API_ISSUER_ID")
+ work="$RUNNER_TEMP/notarize"
+ mkdir -p "$work" signed
+ for target in aarch64-macos x86_64-macos; do
+ name="graff-$target"
+ case "$target" in aarch64-*) arch=arm64 ;; *) arch=x86_64 ;; esac
+ tar -xzf "dist/$name.tar.gz" -C "$work"
+ bin="$work/$name/graff"
+ [ "$(lipo -archs "$bin")" = "$arch" ] || { echo "$name: expected $arch, got $(lipo -archs "$bin")" >&2; exit 1; }
+ xattr -cr "$work/$name"
+ # Hardened runtime + secure timestamp are required by the notary service.
+ codesign --force --options runtime --timestamp --sign "$CODESIGN_IDENTITY" "$bin"
+ codesign --verify --strict --verbose=2 "$bin"
+
+ # ditto, not zip: keep the signed bytes and metadata exact.
+ ditto -c -k --keepParent "$work/$name" "$work/$name.notarize.zip"
+ # notarytool exits 0 even when the submission is Invalid, so the
+ # status field is the gate, not the exit code.
+ xcrun notarytool submit "$work/$name.notarize.zip" "${notary[@]}" \
+ --wait --timeout 30m --output-format json >"$work/$name.notary.json"
+ id="$(plutil -extract id raw -o - "$work/$name.notary.json")"
+ status="$(plutil -extract status raw -o - "$work/$name.notary.json")"
+ echo "$name: notarization $id -> $status"
+ echo "- \`$name\`: notarization \`$id\` $status" >>"$GITHUB_STEP_SUMMARY"
+ if [ "$status" != Accepted ]; then
+ xcrun notarytool log "$id" "${notary[@]}" || true
+ echo "$name: notarization was not Accepted; refusing to ship a signed but unnotarized binary" >&2
+ exit 1
+ fi
+ # Bare CLIs cannot be stapled (stapler error 73); the ticket is
+ # bound to the cdhash and checked online. Ship the accepted bytes.
+ (cd "$work" && tar -czf "$GITHUB_WORKSPACE/signed/$name.tar.gz" "$name")
+ done
+ rm -f "$key"
+
+ - name: Verify like a user
+ if: steps.signing.outputs.enabled == 'true'
+ run: |
+ set -euo pipefail
+ check="$(mktemp -d)"
+ for target in aarch64-macos x86_64-macos; do
+ name="graff-$target"
+ # Same member layout as the Linux-built tarball, no AppleDouble files.
+ members="$(tar -tzf "signed/$name.tar.gz" | sed 's:/$::' | LC_ALL=C sort | tr '\n' ' ')"
+ [ "$members" = "$name $name/LICENSE $name/README.md $name/graff " ] \
+ || { echo "$name: unexpected tarball members: $members" >&2; exit 1; }
+ tar -xzf "signed/$name.tar.gz" -C "$check"
+ codesign --verify --strict "$check/$name/graff"
+ info="$(codesign -dv --verbose=2 "$check/$name/graff" 2>&1)"
+ grep -q 'Authority=Developer ID Application' <<<"$info"
+ grep -q 'flags=.*runtime' <<<"$info"
+ done
+ shasum -a 256 signed/*.tar.gz
+
+ - uses: actions/upload-artifact@v7
+ if: steps.signing.outputs.enabled == 'true'
+ with:
+ name: cli-macos-signed
+ path: signed/*.tar.gz
+ if-no-files-found: error
+
+ - name: Remove signing keychain
+ if: always() && steps.signing.outputs.enabled == 'true'
+ run: |
+ security delete-keychain "$RUNNER_TEMP/release.keychain-db" 2>/dev/null || true
+ rm -f "$RUNNER_TEMP/cert.p12" "$RUNNER_TEMP/ac_api_key.p8"
+
+ release:
+ needs: [build, macos-sign]
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+
+ - uses: actions/download-artifact@v7
+ with:
+ name: cli-tarballs
+ path: .
+
+ - uses: actions/download-artifact@v7
+ if: needs.macos-sign.outputs.signed == 'true'
+ with:
+ name: cli-macos-signed
+ path: signed-macos
+
+ - name: Assemble final assets and checksums
+ env:
+ SIGNED: ${{ needs.macos-sign.outputs.signed }}
+ run: |
+ set -euo pipefail
+ if [ "$SIGNED" = true ]; then
+ for target in aarch64-macos x86_64-macos; do
+ mv -f "signed-macos/graff-$target.tar.gz" "graff-$target.tar.gz"
+ done
+ echo 'macOS CLI tarballs: Developer ID signed and notarized in CI.' >>"$GITHUB_STEP_SUMMARY"
+ else
+ echo 'macOS CLI tarballs: UNSIGNED. Finish them with docs/notarization.md before publishing.' >>"$GITHUB_STEP_SUMMARY"
+ fi
+ for target in aarch64-macos x86_64-macos x86_64-linux aarch64-linux x86_64-windows aarch64-windows; do
+ test -f "graff-$target.tar.gz" || { echo "missing graff-$target.tar.gz" >&2; exit 1; }
+ done
+ # Computed once, from the exact bytes being uploaded.
sha256sum graff-*.tar.gz > SHA256SUMS
+ cat SHA256SUMS
- name: Create GitHub release
env:
@@ -82,9 +275,10 @@ jobs:
}
done
- # Linux desktop package. macOS stays a notarized upload from a Mac
- # (publish-updates.sh). This runner can build the unsigned .deb the
- # packager already writes; signing is not a gate (ADR 0157).
+ # Linux desktop package. The macOS desktop app stays a notarized upload
+ # from a configured Mac (distribute.sh + publish-updates.sh, ADR 0210).
+ # This runner can build the unsigned .deb the packager already writes;
+ # signing is not a gate (ADR 0157).
desktop-linux:
needs: release
runs-on: ubuntu-latest
diff --git a/docs/adr/0210-macos-cli-is-signed-in-ci-before-upload.md b/docs/adr/0210-macos-cli-is-signed-in-ci-before-upload.md
new file mode 100644
index 00000000..c0b37953
--- /dev/null
+++ b/docs/adr/0210-macos-cli-is-signed-in-ci-before-upload.md
@@ -0,0 +1,41 @@
+# 0210. The macOS CLI is signed and notarized in CI before upload
+
+Status: accepted 2026-09-28
+
+## Context
+
+Tag releases built every CLI tarball on Linux and uploaded them to a draft.
+The macOS halves were then signed and notarized by hand on a configured Mac
+(docs/notarization.md), which re-uploaded the tarballs and a hand-edited
+`SHA256SUMS` over the originals. That replace step is not atomic: a
+maintainer can publish in the middle of it, and the workflow also attaches to
+a release that was already published. Either way users could download an
+unsigned binary, or a signed one whose checksum line is still the old one.
+
+## Decision
+
+- `release.yml` is `build` → `macos-sign` → `release` → `desktop-linux`.
+ `macos-sign` runs on a macOS runner and signs each bare `graff` with the
+ Developer ID Application identity (hardened runtime, secure timestamp),
+ notarizes it with an App Store Connect API key, and fails unless the
+ notarytool status is `Accepted`. Bare CLIs are not stapled.
+- It runs only when `MACOS_CERT_P12`, `MACOS_CERT_PASSWORD`, `AC_API_KEY_P8`,
+ `AC_API_KEY_ID` and `AC_API_ISSUER_ID` are all set. Otherwise it succeeds
+ as a no-op, the release carries the unsigned macOS tarballs, and the
+ manual runbook remains the path.
+- Nothing is uploaded until signing is done. `SHA256SUMS` is computed once in
+ `release` from the bytes being uploaded; CI never edits it afterwards.
+- The macOS desktop app stays on `distribute.sh` + `publish-updates.sh` from a
+ configured Mac (ADR 0079, 0157). CI does not build it for release: DMG
+ layout drives Finder via AppleScript, `distribute.sh` takes a notarytool
+ keychain profile, the optional passkey provisioning profile is a local
+ file, and the update assets must reach the draft together.
+
+## Consequences
+
+A tag with the secrets produces a draft whose macOS tarballs are already
+notarized; do not re-sign them by hand, since that changes the bytes Apple
+scanned. A notarization failure blocks the whole draft, Linux and Windows
+included, until the failed jobs are re-run. Every release now also waits for
+a macOS runner, even when it only no-ops. Beta prereleases still ship an
+unsigned macOS CLI; revisit if they should share this job.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 4f1b322f..48b477c5 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -236,6 +236,7 @@ record only when you need the evidence or the edge cases.
| [0207](0207-jev-file-retrieval-is-not-economical.md) | Rejected: no Jev file retrieval (`locate` tool, Jev rerank after `codedb context`, or jevgrep). A full Jev scan found answer files best (80% in top 5 vs 38% for `codedb context`) but costs one request per file and grows with repo size; `codedb` stays the retrieval path. |
| [0208](0208-hot-context-keyed-updates-keep-the-prefix.md) | A mid-session instruction-file edit or date rollover is appended before the next prompt as a keyed `<context>` message (developer role on Responses, system on Chat Completions, user elsewhere), and the system prompt is left as is. Compaction drops those messages and folds the latest values into the new system prompt. |
| [0209](0209-desktop-app-has-no-computer-use.md) | The desktop app has no computer use: the `computer` tool, endpoint and menu toggle are removed; the native input bridge remains a test-only driver. Supersedes the `computer` half of 0071. |
+| [0210](0210-macos-cli-is-signed-in-ci-before-upload.md) | Tag releases sign and notarize the macOS CLI tarballs on a macOS runner before anything is uploaded, gated on all five signing secrets; without them the job no-ops and docs/notarization.md is the fallback. `SHA256SUMS` is computed once from the uploaded bytes. The desktop DMG stays a local `distribute.sh` step. |
## When to write one
diff --git a/docs/notarization.md b/docs/notarization.md
index 688024c7..5af15077 100644
--- a/docs/notarization.md
+++ b/docs/notarization.md
@@ -1,21 +1,63 @@
-# Notarizing a macOS release — the working runbook
+# Notarizing a macOS release
-This is the exact procedure used for v0.0.273 and v0.0.274, end to end.
-It exists because half of these steps are machine-local (a keychain
-profile, a Developer ID identity) and the other half are ordering rules
-that are easy to get subtly wrong. Follow it top to bottom.
+The macOS CLI tarballs are signed and notarized in CI when the signing
+secrets are configured (ADR 0210). The manual runbook below is the fallback:
+it was the exact procedure used for v0.0.273 and v0.0.274, and it is still
+the path whenever CI ran without the secrets. Half of its steps are
+machine-local (a keychain profile, a Developer ID identity) and the other
+half are ordering rules that are easy to get subtly wrong.
## What signs what
| Artifact | Signed by | Where |
|---|---|---|
| Linux / Windows tarballs | nobody | CI (`release.yml`) builds and uploads them |
-| macOS tarballs | Developer ID Application, then Apple notarized | **locally**, after CI's draft exists |
-
-CI cannot sign: the signing identity is not on GitHub runners. So every
-release ships unsigned from CI and gets its macOS halves finished by hand.
-
-## Prerequisites (one-time, this machine)
+| macOS CLI tarballs | Developer ID Application, then Apple notarized | CI `macos-sign` job when the secrets exist; otherwise **locally**, after CI's draft exists |
+| macOS desktop app (DMG + update ZIP) | Developer ID Application, then Apple notarized and stapled | **locally**: `distribute.sh` + `publish-updates.sh` (see `apps/native/electron/README.md`) |
+
+## The CI path
+
+`release.yml` runs `build` (cross-compile on Linux) → `macos-sign` (macOS
+runner) → `release` (checksums + draft) → `desktop-linux`. Nothing is uploaded
+until `macos-sign` has finished, so a release never holds unsigned macOS
+tarballs next to signed ones, and `SHA256SUMS` is computed once from the
+exact bytes that are uploaded. There is no replace-in-place step to race a
+maintainer who publishes early.
+
+`macos-sign` needs all five repository secrets:
+
+| Secret | Contents |
+|---|---|
+| `MACOS_CERT_P12` | base64 of a `.p12` holding only the Developer ID Application certificate and its private key |
+| `MACOS_CERT_PASSWORD` | the `.p12` export password |
+| `AC_API_KEY_P8` | raw contents of the App Store Connect API key (`AuthKey_<KEYID>.p8`) |
+| `AC_API_KEY_ID` | that key's id |
+| `AC_API_ISSUER_ID` | the App Store Connect issuer UUID |
+
+With all five, the job does steps 1 to 4 below on the runner: imports the
+certificate into a temporary keychain, signs each bare `graff` with
+`--options runtime --timestamp`, submits a `ditto` zip with
+`notarytool --key/--key-id/--issuer --wait`, and **fails unless the JSON
+status is `Accepted`** (notarytool exits 0 on `Invalid`; the job prints the
+notary log instead). It skips stapling (step 3), re-tars with the original
+`graff-<target>/` layout, checks the members, signature, Developer ID
+authority and hardened runtime from the new tarball, and hands the tarballs to
+`release`. The submission ids are in the job summary.
+
+If any secret is missing, `macos-sign` logs a notice and succeeds without
+doing anything; the draft gets the unsigned macOS tarballs and the job
+summary says so. Finish that release with the manual runbook.
+
+If notarization fails with the secrets present, the release job does not run
+and no draft is created. Fix the cause and re-run the failed jobs; do not
+ship a signed but unnotarized binary (`install.sh` notes that hardened runtime
+without notarization gets SIGKILLed on Apple silicon).
+
+Do not run the manual runbook on a release CI already signed: re-signing
+changes the bytes Apple scanned. Step 5 (verify like a user) applies to
+either path.
+
+## Manual runbook: prerequisites (one-time, this machine)
1. **Developer ID Application certificate** in the login keychain:
```bash
@@ -37,7 +79,7 @@ release ships unsigned from CI and gets its macOS halves finished by hand.
lost (keychain reset / new machine) and must be re-stored — see the
v0.0.273 session, where `codedb-notary`/`codedb-local` had both vanished.
-## Per-release procedure
+## Manual runbook: per-release procedure
```bash
VER=v0.0.274 # tag already pushed; release.yml has run green