HealthLog/docs/audit/v1416-auto-deploy-fix.md

v1.4.16 — Auto-deploy follow-up (image-digest only)

Stage: Cleanup-C / item 4 Last updated: 2026-05-09 (v1.4.16 release cycle) Status: designed, not shipped — DEFERRED to v1.5 (manual maintainer step required; MCP API does not expose the toggle)

Background — what v1.4.15 left half-finished

The v1.4.15 C2 work (docs/audit/v1415-auto-deploy.md) wired the publish workflow to call Coolify's deploy webhook AFTER GHCR pushes the new image. That solves the "deploy fires when there is a new image" half correctly.

What it did NOT solve: the Coolify application is configured with the GitHub-App integration (source_type: App\Models\GithubApp, git_repository: MBombeck/HealthLog, git_branch: main). Coolify's GitHub App auto-deploy fires on EVERY push to main — including .planning/, docs/, CHANGELOG.md, README.md and other doc-only commits that change zero image bytes. The compose pulls ghcr.io/mbombeck/healthlog:latest, finds the same digest, but still recreates the containers (Coolify always restarts the stack on a deploy event). During the v1.4.15 release cycle, user-observed container churn was reported — multi-second downtime windows on every doc-only push.

We need: deploy fires only when the image digest actually changes.

Investigation — what Coolify v4 supports

Coolify v4.0.0-beta.470 (current production) exposes these deploy-trigger toggles on a dockercompose application:

Setting	Effect	API access
Auto Deploy	GitHub-App webhook listens to push events	UI only (no MCP / REST endpoint exposes it on v4-beta)
Watch Paths	Glob list — push-event paths must match for auto-deploy to fire	UI only
Deploy Webhook	Bearer-protected GET /api/v1/deploy?uuid=… — programmatic trigger	MCP-callable
Notification Webhook	Outgoing POST when deploy completes (success / failure)	UI only

The MCP application.update action exposed by coolify-apps01 intentionally restricts mutations to the safe subset (fqdn, health_check_*, domains, name, description, environment_*, instant_deploy, build-pack family). It does NOT expose auto_deploy_enabled or watch_paths. Calling the bare REST API would require a Coolify UI-issued token AND would bypass the guardrails the MCP wraps around the install — too far outside the automated tooling's scope.

The Coolify community has an open feature request to expose auto_deploy_enabled over REST; the v4-stable line (expected July 2026) is the realistic landing window.

Watchtower — re-examined

v1415-auto-deploy.md rejected Watchtower for v1.4.15 ("polling daemon is material TCB expansion"). Re-examined here:

• The dockercompose build_pack on Coolify v4 ships a restart: unless-stopped policy already; adding a Watchtower sidecar with --label-enable and a per-image com.centurylinklabs.watchtower.enable=true label on the app service would re-pull on registry-digest change with NO push-event traffic.
• But a Watchtower install on apps-01 would also need read access to GHCR (private images) and sit in the same docker network as every other app on the host. That's a larger blast radius than the surgical "flip one Coolify toggle" alternative below.

Chosen approach — DEFER to v1.5 with concrete plan

v1.5 plan (concrete, two-step):

Step 1 — Maintainer-side manual toggle (5 min, before v1.5 cut)

Open Coolify UI → Applications > m-bombeck/-health-log:main-pg8wggwogo8c4gc4ks0kk4ss > Configuration:

1. General → Auto Deploy: turn OFF.
2. (Optional) General → Watch Paths: leave empty — the toggle above is enough; watch_paths only matters with Auto Deploy ON.
3. Save.

Effect: GitHub-App push events from main no longer fire a Coolify deploy. The Actions-driven Trigger Coolify deploy step in docker-publish.yml (already shipped in v1.4.15) becomes the SOLE trigger — and it only fires AFTER the image actually pushes to GHCR. Doc-only commits never reach the deploy queue.

Step 2 — automate the toggle for v1.5+

When Coolify v4-stable lands (or once coolify-apps01 MCP gains the auto_deploy_enabled field), patch scripts/configure-coolify-app.ts to flip the toggle programmatically. Until then the manual UI step is the contract.

Why NOT Watchtower for v1.4.16

The maintainer's instruction was explicit: "Don't half-ship". Watchtower would ship code (a new container in the prod compose, new credentials to manage) for a problem the manual Coolify toggle solves with zero new moving parts. The right call is the toggle.

Test plan after the toggle flip

1. Push a doc-only commit to main (e.g. amend CHANGELOG.md wording).
2. Watch Coolify's deployment history for pg8wggwogo8c4gc4ks0kk4ss — there should be NO deploy entry for that SHA.
3. Watch GHCR — no new image should be published either (the docker-publish.yml workflow only runs pnpm exec docker buildx when source changes, but we haven't path-filtered it yet — that's a separate v1.5 task).
4. Tag a real release (e.g. v1.5.0) — the workflow runs, GHCR publishes, and the Trigger Coolify deploy step fires the webhook. Coolify deploys ONCE.

Status after this audit

• v1.4.16: NO source change shipped for this item. The audit document is the deliverable.
• Maintainer-side action: flip the Coolify toggle whenever convenient. Does not block v1.4.16 release.
• v1.5 backlog: track the MCP-API automation as a concrete follow-up.