Dentolize · Foreground update-docs Walkthrough
On this pageThe change under test (facts, verified in the repo)Gaps between the PR description and the code (document the code)Test matrixEdge cases & things to watchDefinition of done for QA sign-off

For Quality

What to test, where the edges are, and — most importantly — where the PR description and the code disagree. This is a CI-workflow change, so "testing" means dispatching real workflow runs and reading logs/behavior, not clicking product UI.

The change under test (facts, verified in the repo)

Only .github/workflows/sandbox-ops.yml changes:

  1. timeout-minutes: 30 → 90 (:47).
  2. update-docs command: sandbox-docs … refresh --detach → `sandbox-docs …

refresh — the --detach flag is removed (:65`).

  1. Comment text updated to explain foreground execution (:45–47, :62–64).

Everything else in the file — the action list, concurrency, the info-capture guard (:67), and the PR-comment step guard (:72) — is unchanged.

Gaps between the PR description and the code (document the code)

Gap 1 — The second runner slot is not in this diff

The PR body says "a second self-hosted runner slot is now online" and the new code comment says "A second runner slot keeps PR deploys unblocked meanwhile" (.github/workflows/sandbox-ops.yml:62). Nothing in this repository provisions or proves that slot — it's homelab infrastructure. The whole safety argument for foregrounding (long job won't block deploys) rests on that slot existing. Verify out-of-band that two runners with labels [self-hosted, homelab, dentolize] are registered and online before relying on this.

Gap 2 — A neighboring comment now contradicts the new reality

.github/workflows/sandbox-qa.yml:18–19 still states: "the single-slot self-hosted runner cannot run a deploy while this job holds it." If a second slot is genuinely online, that comment is stale/misleading. This PR does not touch it. Flag as documentation drift; consider a follow-up.

Gap 3 — "generating… → live" PR comments aren't in the code

The PR body says PR-open auto-generation is fine detached because "the PR status comments — 'generating…' → 'live' — cover it." But sandbox.yml's comment builder writes a single static docs line (.github/workflows/sandbox.yml:95): **Docs:** https://<slug>.docs… (AI walkthrough — generates after PR open…). There is no generating→live state machine for docs in the shown code. Don't rely on such comments existing.

Gap 4 — refresh "deploys a missing sandbox first" is unverifiable here

The comment claims a docs refresh may "deploy a missing sandbox first" (:45–46), justifying the ~1h/90-min ceiling. That behavior lives inside the sandbox-docs CLI at /opt/homelab/sandbox/bin/sandbox-docs, which is not in this repo. Treat the timing claim as unverified from source; confirm by running update-docs on a branch that has no sandbox.

Test matrix

#ScenarioStepsExpected
1Happy path refreshDispatch Sandbox Ops update-docs on a branch with an existing sandboxJob stays open, streams agent activity, goes green when site published; site at <slug>.docs.anastawfik.com is updated
2No sandbox yetupdate-docs on a branch whose sandbox was destroyedJob deploys sandbox first, then docs; may approach ~1h; still under 90-min timeout
3No PR commentAfter scenario 1, inspect the PR threadNo sandbox comment created/updated by update-docs (guards at :67, :72)
4Timeout ceilingForce a very long/stuck runJob cancelled at 90 min, not 30
5Deploy not blockedStart update-docs, then push a commit to another PRThe other PR's sandbox.yml deploy gets a runner slot and proceeds (needs 2nd slot)
6ConcurrencyDispatch update-docs twice on the same branchSecond waits; cancel-in-progress: false (:35–36) means the first is not cancelled
7Auto-gen untouchedOpen a fresh PRsandbox.yml still runs generate --detach (:66); job returns fast; docs appear later
8Other ops untouchedRun reseed/redeploy/destroyBehave exactly as before; comment step still fires for these
9Failure visibilityCause the agent to fail mid-runFailure appears in the job log and the job goes red (the core value)

Edge cases & things to watch

  • Runner starvation regression: if the second slot is not online, a

foreground docs job will serialize behind/ahead of PR deploys on the single slot — reintroducing the exact blocking this PR claims to avoid. Scenario 5 is the guard.

  • Queued vs. running: a job waiting for a slot looks "stuck" but is just

queued. Distinguish in the Actions UI.

  • GITHUB_TOKEN scope: the job runs with contents: read,

pull-requests: write, issues: write (:38–41). update-docs doesn't comment, so the write scopes are unused on that path — harmless but worth noting.

  • Non-cancelling concurrency: update-docs won't be interrupted by a repeat

dispatch, so double-clicking queues a second full run rather than replacing.

Definition of done for QA sign-off

  • [ ] Scenarios 1–9 pass.
  • [ ] Two runners confirmed online (Gap 1).
  • [ ] Decision recorded on the stale sandbox-qa.yml comment (Gap 2).
  • [ ] Timing claims (Gap 4) observed at least once on a real no-sandbox branch.