PaperClipAI/doc/preview-release-artifacts.md

Preview deployment artifacts

The preview channel in .github/workflows/release.yml builds deployment artifacts for one immutable source commit. It does not create a GitHub release, move a source branch, or advance any stable, beta, nightly, or canary alias.

Dispatch release.yml on master with these inputs:

Input	Value
channel	preview
source_ref	Full lowercase 40-character commit SHA in this repository
request_id	UUID v4 identifying the operator's deployment request
preview_migrator	true when exact-source DB/shared packages are needed
dry_run	false

The workflow title is Stack deploy <request_id> build. Consumers must find a run by this identity, not by the latest run. Preview builds reject workflow definitions that do not run from master.

Outputs and reuse

The image uses ghcr.io/paperclipai/paperclip:sha-<FULL_SHA>-cloud. Full-SHA tags keep separate commits with the same short prefix isolated. Normal release images retain their existing short-tag convention. Build arguments carry the full commit SHA. Preview builds do not import or overwrite the shared release cache or release aliases. Missing images are built for Linux amd64, matching managed deployments.

When requested, both @paperclipai/shared and @paperclipai/db use 0.0.0-preview.g<FULL_SHA>. Workspace dependencies are pinned to exact versions. Packages carry gitHead and paperclipPreviewCommit source identity. npm publishes them under the preview dist-tag only. Normal consumers of latest or canary continue to select normal releases.

Registry 404 responses mean missing artifacts. Authentication errors, outages, or existing package identity mismatches fail the workflow. Retries reuse matching published artifacts, including a shared package published before a DB publish failure. Allow npm's visibility polling to finish before retrying.

The publisher validates both package archives first, then submits each missing package without waiting for the other to become visible. One visibility poll checks both accepted packages, so their registry propagation delays overlap. The publisher succeeds only after both packages pass the identity and distribution-pin checks. A visibility timeout names the package still missing.

The final stack-deploy-result artifact contains result.json with contract version 1, request ID, SHA, stage build, and status ready. It expires after 30 days. This confirms artifact availability; it does not certify a tenant deploy.

Publishing configuration and isolation

Migrator publication on merge

The Cloud artifacts workflow starts a cloud-migrator dispatch of release.yml for every push to master. This dispatch builds and publishes only the exact-source @paperclipai/shared and @paperclipai/db preview packages. It starts independently of the full npm release and does not wait for the Docker image. The normal Docker workflow supplies the image separately.

The run title is Cloud migrator <FULL_SHA>. A successful Cloud artifacts dispatch job only confirms that GitHub accepted the request. Inspect the matching release.yml run to confirm publication completed. This path does not produce a stack-deploy-result or certify source-test success or deployment readiness. Cloud must still verify all deployment prerequisites.

To retry one commit, dispatch release.yml on master with channel=cloud-migrator, the full SHA as source_ref, a new UUID v4 as request_id, and dry_run=false. preview_migrator is not required for this channel. Existing packages are verified and reused. Preview and migrator-only runs use separate workflow concurrency groups. Only their package publication jobs share a group for the same SHA, so they cannot publish the same version concurrently and the migrator does not wait for a preview's image build. Different SHAs publish in separate groups; the full release keeps its existing group.

Publisher identity

Configure npm trusted publishing for both packages with repository paperclipai/paperclip, workflow release.yml, and environment npm-canary. The image publisher uses the same environment, whose deployment branch policy permits only master. Both publishers also check the workflow ref before running. This uses the existing publisher identity rather than requiring another workflow registration. The job uses npm with OIDC trusted publishing support and provenance. The environment's existing protections still apply.

Package compilation runs in a separate job with read-only repository access and no npm, cloud-admin, or provider credentials. Trusted tooling from master packs the requested source checkout. The existing bundled-package helper takes patch configuration from that source checkout. Build artifacts contain only the two fixed package tarballs.

