mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-13 23:25:18 +00:00
refactor(OPS102): fixes do /simplify — comentários vivos alinhados, pin do exit 0 com mais dentes, runbook/changelog precisos
This commit is contained in:
Francisco Solla
parent
c9bd627de4
commit
907b9ba96b
5 changed files with 21 additions and 17 deletions
6
.github/workflows/deploy.yml
vendored
6
.github/workflows/deploy.yml
vendored
|
|
@ -21,9 +21,9 @@
|
|||
# deploy-homeserver.sh) and serialized by flock on the homeserver.
|
||||
#
|
||||
# The `deploy` job fetches the repo from github.com (public) — TEQO_REPO_URL
|
||||
# in deploy-homeserver.sh now defaults there; the script deploys the
|
||||
# dispatched SHA to the end even if main advances during verify (OPS102 —
|
||||
# deliberate dispatch; idempotency is the "already deployed" guard).
|
||||
# in deploy-homeserver.sh now defaults there; the script runs to completion
|
||||
# for the dispatched SHA even if main advances during verify (OPS102 —
|
||||
# publishing is a deliberate operator act).
|
||||
|
||||
name: Deploy (manual)
|
||||
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
**OPS102 — Deploy manual roda até o fim mesmo com `main` à frente (2026-09-12):** o guard de stale run nasceu na era automática (OPS53): `scripts/deploy-homeserver.sh` comparava `git ls-remote … refs/heads/main` com o SHA do job (pré e pós-`flock`) e abortava com `fatal "stale run"`. Desde a OPS71 o publish é um `workflow_dispatch` deliberado — se alguém mergeasse em `main` durante os ~50 min do `verify`, o job `deploy` morria mesmo com o dispatch legítimo. O fix remove os dois blocos (o `flock` e o guard "already deployed" ficam; o único verde sem build segue sendo o que prova que o container já roda o SHA) e realinha o registro vivo: comentários do script e do `deploy.yml`, fluxo e tabela "Falhas conhecidas" do runbook (`docs/ops/teqo-1313-deploy.md` — a linha do antigo "stale run" vira o risco aceito de dispatch fora de ordem, com gatilho de revisita) e `docs/AGENT-OPS.md`. `tests/unit/deployScript.unit.spec.ts` passa a pinar o contrato novo: ausência de `git ls-remote`/`refs/heads/main`/`stale run`, único `exit 0` = "already deployed" (anti-falso-verde #953) e `flock` preservado (RED comprovado contra o script anterior). Sem migration, sem UI, sem access/Consent. Verificação: `pnpm gate:fast` verde; e2e não afetado (diff sem superfície runtime). Aceite final humano pós-merge: dispatch manual do `deploy.yml`.
|
||||
**OPS102 — Deploy manual roda até o fim mesmo com `main` à frente (2026-09-12):** o guard de stale run nasceu na era automática (OPS53): `scripts/deploy-homeserver.sh` comparava `git ls-remote … refs/heads/main` com o SHA do job (pré e pós-`flock`) e abortava com `fatal "stale run"`. Desde a OPS71 o publish é um `workflow_dispatch` deliberado — se alguém mergeasse em `main` durante os ~50 min do `verify`, o job `deploy` morria mesmo com o dispatch legítimo. O fix remove os dois blocos (o `flock` e o guard "already deployed" ficam; o único verde sem build segue sendo o que prova que o container já roda o SHA) e realinha o registro vivo: comentários do script e do `deploy.yml`, fluxo e tabela "Falhas conhecidas" do runbook (`docs/ops/teqo-1313-deploy.md` — a linha do antigo "stale run" vira o risco aceito de dispatch fora de ordem, com gatilho de revisita) e `docs/AGENT-OPS.md`. `tests/unit/deployScript.unit.spec.ts` passa a pinar o contrato novo: ausência de `git ls-remote`/`refs/heads/main`/`stale run` (pins de ausência com RED comprovado contra o script anterior), único `exit 0` = "already deployed" (anti-falso-verde #953) e `flock` preservado. Sem migration, sem UI, sem access/Consent. Verificação: `pnpm gate:fast` verde; e2e não afetado (diff sem superfície runtime). Aceite final humano pós-merge: dispatch manual do `deploy.yml`.
|
||||
|
|
|
|||
|
|
@ -19,8 +19,9 @@ homeserver, o job `verify` (hosted) roda a suíte **full** (incl. e2e full).
|
|||
conta minutos hosted).
|
||||
4. O script, no **homeserver**: `flock` (serializa os dispatches; desde a
|
||||
OPS102 o run vai até o fim com o SHA do dispatch mesmo se `main` avançar
|
||||
durante o verify) → guard "already deployed" (revision do container
|
||||
rodando) → **build do migrator**
|
||||
durante o verify; o workspace é clonado/atualizado de `TEQO_REPO_URL` —
|
||||
default `https://github.com/fsolla/teqo.git`, público) → guard "already
|
||||
deployed" (revision do container rodando) → **build do migrator**
|
||||
(o estágio migrator não roda `next build` — builda mesmo contra o schema
|
||||
antigo; BuildKit, secrets do `~/stack/teqo-1313.env`) → push do migrator em
|
||||
`localhost:5000` (tag **qualificada de registry** — INF13: a única ref que o
|
||||
|
|
@ -129,7 +130,7 @@ a correção se re-mergeia e o próximo deploy completo publica.
|
|||
|
||||
| Sintoma | Causa | Tratamento |
|
||||
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Dispatch fora de ordem (SHA antigo re-dispatchado depois de um deploy mais novo) | O `flock` serializa mas não ordena; o "already deployed" não pega revision diferente | Não re-dispatchar SHA antigo; se acontecer, re-dispatchar o `main` atual (rollback manual disponível na seção Rollback). Revisitar se o deploy ganhar frequência/automação ou se uma regressão fora-de-ordem acontecer |
|
||||
| Prod regride para um SHA antigo após re-dispatch fora de ordem | O `flock` serializa mas não ordena; o "already deployed" não pega revision diferente | Não re-dispatchar SHA antigo; se acontecer, re-dispatchar o `main` atual (rollback manual disponível na seção Rollback). Revisitar se o deploy ganhar frequência/automação ou se uma regressão fora-de-ordem acontecer |
|
||||
| Job verde sem deploy ("already deployed") | O container rodando já tem a revision do SHA do job (ex.: `workflow_dispatch` duplicado da mesma HEAD) | Nada a fazer — o site já roda esse SHA. Forçar rebuild da MESMA HEAD não é suportado via dispatch: edite o tag da imagem no compose (`image: localhost:5000/teqo-1313:<sha>-rebuild`) e `docker compose up -d`, ou espere um commit novo |
|
||||
| Job `deploy` nunca roda / runner offline | Runner self-hosted do homeserver não instalado ou parado (passo manual do cutover OPS71) | Instalar/religar o runner (labels `self-hosted`, `homeserver`); os PRs e o `verify` não dependem dele — só o deploy |
|
||||
| Deploy dispara mas o job `verify` falha | Regressão real na suíte full | Corrigir e re-dispatchar — o homeserver nunca é tocado |
|
||||
|
|
|
|||
|
|
@ -8,13 +8,16 @@
|
|||
# (The Forgejo-era invocation `ssh homeserver "bash -s -- <sha>" < script`
|
||||
# is gone — no SSH hop, no workstation involvement.)
|
||||
#
|
||||
# Flow: flock serialization (a manual dispatch runs to the end with its SHA
|
||||
# even if main advances during verify — OPS102; the idempotency guard below
|
||||
# is the only early green, and it proves the SHA is already running) ->
|
||||
# workspace fetch at <sha> -> docker login (local registry)
|
||||
# -> build of the MIGRATOR stage (it never runs `next build`, so it builds
|
||||
# even against the old schema) -> push of the migrator (registry-qualified
|
||||
# tag — INF13: the ONLY ref the compose references) -> compose image-tag swap
|
||||
# OPS102: a manual dispatch runs to the end with its SHA even if main advances
|
||||
# during verify (the old stale-run guard belonged to the automatic era); the
|
||||
# only early green is the idempotency guard, which proves the SHA is already
|
||||
# running.
|
||||
#
|
||||
# Flow: flock serialization -> workspace fetch at <sha> -> docker login
|
||||
# (local registry) -> build of the MIGRATOR stage (it never runs `next
|
||||
# build`, so it builds even against the old schema) -> push of the migrator
|
||||
# (registry-qualified tag — INF13: the ONLY ref the compose references) ->
|
||||
# compose image-tag swap
|
||||
# (with backup) -> migrate via the maintenance service
|
||||
# (BEFORE the runner build — static generation reads the NEW schema, OPS66)
|
||||
# -> build of the runner stage (BuildKit secrets, compose network) ->
|
||||
|
|
@ -51,8 +54,8 @@ exec 9>"$DEPLOY_LOCK"
|
|||
flock -w 3600 9 || fatal "another deploy holds $DEPLOY_LOCK"
|
||||
|
||||
# --- idempotency (OPS65) ------------------------------------------------
|
||||
# A 30-min main window can re-deliver a SHA the cluster already runs (e.g. a
|
||||
# duplicate workflow_dispatch): rebuilding it is a ~15 min no-op. The truth
|
||||
# A duplicate workflow_dispatch can re-deliver a SHA the cluster already runs:
|
||||
# rebuilding it is a ~15 min no-op. The truth
|
||||
# is the RUNNING container's revision label — the compose file can lie after
|
||||
# a failed rollback (it is swapped before the rollout and restored best-
|
||||
# effort). A container without the label (or down) counts as "not deployed":
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ describe('scripts/deploy-homeserver.sh (OPS53 deploy pipeline)', () => {
|
|||
it('never exits green without deploying: the only early exit 0 is "already deployed"', () => {
|
||||
// #953: the stale-run skip used to `exit 0` — a green deploy that never
|
||||
// happened while prod stayed on an older image.
|
||||
expect(script.match(/^\s*exit 0\s*$/gm) ?? []).toHaveLength(1)
|
||||
expect(script.match(/\bexit 0\b/g) ?? []).toHaveLength(1)
|
||||
})
|
||||
|
||||
it('keeps flock serialization after removing the HEAD guards (OPS102)', () => {
|
||||
|
|
|
|||
Loading…
Reference in a new issue