From 932c8bec56fdcb581b0a65a7999caa85047fb37f Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Fri, 11 Sep 2026 00:58:27 -0700 Subject: [PATCH] fix(ci): bake the managed runtime identity into cloud images (#13210) ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Managed deployments start from the image built by the Cloud workflow. > - The managed runtime requests user and group 1001. > - The image currently builds the node user as 1000. > - Startup must remap that user, which can walk a large mounted home directory. > - This pull request uses the existing Docker build arguments to bake user and group 1001 into Cloud images. > - Matching the runtime identity removes that startup work and helps avoid health-check retries. ## Linked Issues or Issue Description Refs #13208, #1923, and #7861. Searched open and closed PRs for the Cloud UID change. The older #7861 addresses build context and volume ownership repair. This change uses the existing identity arguments in the Cloud workflow and preserves ownership repair. **What happened?** A measured rollout had a container log `Updating node UID to 1001` after startup. The container stayed at this step for at least 2 minutes 55 seconds before rollback stopped it. The baked node identity was 1000, while the managed runtime requested 1001. A health check timed out and the target required a second deployment attempt. **Expected behavior** Cloud images should already have the managed runtime identity. A matching image should skip user and group remapping. Fresh or mismatched volumes must still receive ownership repair. **Steps to reproduce** 1. Build the current Cloud image with its default build arguments. 2. Start it with `USER_UID=1001`, `USER_GID=1001`, and a populated home volume. 3. Observe the startup user remap before the application starts. **Paperclip version or commit** `fc06f7f05f42c675be71ff0927b6334405d520ed` **Deployment mode** Docker on managed hosts. ## What Changed - Pass `USER_UID=1001` and `USER_GID=1001` to the Cloud image build. - Check the pushed digest's baked identity before the entrypoint can repair it. Then check the normal entrypoint's effective identity and writable home before publishing the verified full-SHA tag. - Add a workflow regression and two entrypoint cases for a matching Cloud identity, including a mismatched volume. - Document the runtime identity and the first-build cache cost. ## Verification - Focused workflow and artifact tests: 27 passed. - Entrypoint tests: 11 passed. Actionlint passed. Full local `pnpm -r typecheck` passed. Full local `pnpm build` passed. The manual [Cloud image build](https://github.com/paperclipai/paperclip/actions/runs/34575473213) passed on the exact PR head. It checked Sentry, baked and effective identity, writable home, orphan reaping, and full-SHA publication. The new identity check took one second. All 30 PR checks passed; the Storybook workflow was intentionally skipped. Greptile reviewed commit `114d408f637a0b53e2e2b1339c263779b1e4ae54` at 5/5 with no findings or open threads. - The full local suite for the same application source was already run in #13205. Its macOS general-server phase had 10,471 passes and 70 failures in seven unchanged files. Those failures included missing Runner fixtures, filesystem errors, timeouts, a port conflict, and a load-count mismatch. After configuring Cargo and rebuilding fixtures, 37 of 38 native tests passed; one unchanged native-resume assertion still failed. Linux PR CI passed. This change adds entrypoint tests and does not change application code. ## Risks - The first build must rebuild layers that depend on the base image identity. Later builds can reuse them. - A future managed runtime identity change must update these build arguments and checks together. - The Dockerfile's self-hosted defaults remain 1000. Runtime overrides and mounted-volume ownership repair remain supported. - The observed startup delay supports this change, but fleet timing also includes provider startup, image pull, canary order, and retries. No fixed end-to-end gain is claimed before a live rollout. ## Model Used OpenAI GPT-6 through Codex, with reasoning, code execution, and tool use. The exact serving model ID and context-window size are not exposed in this session. ## 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 (focused workflow tests; full-suite limitations are listed above) - [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 - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip --- .github/workflows/docker-cloud.yml | 22 +++++++++++++++++++ doc/cloud-build-readiness.md | 10 +++++++++ scripts/preview-artifacts.test.mjs | 18 +++++++++++++++ .../src/__tests__/docker-entrypoint.test.ts | 12 ++++++++++ 4 files changed, 62 insertions(+) diff --git a/.github/workflows/docker-cloud.yml b/.github/workflows/docker-cloud.yml index e920dbfa71..14fe69f87f 100644 --- a/.github/workflows/docker-cloud.yml +++ b/.github/workflows/docker-cloud.yml @@ -205,6 +205,8 @@ jobs: # variant installs from server/package.json's declared version; # add another name there when a managed tenant needs it. build-args: | + USER_UID=1001 + USER_GID=1001 CLOUD_BUNDLED_PLUGINS=daytona CLOUD_BUNDLED_SERVER_DEPS=@sentry/node PAPERCLIP_BUILD_VERSION=${{ steps.build-version.outputs.version }} @@ -251,6 +253,26 @@ jobs: fi echo "The pushed image resolves the declared @sentry/node version." + # Managed hosts run node as 1001:1001. Bake that identity into the image + # so usermod does not walk the mounted home on every container start. + # Check before the entrypoint can repair a wrongly built identity. + - name: Verify cloud runtime user + env: + IMAGE: ghcr.io/${{ github.repository }}@${{ steps.build-cloud.outputs.digest }} + run: | + set -euo pipefail + docker run --rm --entrypoint sh "$IMAGE" -ec ' + test "$(id -u node)" = 1001 + test "$(id -g node)" = 1001 + test "$USER_UID" = 1001 + test "$USER_GID" = 1001 + ' + docker run --rm -e USER_UID=1001 -e USER_GID=1001 "$IMAGE" sh -ec ' + test "$(id -u)" = 1001 + test "$(id -g)" = 1001 + test -w "$PAPERCLIP_HOME" + ' + # Verify the independently published cloud image without waiting for # the self-hosted manifest job. The Sentry check already pulled it. - name: Verify cloud PID 1 reaps orphaned processes diff --git a/doc/cloud-build-readiness.md b/doc/cloud-build-readiness.md index 6522f03e05..e5c45c1586 100644 --- a/doc/cloud-build-readiness.md +++ b/doc/cloud-build-readiness.md @@ -15,6 +15,16 @@ The `Cloud readiness` workflow starts for every master push. Its versioned Registry metadata must match the full commit, and the database package must pin the matching shared package. +The Cloud workflow builds the image with `USER_UID=1001` and `USER_GID=1001`, +matching the managed runtime. This avoids a startup user remap, which can walk +the mounted home and delay health checks. Before publishing the full-SHA tag, +the workflow checks the baked identity without running the entrypoint, then +checks the normal entrypoint's effective user and writable home. Volume ownership +repair still runs when needed. The Dockerfile defaults remain `1000:1000` for +self-hosted builds, and runtime identity overrides remain supported. The first +build with the new identity must rebuild layers that depend on the base image; +later builds can reuse those layers. + Verification and image building run concurrently, outside the full npm release's concurrency group. Different commits have independent groups. Source verification is initially duplicated with the normal npm release: this spends existing hosted diff --git a/scripts/preview-artifacts.test.mjs b/scripts/preview-artifacts.test.mjs index 0417365b1b..15ca6978f2 100644 --- a/scripts/preview-artifacts.test.mjs +++ b/scripts/preview-artifacts.test.mjs @@ -197,6 +197,24 @@ test("cloud builds start per commit and preserve tag promotion dependencies", () assert.ok(reaping < cloud.indexOf(" - name: Publish verified full-SHA cloud tag")); }); +test("cloud builds bake the managed runtime identity and verify it before publication", () => { + const workflow = readFileSync(new URL("../.github/workflows/docker-cloud.yml", import.meta.url), "utf8"); + const build = workflow.split(" - name: Build and push (cloud)")[1].split(" - name:")[0]; + assert.match(build, /build-args: \|\n\s+USER_UID=1001\n\s+USER_GID=1001\n/); + const verify = workflow.indexOf(" - name: Verify cloud runtime user"); + assert.ok(verify > workflow.indexOf(" - name: Verify the pushed image resolves the declared Sentry version")); + assert.ok(verify < workflow.indexOf(" - name: Publish verified full-SHA cloud tag")); + const step = workflow.slice(verify).split("\n - name:")[0]; + assert.match(step, /IMAGE: ghcr.io\/\$\{\{ github.repository \}\}@\$\{\{ steps.build-cloud.outputs.digest \}\}/); + assert.doesNotMatch(step, /continue-on-error:|if:/); + assert.ok(step.indexOf('--entrypoint sh "$IMAGE"') < step.indexOf('-e USER_UID=1001 -e USER_GID=1001')); + for (const flag of ["u", "g"]) { + assert.ok(step.includes(`test "$(id -${flag} node)" = 1001`)); + assert.ok(step.includes(`test "$(id -${flag})" = 1001`)); + } + assert.ok(step.includes('test -w "$PAPERCLIP_HOME"')); +}); + test("cloud cache imports are bounded, follow master ancestry, and retain the legacy fallback", () => { const workflow = readFileSync(new URL("../.github/workflows/docker-cloud.yml", import.meta.url), "utf8"); const step = workflow.split(" - name: Select cloud cache ancestry")[1].split(" - name: Setup pnpm")[0]; diff --git a/server/src/__tests__/docker-entrypoint.test.ts b/server/src/__tests__/docker-entrypoint.test.ts index 102eca1b8b..03d0e4acb9 100644 --- a/server/src/__tests__/docker-entrypoint.test.ts +++ b/server/src/__tests__/docker-entrypoint.test.ts @@ -98,6 +98,18 @@ describe("docker-entrypoint.sh", () => { expect(calls).toContain("gosu node echo ENTRYPOINT-CMD-RAN"); }); + it.each([false, true])("skips remapping a cloud identity while preserving volume repair (mismatch: %s)", async (homeMismatch) => { + installStubs({ uid: 0, gid: 0, nodeUid: 1001, nodeGid: 1001, homeMismatch }); + + const { stdout, calls } = await runEntrypoint({ USER_UID: "1001", USER_GID: "1001", PAPERCLIP_HOME: stubDir }); + + expect(stdout).toContain("ENTRYPOINT-CMD-RAN"); + expect(calls).not.toContain("usermod"); + expect(calls).not.toContain("groupmod"); + expect(calls.includes(`chown -R node:node ${stubDir}`)).toBe(homeMismatch); + expect(calls).toContain("gosu node echo ENTRYPOINT-CMD-RAN"); + }); + it("chowns a root-owned home before gosu even with the default UID/GID (fresh volume mount)", async () => { // A freshly mounted volume arrives root-owned and shadows the image's // build-time chown; with no remap requested the old entrypoint dropped