Files
PaperClipAI/.github/workflows/docker.yml
T
DottaandClaude Opus 5.5 d16c06308d perf(release): number canaries by master position and confirm them outside the release lock (#21917)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Every master push runs a canary, and only one canary at a time may
run the release workflow
> - After #21554 and #21555 a canary held that lock for 35.5 min, and
13-16 min of it was waiting for npm to show the new packages
> - The wait was required: the next canary computed `canary.N` from
npm's version list, so starting before npm showed the previous canary
would reuse its number
> - This pull request numbers a canary by its commit's position on
master and moves the registry confirmation, the git tag, the Docker
dispatch and the onboarding smoke to a separate `canary-finalize.yml`
run
> - The benefit is that the release lock is held for about 20-25 min per
canary instead of 35, with the same checks before a canary is tagged

## Linked Issues or Issue Description

**What existing behavior does this improve?**
Canary throughput. In run 43715037497 (2026-11-15) `publish_canary` took
23.7 min, and 13.3 min of that was "Waiting for registry visibility"
(13:08:50 to 13:22:11). The next canary could not start until that run
ended.

**Current behavior**
`release.sh canary` sets `N` to (highest published `-canary.N` for
today) + 1, then publishes, waits for npm to show every package, checks
dist-tags, installs `paperclipai@canary`, and creates
`canary/v<version>`. `publish_canary` pushes the tag, dispatches
`docker.yml`, and `smoke_canary_onboarding` runs in the same run.

**Proposed behavior**
`N` = `git rev-list --count HEAD` (full history required), or the
registry number + 1 when that is higher (a rerun of the same commit).
`release.sh canary --defer-registry-confirmation` ends after npm accepts
every publish. `publish_canary` dispatches `canary-finalize.yml`, which
does the confirmation, tag, Docker dispatch and smoke outside the
release lock. Nightly, beta and stable numbering and flow are unchanged.

Refs #21554, #21555

## What Changed

- `scripts/release-lib.sh`: `next_canary_version_from_source`. A
publishing canary refuses a shallow checkout; a dry run (the PR Canary
Dry Run job) falls back to the registry number.
- `scripts/release.sh`: canary uses the new number; new canary-only
`--defer-registry-confirmation` flag skips the registry wait, the
dist-tag check and the local tag, and writes the version to
`PAPERCLIP_RELEASE_VERSION_FILE`.
- `scripts/confirm-canary-publication.sh` (new): waits for registry
visibility, checks provenance, checks dist-tags with
`--allow-newer-canary`, installs `paperclipai@<version>`, then creates
and pushes `canary/v<version>`. A tag already on the same commit is
accepted, so reruns are safe.
- `scripts/verify-canary-provenance.mjs` (new): every package's npm SLSA
provenance must name `.github/workflows/release.yml` on
`refs/heads/master` in `paperclipai/paperclip` at the source commit. A
dispatch with invented inputs cannot tag anything.
- `scripts/verify-release-registry-state.mjs`: `--allow-newer-canary`
accepts a `canary` dist-tag that a newer canary already moved; older,
foreign or missing tags still fail.
- `.github/workflows/canary-finalize.yml` (new, `workflow_dispatch`,
master only): `confirm_canary` (contents: write, actions: write) and
`smoke_canary_onboarding` (downloads the publisher's lockfile artifact
by run id). Inputs reach shell steps only through a validating step.
- `.github/workflows/release.yml`: `publish_canary` hands off to
`canary-finalize.yml` and drops to `contents: read`; its tag push,
Docker dispatch and smoke job move to `canary-finalize.yml`.
- Tests and `doc/RELEASING.md`.

## Verification

- `node --test .github/scripts/tests/*.test.mjs
scripts/release-lib.test.mjs
scripts/verify-release-registry-state.test.mjs
scripts/verify-canary-provenance.test.mjs`: 846 pass.
`scripts/__tests__/release-verify-workflow.test.mjs`: 73 pass.
- New tests: numbering by master position, rerun moves past a published
number, shallow refusal and dry-run fallback; newer/older/foreign
dist-tags; provenance from another commit, workflow, branch, repository
or package is rejected; finalize wiring, permissions and input handling.
- Real npm data: `verify-canary-provenance.mjs 2026.1116.0-canary.7
b4fa1c7f... paperclipai @paperclipai/shared @paperclipai/server` passes;
the same version with another commit fails.
- `confirm-canary-publication.sh 2026.1116.0-canary.7 b4fa1c7f...` from
a checkout of that commit ran all steps against npm in 61 s and ended
with "canary/v2026.1116.0-canary.7 already points at b4fa1c7f...",
pushing nothing.
- `release.sh canary --dry-run --defer-registry-confirmation` and
`release.sh nightly --defer-registry-confirmation` both stop with "only
applies to a published canary".
- `actionlint` reports no new findings compared with master.
- Not verified before merge: a full publish through
`canary-finalize.yml`. It can run only from master. The first canary
after merge is the check.

## Risks

- Canary numbers jump from `canary.7` to about `canary.8144` (master has
8,143 commits). This is valid semver and still higher than every earlier
canary; users install through the `canary` dist-tag.
- The `canary/v` tag, Docker image and smoke now finish after the
release run ends. Nightly selects only tagged canaries, as before. If
finalize fails, that canary is on npm without a tag, so nightly skips
it, as it skips any canary whose old in-run verification failed.
- A canary can now publish while the previous one is still being
confirmed. Publishing itself is still serialized, so the `canary`
dist-tag only moves forward.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, in Claude Code with
tool use and code execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 11:37:20 -06:00

725 lines
35 KiB
YAML

name: Docker
on:
push:
branches:
- "master"
tags:
- "v*"
- "nightly/v*"
- "beta/v*"
# Release workflows push lane tags with GITHUB_TOKEN, and GitHub suppresses
# push-triggered runs for those, so release.yml (canary-finalize.yml for a
# canary) dispatches this workflow at the new tag ref instead. The tag mapping below keys off github.ref either
# way.
workflow_dispatch:
# Least privilege: nothing at the workflow level; each job declares exactly
# the token scopes it uses (checkout needs contents:read, GHCR pushes need
# packages:write).
permissions: {}
# Serialise builds per ref without killing an in-flight one: a newer push
# supersedes only the pending slot, so the image build that is already
# running always finishes and publishes. Canary TAG refs each get their
# own group on purpose: their builds run in parallel so every published
# canary gets its sha images regardless of merge cadence. The mutable
# `:canary` channel tags are NOT written by the build matrix (which
# would race across parallel runs) — each canary-tag run retags the
# channel afterwards, only if it still matches the npm `canary`
# dist-tag, so the channel moves monotonically and always mirrors npm.
concurrency:
group: docker-${{ github.ref }}
cancel-in-progress: false
jobs:
runner_image:
name: Resolve the Runner image of this commit
if: vars.RUNNER_IMAGE_CONSUME_ENABLED == 'true' && github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064'
continue-on-error: true
runs-on: ubuntu-latest
timeout-minutes: 70
permissions:
contents: read
actions: read
attestations: read
outputs:
mode: ${{ steps.verify.outputs.mode || 'inline' }}
build_contexts: ${{ steps.verify.outputs.build_contexts }}
labels: ${{ steps.verify.outputs.labels }}
build_args: ${{ steps.verify.outputs.build_args }}
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
persist-credentials: false
- name: Setup pnpm
uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
with:
version: 9.15.4
run_install: false
- name: Setup Node.js
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
with:
node-version: 24
package-manager-cache: false
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4
with:
buildkitd-config-inline: |
[registry."docker.io"]
mirrors = ["mirror.gcr.io"]
- name: Compute the Runner inputs of this commit
timeout-minutes: 5
run: node scripts/runner-image-resolve.mjs inputs --dir "$RUNNER_TEMP/runner-image-resolve"
- name: Find the published Runner image of these inputs
id: resolve
timeout-minutes: 55
env:
WAIT: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
GITHUB_TOKEN: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' && github.token || '' }}
run: |
set -euo pipefail
if [ "$WAIT" = true ]; then
node scripts/runner-image-resolve.mjs resolve --dir "$RUNNER_TEMP/runner-image-resolve" --wait
else
node scripts/runner-image-resolve.mjs resolve --dir "$RUNNER_TEMP/runner-image-resolve"
fi
- name: Verify the attestation of the Runner image
id: verify
if: steps.resolve.outputs.mode == 'published'
timeout-minutes: 5
env:
GH_TOKEN: ${{ github.token }}
IMAGE: ${{ steps.resolve.outputs.image }}
LABELS: ${{ steps.resolve.outputs.labels }}
BUILD_ARGS: ${{ steps.resolve.outputs.build_args }}
run: |
set -euo pipefail
if ! gh attestation verify "oci://$IMAGE" \
--repo paperclipai/paperclip \
--signer-workflow paperclipai/paperclip/.github/workflows/runner-image.yml \
--source-ref refs/heads/master; then
echo "::warning title=Runner image not verified::The attestation of $IMAGE did not verify. The image build makes its own Runner."
echo "The attestation of \`$IMAGE\` did not verify: the image build makes its own Runner." >> "$GITHUB_STEP_SUMMARY"
exit 1
fi
{
echo "mode=published"
echo "build_contexts=runner-artifacts=docker-image://$IMAGE"
echo "build_args=$BUILD_ARGS"
echo "labels<<runner-image-labels-end"
echo "$LABELS"
echo "runner-image-labels-end"
} >> "$GITHUB_OUTPUT"
echo "The attestation of \`$IMAGE\` verified: the image build copies this Runner." >> "$GITHUB_STEP_SUMMARY"
source_verification:
name: Watch exact-source verification
if: github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064' && github.ref == 'refs/heads/master'
runs-on: ${{ vars.AWS_POST_MERGE_CI_ENABLED == 'true' && github.run_attempt >= 1 && github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064' && github.ref == 'refs/heads/master' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && 'runs-on/fleet=paperclip-post-merge-x64/env=public-ci' || 'ubuntu-latest' }}
timeout-minutes: 44
permissions:
contents: read
actions: write
checks: read # runner-loss evidence (annotations) for readiness retries
outputs:
verified: ${{ steps.watch.outputs.verified }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
with:
node-version: 24
- name: Stop images when source checks fail and report runner waits
id: watch
env:
GITHUB_TOKEN: ${{ github.token }}
run: node scripts/watch-release-source.mjs
reuse_canary_image:
if: github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064' && startsWith(github.ref, 'refs/tags/canary/v')
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: read
packages: write
attestations: read
outputs:
reused: ${{ steps.reuse.outputs.reused }}
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
- name: Setup Node.js
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
with:
node-version: 24
- name: Login to GitHub Container Registry
uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Reuse the verified master image when present
id: reuse
env:
GH_TOKEN: ${{ github.token }}
run: node scripts/reuse-canary-image.mjs
# Multi-arch by native runner, not QEMU.
#
# This was one job building linux/amd64,linux/arm64 together on an x86
# runner. The arm64 half is emulated there, and it did not merely run slow:
# it wedged, every time, in `RUN pnpm --filter @paperclipai/server build`,
# emitting nothing for 38-45 minutes until `timeout-minutes: 60` killed the
# job. Verified across three consecutive runs on 2026-09-04; the amd64 half
# reached `production 5/5` minutes earlier in every one.
#
# A timed-out job is reported as *cancelled*, not failed, so the run read
# "cancelled" and the production image simply stopped publishing without
# anything going red in an obvious way.
#
# It also starved the queue. A run that burns the full hour holds the
# top-level concurrency slot for that hour, and `cancel-in-progress: false`
# keeps exactly one pending slot — so with merges arriving faster than one
# an hour, most runs were superseded before they ever started a job. Five of
# ten master commits sampled that day never produced an image at all.
#
# Each platform now builds on a runner of its own architecture and pushes by
# digest; `merge` assembles the manifest list. Both architectures remain
# available to self-hosted installations and downstream image composers.
build-and-push:
needs: [reuse_canary_image, runner_image]
if: ${{ !cancelled() && (needs.reuse_canary_image.result == 'skipped' || (needs.reuse_canary_image.result == 'success' && needs.reuse_canary_image.outputs.reused == 'false')) }}
strategy:
# Independent legs: one architecture failing should still publish
# nothing, but it must not also hide the other's logs behind a
# cancellation.
fail-fast: false
matrix:
include:
- platform: linux/amd64
runner: ubuntu-latest
arch: amd64
- platform: linux/arm64
runner: ubuntu-24.04-arm
arch: arm64
runs-on: ${{ vars.CORE_RELEASE_AWS_ENABLED == 'true' && github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064' && github.ref == 'refs/heads/master' && format('runs-on/fleet=paperclip-core-image-{0}/env=public-ci', matrix.arch == 'amd64' && 'x64' || 'arm64') || matrix.runner }}
# Stop before the AWS worker's 45-minute maximum lifetime. Hosted tag
# builds retain their existing limit.
timeout-minutes: ${{ vars.CORE_RELEASE_AWS_ENABLED == 'true' && github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064' && github.ref == 'refs/heads/master' && 40 || 60 }}
permissions:
contents: read
packages: write
actions: read # download a verified merge-queue image artifact of this commit
steps:
- name: Checkout
uses: actions/checkout@v7
with:
# Full history and tags so `git describe` below can compute the
# release version to stamp into the image.
fetch-depth: 0
# Keep the version's full commit graph without downloading blobs
# from every historical revision of this large repository.
filter: blob:none
# `.git` is dockerignored, so a running image cannot derive its own
# version and otherwise reports the source package.json placeholder in
# analytics and the debug panel. Compute it here from the pristine
# checkout (real CalVer drift from the nearest release tag) and pass it
# into both builds. Empty when no release tag is reachable — the server
# then keeps its existing fallbacks.
- name: Compute build version
id: build-version
run: |
set -euo pipefail
case "${GITHUB_REF}" in
refs/tags/nightly/v*)
# Lane tags carry the exact published version; stamp it verbatim
# instead of describing drift from the nearest stable tag.
version="${GITHUB_REF#refs/tags/nightly/v}"
;;
refs/tags/beta/v*)
version="${GITHUB_REF#refs/tags/beta/v}"
;;
*)
version="$(git describe --tags --match 'v*' --long --dirty 2>/dev/null || true)"
;;
esac
echo "version=${version}" >> "$GITHUB_OUTPUT"
echo "Stamping build version: ${version:-<none>}"
# ISO week stamp for the Dockerfile's tool layer: the layer caches
# across commits and re-pulls the @latest CLI tools when the week rolls
# over, instead of on every build.
- name: Compute tool cache epoch
id: tools-epoch
run: echo "epoch=$(date -u +%G-W%V)" >> "$GITHUB_OUTPUT"
- name: Setup pnpm
uses: pnpm/action-setup@v6
with:
version: 9.15.4
run_install: false
# No dependency cache here: this workflow publishes release images, and
# restoring a shared Actions cache into the build inputs would let a
# poisoned cache entry reach the published artifact.
- name: Setup Node.js
uses: actions/setup-node@v7
with:
node-version: 24
- name: Refresh lockfile for Docker build context
if: needs.runner_image.outputs.mode != 'published'
run: |
set -euo pipefail
pnpm install --resolution-only --ignore-scripts --no-frozen-lockfile
changed="$(git status --porcelain)"
if [ -z "$changed" ]; then
echo "Lockfile already matches package metadata."
exit 0
fi
if printf '%s\n' "$changed" | grep -Fvq ' pnpm-lock.yaml'; then
echo "Unexpected files changed during lockfile refresh:"
echo "$changed"
exit 1
fi
echo "Using refreshed pnpm-lock.yaml in the Docker build context."
- name: Free runner disk
if: ${{ !(vars.CORE_RELEASE_AWS_ENABLED == 'true' && github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064' && github.ref == 'refs/heads/master') }}
run: |
set -euo pipefail
echo "Disk before cleanup:"
df -h
pnpm store prune || true
sudo apt-get clean || true
sudo rm -rf \
/usr/share/dotnet \
/usr/share/swift \
/usr/local/lib/android \
/usr/local/share/boost \
/usr/local/share/powershell \
/opt/ghc \
/opt/hostedtoolcache/CodeQL \
/opt/hostedtoolcache/PyPy \
/opt/hostedtoolcache/Ruby || true
docker system prune -af || true
echo "Disk after cleanup:"
df -h
- name: Login to GitHub Container Registry
uses: docker/login-action@v4
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
password: ${{ secrets.GITHUB_TOKEN }}
# Build-before-merge. When the merge queue already built and probed this
# exact commit (docker-merge-group.yml, with no registry credentials),
# push those bytes, unless a published Runner image is used. The script
# requires a successful merge-group run of this repository for this SHA
# and checks the record's commit, tree, architecture and archive digest.
# Any missing or mismatched proof, or any failure here, leaves
# `steps.promote.outputs.digest` empty and the build below runs as
# before. The probe below and the exact-source gate apply either way.
- name: Find the merge-queue build of this commit
id: find
if: needs.runner_image.outputs.mode != 'published' && github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064' && github.event_name == 'push' && github.ref == 'refs/heads/master'
continue-on-error: true
env:
GITHUB_TOKEN: ${{ github.token }}
BEFORE: ${{ github.event.before }}
ARCH: ${{ matrix.arch }}
# Master's copy from before this push selects the run; see the promote
# step below.
run: |
set -euo pipefail
trusted="$RUNNER_TEMP/merge-group-image-trusted.mjs"
git show "$BEFORE:scripts/merge-group-image.mjs" > "$trusted"
node "$trusted" find --arch "$ARCH"
- name: Download the merge-queue image
if: steps.find.outputs.run_id != ''
continue-on-error: true
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
with:
name: merge-group-image-${{ matrix.arch }}
run-id: ${{ steps.find.outputs.run_id }}
github-token: ${{ github.token }}
path: ${{ runner.temp }}/merge-group-image
- name: Promote the merge-queue image
id: promote
if: steps.find.outputs.run_id != ''
continue-on-error: true
env:
ARCH: ${{ matrix.arch }}
DIRECTORY: ${{ runner.temp }}/merge-group-image
IMAGE_NAME: ghcr.io/${{ github.repository }}
BEFORE: ${{ github.event.before }}
run: |
set -euo pipefail
# Say plainly when this runner image cannot promote, instead of
# failing later inside the copy.
if ! command -v skopeo >/dev/null; then
echo "::notice title=Merge-queue promotion unavailable::skopeo is not installed on this runner; building from source."
exit 1
fi
echo "Promoting with $(skopeo --version)"
# Run the verifier as master had it before this push, not the copy
# this push brings, so a push cannot weaken the check it must pass.
# The verifier refuses any push that changes the pipeline since
# BEFORE. A push whose BEFORE has no verifier builds from source.
trusted="$RUNNER_TEMP/merge-group-image-trusted.mjs"
git show "$BEFORE:scripts/merge-group-image.mjs" > "$trusted"
# Verify without writing a step output: the digest is set only after
# the exact bytes are in the registry.
verified="$(GITHUB_OUTPUT='' node "$trusted" verify --arch "$ARCH" --dir "$DIRECTORY" --since "$BEFORE")"
digest="$(printf '%s\n' "$verified" | sed -n 's/^digest=//p')"
printf '%s' "$digest" | grep -Eq '^sha256:[a-f0-9]{64}$'
# --preserve-digests fails rather than re-encode, so the registry
# holds exactly the archived image under the recorded digest.
skopeo copy --all --preserve-digests "oci-archive:$DIRECTORY/image.tar" "docker://$IMAGE_NAME@$digest"
echo "Promoted the merge-queue image $IMAGE_NAME@$digest"
echo "digest=$digest" >> "$GITHUB_OUTPUT"
- name: Set up Docker Buildx
if: steps.promote.outputs.digest == ''
uses: docker/setup-buildx-action@v4
with:
buildkitd-config-inline: |
[registry."docker.io"]
mirrors = ["mirror.gcr.io"]
# Deployment tooling reads these labels from the registry to verify an
# image's schema expectations against a migrator before deploying it,
# without pulling the image. The server refuses to start when the
# database is missing bundled migrations, so orchestrators need a cheap
# way to check image/migrator compatibility up front.
- name: Compute schema migration labels
id: schema
if: steps.promote.outputs.digest == ''
run: |
set -euo pipefail
last=$(ls packages/db/src/migrations/*.sql | sed 's|.*/||' | LC_ALL=C sort | tail -1)
count=$(ls packages/db/src/migrations/*.sql | wc -l | tr -d ' ')
echo "last=${last}" >> "$GITHUB_OUTPUT"
echo "count=${count}" >> "$GITHUB_OUTPUT"
# Lane tag mapping: nightly/v* tags publish `:nightly`, and only
# stable v* tags move `:latest` and the versioned tags.
# `:sha-<short>` is published on every build. `:canary` is
# deliberately absent here — the channel tag is moved by the
# dist-tag-checked retag step below, never by the build matrix,
# so parallel canary builds cannot race it backwards.
- name: Docker meta
id: meta
if: steps.promote.outputs.digest == ''
uses: docker/metadata-action@v6
with:
images: ghcr.io/${{ github.repository }}
tags: |
type=raw,value=nightly,enable=${{ startsWith(github.ref, 'refs/tags/nightly/v') }}
type=raw,value=beta,enable=${{ startsWith(github.ref, 'refs/tags/beta/v') }}
type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
type=semver,pattern={{version}},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
type=semver,pattern={{major}}.{{minor}},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
type=sha
type=raw,value=sha-${{ github.sha }},enable=${{ github.repository == 'paperclipai/paperclip' && github.event_name == 'push' && github.ref == 'refs/heads/master' }}
labels: |
io.github.paperclipai.schema.last-migration=${{ steps.schema.outputs.last }}
io.github.paperclipai.schema.migration-count=${{ steps.schema.outputs.count }}
- name: Build and push by digest
id: build
if: steps.promote.outputs.digest == ''
uses: docker/build-push-action@v7
with:
context: .
# Pin the self-hosted image to the production stage explicitly:
# the Dockerfile now declares a later `cloud` stage, and without a
# target the default would silently become that stage.
target: production
build-args: |
PAPERCLIP_BUILD_VERSION=${{ steps.build-version.outputs.version }}
PAPERCLIP_BUILD_COMMIT=${{ github.sha }}
CLI_TOOLS_CACHE_EPOCH=${{ steps.tools-epoch.outputs.epoch }}
${{ needs.runner_image.outputs.build_args }}
build-contexts: ${{ needs.runner_image.outputs.build_contexts }}
platforms: ${{ matrix.platform }}
# By digest, not by tag: two runners cannot each push the same tag
# and end up with a manifest list. Each leg publishes an untagged
# image and `merge` names them together.
outputs: type=image,name=ghcr.io/${{ github.repository }},push-by-digest=true,name-canonical=true,push=true
# Registry-backed BuildKit cache instead of type=gha: the Actions
# cache is capped at 10GB per repo, and two multi-arch mode=max jobs
# evict each other, so most builds ran effectively cold. The cache
# ref lives in ghcr next to the image and is written only by this
# workflow (docker.yml runs on master/tag pushes, never on PRs).
#
# Per-arch refs now the legs are separate runners: a shared ref would
# have each leg overwrite the other's cache on every build.
cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache-${{ matrix.arch }}
cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache-${{ matrix.arch }},mode=max
labels: |
${{ steps.meta.outputs.labels }}
${{ needs.runner_image.outputs.labels }}
# Exactly one of the two paths produced this leg's digest.
- name: Select image digest
id: image
env:
PROMOTED: ${{ steps.promote.outputs.digest }}
BUILT: ${{ steps.build.outputs.digest }}
run: |
set -euo pipefail
digest="${PROMOTED:-$BUILT}"
test -n "$digest"
echo "digest=$digest" >> "$GITHUB_OUTPUT"
# PID 1 must be an init that reaps adopted orphans. With node there, the
# orphans agent runs leave behind are never wait()ed and pin as zombies
# until the cgroup pid limit is exhausted and every fork() in the
# container fails.
#
# Probed here, on this leg's own architecture, against the exact digest
# just pushed. On master this runs while the exact-source gate is still
# pending, so the image pull (~95 s for amd64) is off the publication
# path, and arm64 is exercised too (the publisher runner is x86_64 only).
# Only a probed digest is exported, and merge-and-push signs an index
# only when its every Linux image is one of these probed digests.
- name: Verify PID 1 reaps orphaned processes
env:
# Through the environment, not interpolated into the script body.
IMAGE_DIGEST: ${{ steps.image.outputs.digest }}
IMAGE_NAME: ghcr.io/${{ github.repository }}
PLATFORM: ${{ matrix.platform }}
run: |
set -euo pipefail
test -n "$IMAGE_DIGEST"
echo "Verifying orphan reaping in $IMAGE_NAME@$IMAGE_DIGEST ($PLATFORM)"
docker run --rm -i --pull always --platform "$PLATFORM" "$IMAGE_NAME@$IMAGE_DIGEST" sh -s < scripts/assert-orphan-reaping.sh
# The digest is the only thing `merge` needs from this job. Carried as an
# empty file named for it, which is the upstream pattern — the name is
# the payload, so several legs can upload without colliding on content.
- name: Export digest
run: |
set -euo pipefail
mkdir -p /tmp/digests
digest="${{ steps.image.outputs.digest }}"
test -n "$digest"
touch "/tmp/digests/${digest#sha256:}"
- name: Upload digest
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
with:
name: digests-production-${{ matrix.arch }}
path: /tmp/digests/*
if-no-files-found: error
retention-days: 1
# Wait for proof on ephemeral verification capacity. Publication runners do
# only registry/signing work. Each Spot observer stays below its 45m lifetime.
publication_verification:
name: Require exact-source verification
if: ${{ !cancelled() && github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064' && github.ref == 'refs/heads/master' && needs.build-and-push.result == 'success' && needs.source_verification.result == 'success' && needs.source_verification.outputs.verified != 'true' }}
needs: [build-and-push, source_verification]
runs-on: ${{ vars.AWS_POST_MERGE_CI_ENABLED == 'true' && github.run_attempt >= 1 && github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064' && github.ref == 'refs/heads/master' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && 'runs-on/fleet=paperclip-post-merge-x64/env=public-ci' || 'ubuntu-latest' }}
timeout-minutes: 44
permissions:
contents: read
actions: write # restart only exact-source producers deferred before admission
checks: read # runner-loss evidence (annotations) for readiness retries
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
with:
node-version: 24
- name: Require source proof and migrator admission before publication
env:
GITHUB_TOKEN: ${{ github.token }}
run: node scripts/watch-release-source.mjs --require-proof
# Names the per-architecture digests as one manifest list under the real
# tags. Nothing is publicly tagged until this runs, so a half-published
# multi-arch image is not a state anything can pull.
merge-and-push:
if: ${{ !cancelled() && needs.build-and-push.result == 'success' && (needs.source_verification.result == 'success' || needs.source_verification.result == 'skipped') && (needs.publication_verification.result == 'success' || (needs.publication_verification.result == 'skipped' && (github.repository != 'paperclipai/paperclip' || github.repository_id != '1170821064' || github.ref != 'refs/heads/master' || needs.source_verification.outputs.verified == 'true'))) }}
needs: [build-and-push, source_verification, publication_verification]
runs-on: ${{ github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064' && github.ref == 'refs/heads/master' && (vars.CORE_PUBLICATION_RUNNER || 'cloud-release-32') || 'ubuntu-latest' }}
timeout-minutes: 20
permissions:
contents: read
actions: read
packages: write
id-token: write
attestations: write
steps:
# Checked out for `packages/db` (schema labels) and the source-proof and
# standard-image contract scripts.
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- name: Download digests
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
with:
path: /tmp/digests
pattern: digests-production-*
merge-multiple: true
- name: Login to GitHub Container Registry
uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4
# Repeated from the build job rather than passed between them: job
# outputs would have to survive a matrix, and this is two `ls` calls.
- name: Compute schema migration labels
id: schema
run: |
set -euo pipefail
last=$(ls packages/db/src/migrations/*.sql | sed 's|.*/||' | LC_ALL=C sort | tail -1)
count=$(ls packages/db/src/migrations/*.sql | wc -l | tr -d ' ')
echo "last=${last}" >> "$GITHUB_OUTPUT"
echo "count=${count}" >> "$GITHUB_OUTPUT"
# Same lane mapping as the build job; this is where it is actually
# applied, since the legs push untagged. `:canary` is deliberately
# absent, exactly as in the build job's mapping: the channel tag is
# moved only by the dist-tag-checked promote_canary_channel job below,
# so parallel canary-tag builds can never race the channel backwards.
- name: Docker meta
id: meta
uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6
with:
images: ghcr.io/${{ github.repository }}
tags: |
type=raw,value=nightly,enable=${{ startsWith(github.ref, 'refs/tags/nightly/v') }}
type=raw,value=beta,enable=${{ startsWith(github.ref, 'refs/tags/beta/v') }}
type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
type=semver,pattern={{version}},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
type=semver,pattern={{major}}.{{minor}},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
type=sha
type=raw,value=sha-${{ github.sha }},enable=${{ github.repository == 'paperclipai/paperclip' && github.event_name == 'push' && github.ref == 'refs/heads/master' }}
labels: |
io.github.paperclipai.schema.last-migration=${{ steps.schema.outputs.last }}
io.github.paperclipai.schema.migration-count=${{ steps.schema.outputs.count }}
- name: Setup Node.js
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
with:
node-version: 24
# Revalidate the latest attempt after runner assignment without waiting
# here. A concurrent source retry must invalidate the earlier proof.
- name: Revalidate exact-source proof before publication
if: github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064' && github.ref == 'refs/heads/master'
env:
GITHUB_TOKEN: ${{ github.token }}
run: node scripts/watch-release-source.mjs --check-proof
- name: Create manifest list and push
working-directory: /tmp/digests
run: |
set -euo pipefail
docker buildx imagetools create \
$(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
$(printf 'ghcr.io/${{ github.repository }}@sha256:%s ' *)
# The orphan-reaping probe ran in each build leg against the digest that
# leg pushed; /tmp/digests holds only probed digests. Pulling the image
# again here cost ~95 s after the source gate, on the publication path.
# This generic contract is useful to any downstream image composer. Only
# canonical master pushes own the full-SHA tag and its signed provenance.
# Capture exact registry bytes and sign that digest, so later tag movement
# cannot change what was verified. Registry content is addressed by
# digest: the resolve step fails unless every Linux image in the index is
# one the build legs probed.
- name: Resolve standard image digest
id: standard
if: github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064' && github.event_name == 'push' && github.ref == 'refs/heads/master'
run: node scripts/standard-image-contract.mjs --resolve "$GITHUB_SHA" --verified-digests /tmp/digests
- name: Attest the standard production image
if: steps.standard.outputs.digest != ''
uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4
with:
subject-name: ghcr.io/paperclipai/paperclip
subject-digest: ${{ steps.standard.outputs.digest }}
push-to-registry: true
# Moves the mutable `:canary` channel tag. Kept OUT
# of the build jobs and serialized in its own lane, and — the load-
# bearing property — CONVERGENT rather than self-interested: a
# promotion does not promote "its own" canary, it retags the channel
# to whatever the npm `canary` dist-tag names at execution time,
# provided that version's sha images are published. GitHub's shared
# concurrency lane keeps one running and one pending promotion and
# REPLACES the pending slot with the latest enqueued — an older build
# finishing late can therefore evict the newest canary's pending
# promotion. With convergent promotion that eviction is harmless:
# whichever promotion survives resolves the current dist-tag fresh
# and lands the channel there (the current canary's images always
# exist by the time any later promotion runs, because per-tag build
# groups mean canary builds are never superseded and each run's
# promotion is gated on its own completed pushes). Every interleaving
# converges the Docker channel onto the npm channel.
promote_canary_channel:
if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/canary/v') && (needs.merge-and-push.result == 'success' || (needs.reuse_canary_image.result == 'success' && needs.reuse_canary_image.outputs.reused == 'true')) }}
needs: [reuse_canary_image, merge-and-push]
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: read
packages: write
concurrency:
group: docker-canary-channel-promotion
cancel-in-progress: false
steps:
- name: Login to GitHub Container Registry
uses: docker/login-action@v4
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Converge the channel tags onto the current npm canary
env:
IMAGE: ghcr.io/${{ github.repository }}
GH_TOKEN: ${{ github.token }}
run: |
current="$(curl -fsS "https://registry.npmjs.org/-/package/@paperclipai%2Fdb/dist-tags" | jq -er .canary)"
sha="$(gh api "repos/${GITHUB_REPOSITORY}/commits/$(printf 'canary/v%s' "$current" | jq -sRr @uri)" --jq .sha 2>/dev/null || true)"
if [ -z "$sha" ]; then
echo "canary/v${current} does not resolve yet; a later promotion converges the channel"
exit 0
fi
short="$(printf '%s' "$sha" | cut -c1-7)"
if ! docker buildx imagetools inspect "$IMAGE:sha-${short}" >/dev/null 2>&1; then
echo "images for ${current} (sha-${short}) not published yet; its own promotion converges the channel"
exit 0
fi
docker buildx imagetools create -t "$IMAGE:canary" "$IMAGE:sha-${short}"
echo "channel tags moved to canary ${current} (sha-${short})"