amtronics/platform-actions

Watch

Fork 0

docs: Stop tying deploy-vps to a traefik edge #83

Merged

ahmad merged 1 commit from feature/78-template-deploy-header into main

2026-09-09 20:13:36 +00:00

ahmad commented

2026-09-09 19:19:10 +00:00

Owner

Issue

Closes #78

Problem

templates/release.yml's header said the template "deploys with the shared
deploy-vps action (a traefik VPS host)" and told anyone "behind a reverse
proxy on published ports" to replace the deploy step with their own local
action. Both halves are wrong, and the second is the expensive one: every
application on this fleet is behind a reverse proxy, so the advice applied to
all of them.

ahmad/namey is the live counter-example — deploy-vps@v3, publishing
MARKETING_PUBLISH / PORTAL_PUBLISH for the nginx-proxy-manager edge to
forward. By that header its author should have written a local action.

The same claim was in two more places the issue did not name, found by the sweep
its fourth criterion asks for: the deploy-domain input's own description in
deploy-vps/action.yml, and the matching README row.

Solution

The header now says what the action does — copies docker-compose.vps.yml and
infra/alloy/config.alloy, writes the host .env from app-env, pulls, rolls
out, health-checks — and that routing is the compose file's business, naming
both shapes in use: traefik labels on the shared edge (suhba/suhba-docs), and
published ports behind a proxy (ahmad/namey).

Removing the false reason leaves a real question, so the replacement answers it:
write a local deploy action when the shared one cannot do the job — a different
compose filename or set, or a rollout that is not "pull, up -d, wait for
healthy" — and it names what you give up, since a local action that skips the
partial grafana-prom-* check deploys silently without metrics.

deploy-domain is now described by what it is: written to the host .env as
DEPLOY_DOMAIN, with the compose deciding what it means.

Review notes

The two remaining occurrences of "traefik" are deliberate and, I believe,
accurate: each names it as one of two shapes rather than as the edge. I did not
write that traefik is unused here — suhba/suhba-docs runs on vps-production
and its labels are live and load-bearing, including the TLS resolver and the
X-Robots-Tag middleware.

templates/release.yml is also touched by the open #82, which changes the notify
status: expression around line 311. This change is confined to the header
comment block, so the hunks do not overlap; whichever lands second should rebase
cleanly.

Risks and trade-offs

Comments and one input description — no behaviour changes. All five validate
steps pass locally by exit code, and both edited YAML files parse.

### Issue Closes #78 ### Problem `templates/release.yml`'s header said the template "deploys with the shared `deploy-vps` action (a traefik VPS host)" and told anyone "behind a reverse proxy on published ports" to replace the deploy step with their own local action. Both halves are wrong, and the second is the expensive one: every application on this fleet is behind a reverse proxy, so the advice applied to all of them. `ahmad/namey` is the live counter-example — `deploy-vps@v3`, publishing `MARKETING_PUBLISH` / `PORTAL_PUBLISH` for the nginx-proxy-manager edge to forward. By that header its author should have written a local action. The same claim was in two more places the issue did not name, found by the sweep its fourth criterion asks for: the `deploy-domain` input's own description in `deploy-vps/action.yml`, and the matching README row. ### Solution The header now says what the action does — copies `docker-compose.vps.yml` and `infra/alloy/config.alloy`, writes the host `.env` from `app-env`, pulls, rolls out, health-checks — and that routing is the compose file's business, naming both shapes in use: traefik labels on the shared edge (`suhba/suhba-docs`), and published ports behind a proxy (`ahmad/namey`). Removing the false reason leaves a real question, so the replacement answers it: write a local deploy action when the shared one cannot do the job — a different compose filename or set, or a rollout that is not "pull, `up -d`, wait for healthy" — and it names what you give up, since a local action that skips the partial `grafana-prom-*` check deploys silently without metrics. `deploy-domain` is now described by what it is: written to the host `.env` as `DEPLOY_DOMAIN`, with the compose deciding what it means. ### Review notes The two remaining occurrences of "traefik" are deliberate and, I believe, accurate: each names it as one of two shapes rather than as the edge. I did not write that traefik is unused here — `suhba/suhba-docs` runs on `vps-production` and its labels are live and load-bearing, including the TLS resolver and the `X-Robots-Tag` middleware. `templates/release.yml` is also touched by the open #82, which changes the notify `status:` expression around line 311. This change is confined to the header comment block, so the hunks do not overlap; whichever lands second should rebase cleanly. ### Risks and trade-offs Comments and one input description — no behaviour changes. All five `validate` steps pass locally by exit code, and both edited YAML files parse.

ahmad added 1 commit

2026-09-09 19:19:10 +00:00

docs: Stop tying deploy-vps to a traefik edge

PR / validate (pull_request) Successful in 21s

Details

6c14441118

The action does no routing — it copies the compose, writes the host .env,
pulls, rolls out and health-checks. The template's header nevertheless
told anyone behind a reverse proxy on published ports to write their own
deploy action, which is every application on the fleet, and ahmad/namey
already does exactly that with the shared action.

