feat: speed up API build and gate "latest" on a complete release

[pikann]

Summary

CD: speed up the API image build. The services/api builder stage now cross-compiles natively (--platform=$BUILDPLATFORM + GOOS=$TARGETOS GOARCH=$TARGETARCH) instead of running the Go compiler under QEMU emulation for linux/arm64, which was the dominant cost of the ~20 minute build. GOMAXPROCS / GOMEMLIMIT / -p are now build-args (defaulting to the original single-core/768MiB values for local and e2e builds) that cd.yml overrides to 4 cores / 6GiB for CI.

CD: never expose a half-shipped release. Previously release-assets (which uploads install.sh, upgrade.sh, docker-compose.yml, etc.) depended on every image/package job, so those files simply didn't exist for the ~20-30 minutes a release was building, and GitHub already marks a release "Latest" the instant it's published — so /releases/latest/download/* 404'd, and any Docker :latest pull could land on a stale mix of old/new images depending on which per-service job happened to finish first. Fixed with three coordinated pieces:

• hold-release-label (new, runs first) immediately demotes the release off GitHub's "Latest" marker, so /releases/latest keeps resolving to the previous, fully-shipped release for the whole build window.
• Per-service jobs no longer push a :latest Docker tag at all — only version-pinned tags ({{version}}, {{major}}.{{minor}}).
• promote-release (new, final job, depends on every other job, skipped for pre-releases) retags every image :latest via docker buildx imagetools create (registry-side copy, no rebuild) and only then marks the GitHub release "Latest" — tags first, label second, so /releases/latest never points at a release whose :latest images aren't there yet.

release-assets keeps its original needs on every image/package job, so it (and the version it stamps into the scripts below) never runs for a release that isn't fully shippable.

install.sh / upgrade.sh: pin to a specific version instead of floating :latest. Both scripts now default to PACA_DEFAULT_VERSION="latest", a single dedicated, comment-flagged line that CD's release-assets job stamps to the release's own tag before upload (sed -i 's/^PACA_DEFAULT_VERSION="latest"$/PACA_DEFAULT_VERSION="<tag>"/'). A plain bash install.sh / bash upgrade.sh downloaded from a release therefore always targets a version guaranteed to exist, rather than depending on the :latest Docker tag being current. AGENT_SERVER_IMAGE (previously hardcoded to :latest in both scripts) now pins to the same version tag as everything else, including in upgrade.sh's re-pin and old-upstream-image migration logic. The source-tree copies of both scripts keep PACA_DEFAULT_VERSION="latest" so a plain checkout still behaves sensibly, and the header doc comments were reworded to be evergreen instead of needing their own sed pass.

Test plan

• Publish a release and confirm /releases/latest keeps pointing at the previous release until promote-release runs, then flips over
• Confirm every image (paca-api, paca-realtime, paca-web, paca-ai-agent, paca-agent-server) gets a :latest tag on both GHCR and DockerHub only after promote-release succeeds
• Confirm install.sh / upgrade.sh downloaded from that release have PACA_DEFAULT_VERSION stamped to the release tag, and that a plain run pins PACA_API_IMAGE, PACA_WEB_IMAGE, PACA_REALTIME_IMAGE, PACA_AI_AGENT_IMAGE, and AGENT_SERVER_IMAGE to that version
• Confirm the API image build time drops from ~20 min and both linux/amd64/linux/arm64 images still run correctly
• Confirm local docker compose / e2e builds of services/api are unaffected (still single-core defaults), and scripts/install.sh/scripts/upgrade.sh run directly from a checkout still default to latest

[pullfrog]

Important

The release-assets job should keep a needs dependency on the image build jobs. Removing it lets release assets publish before the Docker images they reference are available, and it removes the failure gate that prevents a broken release from being advertised.

Reviewed changes

• services/api/Dockerfile: switched the builder stage to FROM --platform=$BUILDPLATFORM, added TARGETOS/TARGETARCH cross-compilation, and parameterized GOMAXPROCS / GOMEMLIMIT / GOBUILD_P with conservative local defaults.
• .github/workflows/cd.yml: passed the three build args to the API image build, and removed the needs block from release-assets.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

The new commit (415de0a) reworks the release sequencing in response to the prior review:

• Restored the release-assets failure gate. release-assets again needs every image and package job, so install.sh, upgrade.sh, and the compose file are only uploaded once every artefact is actually shippable.
• Added hold-release-label / promote-release. The release is demoted from GitHub's "Latest" marker immediately on publish, then re-promoted only after all images, packages, and release assets have succeeded. :latest Docker tags are also applied only at promotion time via docker buildx imagetools create, so /releases/latest/download/* and :latest image pulls stay consistent with the previous fully-shipped release until the new one is complete.
• Pinned script defaults to the release tag. install.sh and upgrade.sh are stamped with the exact release tag during the asset upload, so a plain bash install.sh never depends on the floating :latest tag being current.
• Updated AGENT_SERVER_IMAGE handling in scripts. install.sh now writes the versioned tag, and upgrade.sh only re-pins it when it already points to Paca's own image, preserving custom values.

The cross-compilation / build-arg changes in services/api/Dockerfile are unchanged from the previous review and remain sound.

  ^{｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

The new commit (fbcf608) makes two small hardening tweaks to the release sequencing in .github/workflows/cd.yml:

• Replaced direct tag interpolation in gh release edit commands with a TAG_NAME environment variable, so the release tag flows into the shell via a proper env rather than a GitHub Actions context-expression string.
• Sequenced the hold-release-label job before promote-release by adding it to promote-release's needs, preventing any possibility of the "Latest" label being re-promoted before the initial demotion has run.

The script and Dockerfile changes from prior reviews are unchanged and remain sound.

  ^{｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}