Publishing runs on a fresh runner with trusted tooling, without a checkout of the requested branch. It checks package identity and exact dependencies, rejects archive path aliases, and publishes with lifecycle scripts disabled and an explicit registry and dist-tag. Image builds also run without registry write access and export a Docker archive. A separate trusted publisher loads that archive as data, verifies its full revision, platform, and image ID, then pushes only the SHA tag. It never runs the image. Dependency resolution disables scripts and pnpmfile hooks. Preview actions are pinned to full commit SHAs.

The deploying control plane must independently verify package integrity, source identity, SQL and migration journal contents, and schema compatibility. Publish this workflow support before enabling an operator CLI that depends on it. Test normal release selection and a new migration-bearing branch in staging before allowing production use.

Local checks

node --test scripts/preview-artifacts.test.mjs
pnpm test:release-registry
pnpm -r typecheck
pnpm test:run
pnpm build

For a package build without publishing, install dependencies in a disposable checkout at an exact commit, then use the trusted helper:

node scripts/preview-artifacts.mjs pack /path/to/source /path/to/output FULL_SHA

This executes source build scripts. Keep output outside the repository and use an environment without publishing or cloud-admin credentials.

Direct cloud migrator artifacts

cloud-migrator-artifacts.yml builds the DB and shared preview packages on each canonical master push. A manual run also requires master and uses its exact commit. This workflow runs on GitHub-hosted runners. It has no PR trigger.

The build resolves a complete npm lockfile from the two local archives. It then pins their download URLs to immutable, content-addressed objects. The cloud migration runner can use npm ci with this lockfile before either new package version is available on npm. Existing external dependencies still come from npm and carry SHA-512 integrity pins. Package lifecycle scripts remain disabled. Before upload, the build job smoke-installs the real archives and their complete external and bundled dependency graph with an empty npm cache. It imports both installed packages. This check uses local archive URLs because public objects do not exist yet; all versions and integrity pins remain unchanged.

Artifacts use the existing runner-history S3 bucket and CloudFront distribution, under the separate cloud-migrators/v1/ prefix. The manifest at https://d1p6rlowie26tp.cloudfront.net/cloud-migrators/v1/<full-sha>/manifest.json records the full source SHA, exact preview version, and the size, URL, and SHA-512 hash of each archive and the lockfile. Blob URLs include the content hash. The publisher validates the complete bundle before any write, writes all blobs before the manifest, and verifies downloads through the public endpoint. A retry reuses a complete existing manifest after verification. The publisher also creates a GitHub/Sigstore build-provenance attestation for the manifest before upload. This independently binds all package and lockfile content hashes to the canonical workflow, master ref, repository identity, and source commit. Cloud must verify this signature and its certificate claims before accepting the executable archives; hashes served by the artifact store alone are not sufficient provenance.

The build job has no AWS credential. The publish job downloads only the four fixed files, validates them, and uploads them without executing their code. The dedicated paperclip-cloud-migrator-github OIDC role trusts only repo:paperclipai/paperclip:ref:refs/heads/master. Its policy permits prefix listing and conditional PutObject calls in this one prefix. It permits no object deletion or overwrite. PRs, including allowlisted PRs, cannot assume it.

The deploy policies are checked in under .github/cloud-migrator-deploy/:

• trust-policy.json: the role trust policy.
• upload-policy.json: the role's inline permission policy.
• cloudfront-read-statement.json: append this statement to the existing bucket policy, preserving its other statements and public-access blocks.

There is no lifecycle expiry on this prefix. Keep referenced artifacts for rollback; deleting them can prevent a fresh migrator install for an old release. Cloud readiness consumes the signed direct bundle after its exact-source publisher succeeds. It retains source verification, image identity, and the cloud runner's integrity and migration compatibility checks. The cloud direct artifact switch must be enabled before adopting this gate. Automatic npm-only migrator dispatch is removed; explicit npm previews and manual migrator runs remain available. See doc/cloud-build-readiness.md for coordinated rollback.

Local verification:

node --test scripts/cloud-migrator-artifacts.test.mjs
node scripts/cloud-migrator-artifacts.mjs verify <full-sha>