Says instead when a local action is warranted — a different compose set,
or a rollout that is not pull/up/wait — and what it costs, since a local
action that skips the partial grafana-prom-* check deploys silently
without metrics.

The deploy-domain input carried the same claim in its own description and
in the README; both now say the compose decides what the value means.

ahmad changed title from ~~WIP: docs: Stop tying deploy-vps to a traefik edge~~ to docs: Stop tying deploy-vps to a traefik edge

2026-09-09 19:19:56 +00:00

ahmad commented

2026-09-09 19:19:57 +00:00

Author

Owner

Self-verified against each acceptance criterion on 6c14441; PR / validate green.

The header does not state or imply that deploy-vps requires or assumes traefik. It now states what the action does — copy docker-compose.vps.yml and infra/alloy/config.alloy, write the host .env from app-env, pull, roll out, health-check — and that routing is the compose file's business.
The reason to write a local deploy action actually distinguishes the two. "A different compose filename or set, or a rollout that is not pull / up -d / wait for healthy." That is what ahmad/imamah genuinely does differently. Neither a reverse proxy nor published ports appears as a reason, because neither is one.
A reader deploying behind nginx-proxy-manager with published ports is pointed at deploy-vps and an example that does the same. ahmad/namey is named in the header, beside suhba/suhba-docs for the traefik shape, so both are visible as normal rather than one being the default.
Every remaining occurrence of "traefik" is accurate for the host it describes. Two remain, both naming it as one of two shapes: the header's suhba/suhba-docs example, and the deploy-domain description listing "a traefik router rule, a redirect URL, nothing at all" as things a compose may do with the value.

Gates by exit code: test-check-actions.py 0, check-actions.py 0 (it re-checked templates/release.yml and deploy-vps/action.yml), test-behaviour-harness.py 0, behaviour-tests.py 0, README lint 0. Both edited YAML files parse.

Two things the issue did not ask for but its fourth criterion required, so they are in here:

The deploy-domain input carried the same claim in its own description and in the README's input table — "Public hostname traefik routes." That is the copy a consumer actually reads while wiring the action, so leaving it would have kept the belief alive after the header stopped saying it.

I added what a local action costs rather than only when to write one. ahmad/imamah's leaves COMPOSE_PROFILES empty on a partial grafana-prom-* set where deploy-vps exits 1, so it deploys silently without metrics — that is the concrete price of forking the deploy step, and it belongs next to the advice.

Self-verified against each acceptance criterion on `6c14441`; `PR / validate` green. - *The header does not state or imply that `deploy-vps` requires or assumes traefik.* It now states what the action does — copy `docker-compose.vps.yml` and `infra/alloy/config.alloy`, write the host `.env` from `app-env`, pull, roll out, health-check — and that routing is the compose file's business. - *The reason to write a local deploy action actually distinguishes the two.* "A different compose filename or set, or a rollout that is not pull / `up -d` / wait for healthy." That is what `ahmad/imamah` genuinely does differently. Neither a reverse proxy nor published ports appears as a reason, because neither is one. - *A reader deploying behind nginx-proxy-manager with published ports is pointed at `deploy-vps` and an example that does the same.* `ahmad/namey` is named in the header, beside `suhba/suhba-docs` for the traefik shape, so both are visible as normal rather than one being the default. - *Every remaining occurrence of "traefik" is accurate for the host it describes.* Two remain, both naming it as one of two shapes: the header's `suhba/suhba-docs` example, and the `deploy-domain` description listing "a traefik router rule, a redirect URL, nothing at all" as things a compose may do with the value. Gates by exit code: `test-check-actions.py` 0, `check-actions.py` 0 (it re-checked `templates/release.yml` and `deploy-vps/action.yml`), `test-behaviour-harness.py` 0, `behaviour-tests.py` 0, README lint 0. Both edited YAML files parse. Two things the issue did not ask for but its fourth criterion required, so they are in here: The `deploy-domain` input carried the same claim in **its own description** and in the README's input table — "Public hostname traefik routes." That is the copy a consumer actually reads while wiring the action, so leaving it would have kept the belief alive after the header stopped saying it. I added what a local action costs rather than only when to write one. `ahmad/imamah`'s leaves `COMPOSE_PROFILES` empty on a partial `grafana-prom-*` set where `deploy-vps` exits 1, so it deploys silently without metrics — that is the concrete price of forking the deploy step, and it belongs next to the advice.

ahmad_bot approved these changes

2026-09-09 19:48:48 +00:00

ahmad_bot left a comment

Approved. No findings. All four criteria of #78 are met, and the fourth — the sweep — I re-ran rather than took on trust.

Verified

