The 🧪 Sandbox settings block

Business view

Every pull request in this repo gets its own disposable, fully working copy of Dentolize — a real web app, API, and database, seeded with demo data — so anyone can click through a change before it merges. That preview environment has a handful of knobs (do we need the extra Saudi-region stack? the WhatsApp integration? a full demo dataset or a fast minimal one? scheduled jobs on or off?). Those knobs already existed; this PR just puts the control panel where every PR author will actually see it, pre-set to sensible defaults, with each option explained in a one-line comment.

Nobody has to do anything differently. If you never touch the block, your sandbox behaves exactly as it did the day before this PR — same regions, same seed, same everything — with one small addition: your sandbox's app containers now always get an IS_SANDBOX=true variable, because that's baked into the template's default env entry.

Technical view

The block itself

Added at .github/PULL_REQUEST_TEMPLATE.md:9-27 (the diff is fully reproduced below — this is the entire change in this PR):

two_regions: false    # regional branches only — also bring up the ME-1 region + its own S3 mock
whatsapp: false       # bring up the whatsapp-official service
cron: true            # run scheduled jobs (set false for a frozen dataset)
seed: rich            # rich = full demo dataset · basic = minimal seed
env:                  # extra environment variables for the app containers
  IS_SANDBOX: "true"

It sits under a ## 🧪 Sandbox heading with an HTML comment above the fenced block explaining the semantics (visible in the template source, not rendered in the PR body).

Where each key is consumed

The block is plain YAML in the PR description — GitHub doesn't do anything special with it. It only becomes meaningful because .github/workflows/sandbox.yml looks for it. That workflow (unchanged by this PR — it already handled this block before the template existed) does the following, in order:

1. Extract — an awk program (sandbox.yml:97-103) pulls out the first

fenced code block that follows a heading containing "sandbox" (case-insensitive), from the live PR body.

1. Convert — if a block was found and yq is on the runner, it's piped

through yq -p yaml -o json (sandbox.yml:104-105) into a JSON file. If no block exists, or yq isn't available, the settings file is just {} — i.e., every key falls back to whatever the sandbox CLI's own defaults are.

1. Consume — the resulting file is exported as SANDBOX_SETTINGS_FILE

and read by /opt/homelab/sandbox/bin/sandbox … deploy (sandbox.yml:109, 128). That CLI binary lives on the self-hosted runner, outside this repository, so its exact handling of each key (two_regions, whatsapp, cron, seed, env) is not something this repo's source can verify — the workflow only guarantees the JSON gets passed through.

env.IS_SANDBOX specifically

This is the one key whose default value is new behavior, not just newly documented behavior:

• Before this PR: a PR opened with no ## 🧪 Sandbox block in its

description → SANDBOX_SETTINGS_FILE is {} → no env overrides are passed to the deploy → app containers get no IS_SANDBOX variable.

• After this PR: a PR opened without editing the template → the template's

own text (which now includes the block) becomes the PR body → the awk extractor finds it → env.IS_SANDBOX parses to the string "true" → the deploy passes IS_SANDBOX=true into the server/queue/cron containers.

The PR description calls out that this was verified end-to-end against the workflow's exact parser: two_regions=false, cron=true, seed=rich, env.IS_SANDBOX="true", with IS_SANDBOX staying a YAML string (quoted) so it doesn't get coerced to a boolean during the YAML→JSON conversion — Python / JS truthiness would otherwise turn an unquoted true into True or a native boolean depending on the consumer, which could break a shell export IS_SANDBOX=$value expecting the literal text true.

Gap between code and docs: as of this diff, grep -rn IS_SANDBOX across packages/ in this repo returns no matches — nothing in the Dentolize application code (server, clinic-web, clinic-mobile, etc.) reads this variable yet. It's plumbed through the sandbox deploy path but not consumed by the app. Treat it as a hook for future sandbox-aware behavior, not something currently observable from inside the running app.

two_regions and the auth-server precondition

The inline comment states two_regions only applies to "regional branches (those with packages/auth-server)". This repo's current worktree has no packages/auth-server directory, so on this branch the flag is inert regardless of its value — consistent with the sandbox.yml:290-292 logic that only renders regional-stack messaging (AUTH_URL, API_ME_URL, ME-1 S3 console) when the deploy actually produced a regional stack.