Every claim the new header makes about deploy-vps is what the action does. deploy-vps/action.yml: scp docker-compose.vps.yml (335), scp infra/alloy/config.alloy (336), scp .env.deploy → .env (337), docker compose pull (409), up -d --force-recreate --remove-orphans (412), then the healthcheck wait. Nothing in it routes anything, so "does no routing" is literally true rather than a simplification.
Both named examples are live and they really do sit on the same action. ahmad/namey uses deploy-vps@v3 (deploy.yml:51) and publishes ports for the proxy to forward — ${MARKETING_PUBLISH:?…}:80 and ${PORTAL_PUBLISH:?…}:80 in its compose, fed by app-env lines 64-65. suhba/suhba-docs uses deploy-vps@v3 from both release.yml:233 and deploy.yml:51 and carries live traefik labels: the Host() router built from DEPLOY_DOMAIN, entrypoints=websecure, tls.certresolver=le, and the X-Robots-Tag: noindex, nofollow plus HSTS middleware. So the two shapes are not illustrative, they are the two repositories the header names, and neither needed a different deploy step. That is the whole argument of #78 and it holds.
The replacement reason distinguishes the two, which the old one did not. "A different compose filename or set, or a rollout that is not pull, up -d, wait for healthy" is a property of the action's capability rather than of the host's edge — and ahmad/imamah, the example kept, qualifies on exactly that ground. Naming the cost is the part I would not have thought to ask for: a local action that skips the partial grafana-prom-* check deploys silently without metrics, which is measurably true of imamah's today.
The two surviving "traefik" occurrences are accurate. action.yml:30 lists it as one thing a compose might do with DEPLOY_DOMAIN — "a traefik router rule, a redirect URL, nothing at all" — and templates/release.yml:19 names it as one of two shapes with the repository that uses it. Neither says the action assumes it.
The correction did not need to propagate, and I checked rather than assumed. Swept all fourteen fleet repositories' .forgejo/workflows/*.yml on main for the four corrected phrasings: zero stale copies. Consumers evidently trimmed the header block when copying the template, so this repository really was the only place the claim lived — which is the outcome worth confirming for a template fix, since the usual failure is a sentence corrected in one place and still being copied from another.
PR / validate green.

One scheduling note, not a finding. #82 also edits templates/release.yml, at the notify status: expression around line 311, and this change is confined to the header block above line 30 — so they do not overlap textually, but whichever merges second will need a rebase. No conflict to resolve either way.

Approved. No findings. All four criteria of `#78` are met, and the fourth — the sweep — I re-ran rather than took on trust. **Verified** - **Every claim the new header makes about `deploy-vps` is what the action does.** `deploy-vps/action.yml`: `scp docker-compose.vps.yml` (335), `scp infra/alloy/config.alloy` (336), `scp .env.deploy → .env` (337), `docker compose pull` (409), `up -d --force-recreate --remove-orphans` (412), then the healthcheck wait. Nothing in it routes anything, so "does no routing" is literally true rather than a simplification. - **Both named examples are live and they really do sit on the same action.** `ahmad/namey` uses `deploy-vps@v3` (`deploy.yml:51`) and publishes ports for the proxy to forward — `${MARKETING_PUBLISH:?…}:80` and `${PORTAL_PUBLISH:?…}:80` in its compose, fed by `app-env` lines 64-65. `suhba/suhba-docs` uses `deploy-vps@v3` from both `release.yml:233` and `deploy.yml:51` and carries live traefik labels: the `Host()` router built from `DEPLOY_DOMAIN`, `entrypoints=websecure`, `tls.certresolver=le`, and the `X-Robots-Tag: noindex, nofollow` plus HSTS middleware. So the two shapes are not illustrative, they are the two repositories the header names, and neither needed a different deploy step. That is the whole argument of `#78` and it holds. - **The replacement reason distinguishes the two, which the old one did not.** "A different compose filename or set, or a rollout that is not pull, `up -d`, wait for healthy" is a property of the *action's* capability rather than of the host's edge — and `ahmad/imamah`, the example kept, qualifies on exactly that ground. Naming the cost is the part I would not have thought to ask for: a local action that skips the partial `grafana-prom-*` check deploys silently without metrics, which is measurably true of `imamah`'s today. - **The two surviving "traefik" occurrences are accurate.** `action.yml:30` lists it as one thing a compose might do with `DEPLOY_DOMAIN` — "a traefik router rule, a redirect URL, nothing at all" — and `templates/release.yml:19` names it as one of two shapes with the repository that uses it. Neither says the action assumes it. - **The correction did not need to propagate, and I checked rather than assumed.** Swept all fourteen fleet repositories' `.forgejo/workflows/*.yml` on `main` for the four corrected phrasings: **zero stale copies**. Consumers evidently trimmed the header block when copying the template, so this repository really was the only place the claim lived — which is the outcome worth confirming for a template fix, since the usual failure is a sentence corrected in one place and still being copied from another. - `PR / validate` green. **One scheduling note, not a finding.** `#82` also edits `templates/release.yml`, at the notify `status:` expression around line 311, and this change is confined to the header block above line 30 — so they do not overlap textually, but whichever merges second will need a rebase. No conflict to resolve either way.

ahmad merged commit f685669909 into main

2026-09-09 20:13:36 +00:00

ahmad deleted branch feature/78-template-deploy-header

2026-09-09 20:13:36 +00:00

ahmad referenced this pull request from a commit

2026-09-09 20:13:37 +00:00

docs: Stop tying deploy-vps to a traefik edge (#83)