@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +310 -3
  3. package/README.vi.md +280 -0
  4. package/audit/audit.mjs +3035 -0
  5. package/package.json +26 -5
  6. package/templates/README.md +257 -0
  7. package/templates/adr-README.md +57 -0
  8. package/templates/branch-name.yml +51 -0
  9. package/templates/ci-laravel.yml +540 -0
  10. package/templates/ci-node.yml +291 -0
  11. package/templates/ci-python.yml +281 -0
  12. package/templates/deploy-xserver.yml +531 -0
  13. package/templates/dist-refs.yml +177 -0
  14. package/templates/docs-lint.mjs +993 -0
  15. package/templates/docs-lint.yml +55 -0
  16. package/templates/gotchas-d-README.md +41 -0
  17. package/templates/identity-vocabulary.example +58 -0
  18. package/templates/npx-launcher.mjs +213 -0
  19. package/templates/pre-commit-dispatch +88 -0
  20. package/templates/pre-commit-identity +267 -0
  21. package/templates/pre-push-guard +137 -0
  22. package/templates/release-auto.yml +475 -0
  23. package/templates/release-tag.yml +245 -0
  24. package/templates/repo-CLAUDE-block.md +21 -0
  25. package/tools/colab +13790 -0
  26. package/tools/lib/adopt.js +882 -0
  27. package/tools/lib/axis-authority.js +96 -0
  28. package/tools/lib/base-ci-verdict.js +93 -0
  29. package/tools/lib/blocked-by.js +262 -0
  30. package/tools/lib/branch-name.js +137 -0
  31. package/tools/lib/checklist.js +143 -0
  32. package/tools/lib/ci-cure.js +512 -0
  33. package/tools/lib/ci-grant.js +307 -0
  34. package/tools/lib/ci-verdict.js +113 -0
  35. package/tools/lib/claim-comments.js +212 -0
  36. package/tools/lib/claim-identity.js +195 -0
  37. package/tools/lib/codeowners.js +208 -0
  38. package/tools/lib/consumer-evidence.js +74 -0
  39. package/tools/lib/container-close.js +141 -0
  40. package/tools/lib/cure-diff.js +267 -0
  41. package/tools/lib/decision-record.js +335 -0
  42. package/tools/lib/dirty-owner.js +150 -0
  43. package/tools/lib/disposition.js +378 -0
  44. package/tools/lib/docs-only.js +156 -0
  45. package/tools/lib/exposure-shape.js +207 -0
  46. package/tools/lib/gate.js +80 -0
  47. package/tools/lib/git.js +1059 -0
  48. package/tools/lib/group-labels.js +120 -0
  49. package/tools/lib/hermetic.js +193 -0
  50. package/tools/lib/identity.js +187 -0
  51. package/tools/lib/install-check.js +259 -0
  52. package/tools/lib/instruction-file.js +302 -0
  53. package/tools/lib/journal.js +430 -0
  54. package/tools/lib/labels.js +653 -0
  55. package/tools/lib/landed.js +230 -0
  56. package/tools/lib/local-adopt.js +133 -0
  57. package/tools/lib/lockfile-drift.js +119 -0
  58. package/tools/lib/machine-trailer.js +83 -0
  59. package/tools/lib/machine.js +238 -0
  60. package/tools/lib/migration-grant.js +641 -0
  61. package/tools/lib/migration-paths.js +135 -0
  62. package/tools/lib/notify.js +188 -0
  63. package/tools/lib/npm-publish-guard.js +242 -0
  64. package/tools/lib/orphan-worktree.js +127 -0
  65. package/tools/lib/owner-branch.js +182 -0
  66. package/tools/lib/place.js +782 -0
  67. package/tools/lib/ports.js +167 -0
  68. package/tools/lib/procs.js +185 -0
  69. package/tools/lib/readiness.js +240 -0
  70. package/tools/lib/records.js +185 -0
  71. package/tools/lib/refs-brake.js +95 -0
  72. package/tools/lib/release-channel.js +99 -0
  73. package/tools/lib/release-cut.js +822 -0
  74. package/tools/lib/release-finalize.js +521 -0
  75. package/tools/lib/release-policy.js +358 -0
  76. package/tools/lib/release-tag.js +225 -0
  77. package/tools/lib/ship-batch.js +277 -0
  78. package/tools/lib/ship-roles.js +71 -0
  79. package/tools/lib/ship-target-sync.js +181 -0
  80. package/tools/lib/shipguard.js +317 -0
  81. package/tools/lib/shipped-branch.js +56 -0
  82. package/tools/lib/solo.js +213 -0
  83. package/tools/lib/squash.js +515 -0
  84. package/tools/lib/stale-base.js +70 -0
  85. package/tools/lib/stamp.js +740 -0
  86. package/tools/lib/state.js +262 -0
  87. package/tools/lib/teardown.js +83 -0
  88. package/tools/lib/trust-humans.js +104 -0
  89. package/tools/lib/util.js +98 -0
  90. package/tools/lib/wake.js +188 -0
  91. package/tools/lib/workflow-triggers.js +273 -0
  92. package/tools/lib/writes-authority.js +237 -0
  93. package/tools/lib/yaml.js +101 -0
  94. package/bin/cli.js +0 -3
@@ -0,0 +1,531 @@
1
+ # Deploy (SSH/rsync to shared hosting) — TEMPLATE. Copy me into your repo at .github/workflows/deploy-xserver.yml.
2
+ #
3
+ # This is a starting point, not a dependency. Once you copy it, YOU OWN THIS FILE.
4
+ # Edit it freely: rename jobs, add steps, drop the parts you do not need. Nothing
5
+ # calls this file remotely and nothing will update it for you — divergence between
6
+ # your copy and the handbook is expected and fine. If you find an improvement worth
7
+ # sharing, change the handbook template too, but that is a manual, deliberate act.
8
+ #
9
+ # EDIT POINTS are marked `# EDIT:` — walk them once after copying.
10
+ #
11
+ # For: a PHP-framework + Vite fullstack app deployed to SHARED HOSTING over SSH —
12
+ # no root, no Docker, no container registry. The release is built on a runner
13
+ # and rsynced into a directory in the hosting account's home; a docroot symlink
14
+ # points the web server at the app's `public/`. Database migrations then run
15
+ # ON THE SERVER, against production.
16
+ #
17
+ # NOT for: anything with a container runtime or an orchestrator on the far side
18
+ # (build an image and push it instead); static sites (no server step to run);
19
+ # any host you cannot reach over SSH from the runner.
20
+ #
21
+ # ─────────────────────────────────────────────────────────────────────────────
22
+ # THIS FILE DOES NOT CHANGE YOUR REPO'S TIER.
23
+ #
24
+ # Tier counts the gates between a merge and users; it is declared in
25
+ # `.github/project.yml` and changed only by the checklist in CONVENTIONS.md §9.
26
+ # Copying a deploy workflow in is not that checklist. Concretely:
27
+ #
28
+ # - A tag push only deploys where `deploy: tag` is declared. If your repo says
29
+ # `deploy: manual`, adopting this file is the moment to change that field
30
+ # deliberately (and drop the now-false `runbook:`), NOT a side effect of the
31
+ # copy. Until you do, the two disagree and the audit will say so.
32
+ # - Tier B repos have no production at all. If you are copying this into one,
33
+ # stop: you are changing what the repo IS, which is a deliberate decision with
34
+ # its own checklist, not a workflow file.
35
+ #
36
+ # SECRETS ARE NAMED HERE, NEVER VALUED.
37
+ #
38
+ # - `secrets.DEPLOY_SSH_KEY` — the private key that logs into the hosting
39
+ # account. ONE KEY PER REPO. Do not share a key between repos that deploy to
40
+ # the same account: a leak from any one of them then reaches all of them, and
41
+ # you cannot rotate one without breaking the rest.
42
+ # - `vars.DEPLOY_KNOWN_HOSTS` (optional) — see the "Setup SSH" step. Without it
43
+ # the host key is learned at run time, which is trust-on-first-use ON EVERY
44
+ # RUN rather than genuine host verification.
45
+ #
46
+ # Nothing else is secret. The host, port, user and paths below are configuration:
47
+ # keep them in the `env:` block where a reviewer can see them, or move them to
48
+ # repo variables if this repo is public and you would rather not publish them.
49
+ #
50
+ # ─────────────────────────────────────────────────────────────────────────────
51
+ # SELF-HOSTED RUNNER — the assumptions that differ from a hosted one.
52
+ #
53
+ # Many shared hosts restrict SSH to domestic IP ranges, which a hosted runner in
54
+ # another region cannot satisfy; a runner inside the right region can. If that is
55
+ # why you are on a self-hosted runner, three things follow and this file depends
56
+ # on all of them:
57
+ #
58
+ # 1. THE WORKSPACE IS NOT CLEAN BETWEEN RUNS. Files a previous run left behind
59
+ # are still there — including a previous `.env` and previous build output.
60
+ # Every step here either overwrites what it needs or is explicitly idempotent,
61
+ # and the final cleanup runs `if: always()`. Do not add a step that assumes
62
+ # an empty directory.
63
+ # 2. TOOL VERSIONS ARE WHATEVER THE BOX HAS. The runner's native PHP and
64
+ # Composer are used as-is — there is no setup-php step. If the box's PHP does
65
+ # not satisfy the app's `require.php`, the build fails here rather than in
66
+ # production, which is the correct place; fix the box, do not pin around it.
67
+ # Node IS installed per-run, at the version this repo declares (below).
68
+ # 3. BILLING OUTAGES DO NOT STOP IT. A hosted-runner billing lock halts every
69
+ # `ubuntu-latest` job in the org while this keeps deploying. That is a
70
+ # feature, and also a hazard: your CI can be silently dead while deploys
71
+ # still succeed. Check CI is alive before you release, not just green.
72
+ #
73
+ # On a hosted runner instead: change `runs-on`, and add a setup-php step, because
74
+ # assumption 2 no longer holds.
75
+ #
76
+ # ─────────────────────────────────────────────────────────────────────────────
77
+ # ONE-TIME SERVER PREPARATION — none of this is automated, and the first deploy
78
+ # fails without it. Copy this checklist into the repo's deploy runbook and tick it:
79
+ #
80
+ # [ ] Hosting panel: subdomain created, on the PHP version pinned in PHP_BIN below.
81
+ # [ ] Hosting panel: TLS certificate issued for that subdomain.
82
+ # [ ] Hosting panel: database + user created, granted on that database only.
83
+ # [ ] DNS record pointing at the host (some panels only issue a certificate once
84
+ # the name resolves to them directly — i.e. not behind a proxy).
85
+ # [ ] `<APP_DIR>/.env` written on the server, mode 600. It lives ONLY there:
86
+ # the rsync below excludes it, so it is never overwritten and never comes
87
+ # from the repo. Production values, `APP_DEBUG=false`, a generated app key.
88
+ # [ ] Deploy public key appended to the hosting account's `~/.ssh/authorized_keys`,
89
+ # its private half stored as this repo's `DEPLOY_SSH_KEY` secret.
90
+ # [ ] Scheduler / queue cron entries registered in the panel, IF the app has any
91
+ # scheduled tasks or queued jobs. It probably does not on day one — add them
92
+ # when it does, and wrap the queue worker in `flock` so a slow run cannot
93
+ # overlap the next tick.
94
+ # [ ] First deploy only: seed whatever an empty database needs, then immediately
95
+ # rotate any password the seeder hardcoded.
96
+ # ─────────────────────────────────────────────────────────────────────────────
97
+
98
+ name: Deploy # EDIT: name it after the environment, e.g. "Deploy to production".
99
+
100
+ on:
101
+ push:
102
+ tags:
103
+ # EDIT: only if your tag convention differs. This trigger is what makes
104
+ # `deploy: tag` true — a tag is the deploy, a branch push is not.
105
+ - "v*.*.*"
106
+ workflow_dispatch:
107
+ inputs:
108
+ ref:
109
+ description: "Branch/tag/SHA to deploy (defaults to the triggering ref)"
110
+ required: false
111
+ default: ""
112
+
113
+ # Serialise deploys, and NEVER cancel one in flight: a cancelled run can leave the
114
+ # server rsynced but not migrated, which is the one state nothing recovers from
115
+ # automatically. A queued second deploy is cheap; a half-applied one is not.
116
+ concurrency:
117
+ group: deploy-${{ github.repository }}
118
+ cancel-in-progress: false
119
+
120
+ env:
121
+ # EDIT: every value in this block. This is the ONLY place per-repo configuration
122
+ # belongs — no step below hardcodes any of it, so adopting a later version of
123
+ # this template stays a small, readable diff.
124
+ #
125
+ # On a public repo you may prefer not to publish the host: replace with
126
+ # `${{ vars.DEPLOY_HOST }}` and set it as a repo variable. Variables are not
127
+ # secrets — they are for reducing noise, not for hiding credentials.
128
+ SSH_HOST: deploy.example.net
129
+ SSH_PORT: "22"
130
+ SSH_USER: deployuser
131
+ # Path RELATIVE to the SSH user's home directory.
132
+ APP_DIR: apps/myapp
133
+ # Absolute path of the docroot the web server serves. The reconcile step keeps
134
+ # this a symlink to $APP_DIR/public on every deploy.
135
+ DOCROOT_LINK: /home/deployuser/example.com/public_html/app.example.com
136
+ # Absolute path to the PHP binary ON THE SERVER. Shared hosts install several
137
+ # versions side by side and the default `php` on the SSH path is frequently NOT
138
+ # the one the web server runs. Pin the one that matches the domain's FPM
139
+ # version — otherwise migrations run under a different PHP than the site does.
140
+ PHP_BIN: /opt/php-8.4/bin/php
141
+ # EDIT: match the app's display name, or leave empty if the build does not read it.
142
+ VITE_APP_NAME: ""
143
+ # EDIT: arguments passed to the build-time route/codegen command.
144
+ WAYFINDER_ARGS: "--with-form"
145
+ # EDIT: the URL the smoke test asks. Must be the PUBLIC url, not the host above.
146
+ SMOKE_URL: https://app.example.com/
147
+ # EDIT: HTTP codes that mean "the app booted". 302 is here because an app behind
148
+ # auth redirects to its login page — that is a live app, not a failure.
149
+ SMOKE_OK_CODES: "200 302"
150
+
151
+ jobs:
152
+ deploy:
153
+ name: Build & deploy
154
+ # EDIT: your runner label. See the SELF-HOSTED RUNNER note in the header —
155
+ # this file assumes PHP and Composer already exist on the box.
156
+ runs-on: [self-hosted, Linux, X64]
157
+ steps:
158
+ - name: Checkout
159
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
160
+ with:
161
+ ref: ${{ github.event.inputs.ref || github.ref }}
162
+ # No credentials left in .git/config — on a self-hosted runner the
163
+ # workspace outlives the job.
164
+ persist-credentials: false
165
+
166
+ # -------------------------------------------------------------------------
167
+ # Toolchain resolution. Precedence, highest first:
168
+ # Node: 1. .github/project.yml -> node: 2. .nvmrc, else package.json engines.node
169
+ # ...and if neither declares it, FAIL.
170
+ #
171
+ # There is deliberately NO fallback default, and a DEPLOY workflow is where
172
+ # that rule was learned the hard way: every hand-written ancestor of this
173
+ # template hardcoded its Node version here. One of them was fixed when its CI
174
+ # turned out to build on a different major than this file deployed on — CI
175
+ # was green and proved nothing about what shipped. The other copies stayed
176
+ # wrong, because there was no template and therefore no way to see it.
177
+ #
178
+ # Reading the same declaration CI reads is the entire point. Do not replace
179
+ # this with a literal, however obvious the version seems today.
180
+ # -------------------------------------------------------------------------
181
+ - name: Resolve deploy toolchain
182
+ id: toolchain
183
+ run: |
184
+ set -euo pipefail
185
+
186
+ # "^8.3" / ">=22.1" / "v22" / "8.4.*" -> "8.3" / "22.1" / "22" / "8.4"
187
+ normalise() {
188
+ printf '%s' "$1" \
189
+ | tr -d '"' \
190
+ | sed -E 's/^[^0-9]*//' \
191
+ | sed -E 's/[[:space:]].*$//' \
192
+ | sed -E 's/\.(x|\*)$//' \
193
+ | sed -E 's/[^0-9.].*$//' \
194
+ | sed -E 's/\.$//'
195
+ }
196
+
197
+ # Read a flat `key: value` out of .github/project.yml. That file is a
198
+ # handful of top-level keys by design, so this is sufficient.
199
+ from_project_yml() {
200
+ [ -f .github/project.yml ] || return 0
201
+ sed -nE "s/^[[:space:]]*$1:[[:space:]]*\"?([^\"#[:space:]]+)\"?.*/\1/p" .github/project.yml | head -1
202
+ }
203
+
204
+ # --- Node (used to build the assets that ship) --------------------------
205
+ NODE_VERSION=""; NODE_SOURCE=""
206
+ V="$(from_project_yml node || true)"
207
+ if [ -n "$V" ] && [ "$V" != "null" ]; then
208
+ NODE_VERSION="$(normalise "$V")"; NODE_SOURCE=".github/project.yml (node:)"
209
+ fi
210
+ if [ -z "$NODE_VERSION" ] && [ -f .nvmrc ]; then
211
+ V="$(grep -vE '^[[:space:]]*(#|$)' .nvmrc | head -1 | tr -d '[:space:]' || true)"
212
+ if [ -n "$V" ]; then
213
+ NODE_VERSION="$(normalise "$V")"; NODE_SOURCE=".nvmrc"
214
+ fi
215
+ fi
216
+ if [ -z "$NODE_VERSION" ] && [ -f package.json ]; then
217
+ V=""
218
+ if command -v node >/dev/null 2>&1; then
219
+ V="$(node -e "try{const e=require('./package.json').engines||{};process.stdout.write(String(e.node||''))}catch(_){}" || true)"
220
+ elif command -v python3 >/dev/null 2>&1; then
221
+ V="$(python3 -c "import json;print((json.load(open('package.json')).get('engines') or {}).get('node') or '')" || true)"
222
+ fi
223
+ if [ -n "$V" ]; then
224
+ NODE_VERSION="$(normalise "$V")"; NODE_SOURCE="package.json (engines.node)"
225
+ fi
226
+ fi
227
+ if [ -z "$NODE_VERSION" ]; then
228
+ echo "::error::No Node version is declared in this repository, and this workflow refuses to guess one."
229
+ {
230
+ echo "Declare it in ONE of:"
231
+ echo " 1. .github/project.yml -> node: \"22\" (preferred)"
232
+ echo " 2. .nvmrc -> 22 or package.json -> \"engines\": { \"node\": \">=22\" }"
233
+ echo "Declare the SAME version CI builds with, or CI proves nothing about this deploy."
234
+ } >&2
235
+ exit 1
236
+ fi
237
+
238
+ # --- PHP: cross-check the SERVER binary against the declaration ---------
239
+ # PHP is NOT installed here (the runner's own PHP builds the release, see
240
+ # the header). What this checks is subtler and has no equivalent in CI:
241
+ # PHP_BIN names a specific interpreter on the far side, so a repo can
242
+ # declare one PHP version, test on it, and then migrate production with a
243
+ # different one — no error anywhere, just two PHPs. If the pinned path
244
+ # carries a version number, it must agree with the declaration.
245
+ PHP_DECLARED="$(from_project_yml php || true)"
246
+ if [ -n "$PHP_DECLARED" ] && [ "$PHP_DECLARED" != "null" ]; then
247
+ PHP_DECLARED="$(normalise "$PHP_DECLARED")"
248
+ PHP_BIN_VERSION="$(printf '%s' "$PHP_BIN" | sed -nE 's/.*([0-9]+\.[0-9]+).*/\1/p')"
249
+ if [ -z "$PHP_BIN_VERSION" ]; then
250
+ echo "::notice::PHP_BIN ($PHP_BIN) carries no version to check against the declared PHP $PHP_DECLARED — verify by hand that it is the same interpreter the web server runs."
251
+ elif [ "$PHP_BIN_VERSION" != "$PHP_DECLARED" ]; then
252
+ echo "::error::PHP_BIN points at PHP $PHP_BIN_VERSION but this repo declares php: $PHP_DECLARED."
253
+ {
254
+ echo "Production would migrate under a PHP the repo does not claim to support."
255
+ echo "Fix ONE of: the PHP_BIN path in this workflow, or php: in .github/project.yml."
256
+ } >&2
257
+ exit 1
258
+ fi
259
+ fi
260
+
261
+ echo "node-version=$NODE_VERSION" >> "$GITHUB_OUTPUT"
262
+ echo "Node $NODE_VERSION (from: $NODE_SOURCE) / server PHP: $PHP_BIN"
263
+ {
264
+ echo "Node **$NODE_VERSION** — resolved from \`$NODE_SOURCE\`"
265
+ echo ""
266
+ echo "Server PHP — \`$PHP_BIN\`"
267
+ } >> "$GITHUB_STEP_SUMMARY"
268
+
269
+ - name: Setup Node
270
+ uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
271
+ with:
272
+ node-version: ${{ steps.toolchain.outputs.node-version }}
273
+
274
+ - name: Composer install (production, no scripts)
275
+ run: |
276
+ # --no-dev: dev dependencies must not ship. --no-scripts: the
277
+ # post-autoload-dump hook boots the application to discover packages, and
278
+ # it cannot boot against the server's .env from here. The package manifest
279
+ # is therefore regenerated ON THE SERVER after rsync (see reconcile).
280
+ composer install --no-dev --no-interaction --prefer-dist \
281
+ --optimize-autoloader --no-scripts
282
+
283
+ - name: Prepare env for build-time codegen (wayfinder)
284
+ run: |
285
+ # The Vite build shells out to the framework's route-codegen command, so
286
+ # the application must actually BOOT on the runner.
287
+ #
288
+ # Rewrite the database connection to sqlite against an empty file. Do this
289
+ # EVEN IF your .env.example already says sqlite: one ancestor of this
290
+ # template skipped these two lines because its example file happened to
291
+ # use sqlite, which quietly made the deploy depend on a file nobody
292
+ # thought of as deploy configuration. The sed is a no-op when it is
293
+ # already sqlite, and load-bearing the day someone edits .env.example.
294
+ #
295
+ # This .env is disposable and never leaves the runner — the rsync below
296
+ # excludes it. On a self-hosted runner a previous run's .env may still be
297
+ # sitting here, so this overwrites rather than creates.
298
+ cp .env.example .env
299
+ sed -i 's/^DB_CONNECTION=.*/DB_CONNECTION=sqlite/' .env
300
+ touch database/database.sqlite
301
+ php artisan key:generate --force
302
+
303
+ # Print the runner's PHP: when a build fails for version reasons, this is
304
+ # the line that says so immediately.
305
+ echo "=== PHP version on runner ==="
306
+ php -v
307
+
308
+ # Run codegen explicitly rather than letting the Vite plugin invoke it.
309
+ # The plugin swallows stderr and reports only "Command failed", which is
310
+ # unusable; run it here and a codegen failure shows its real error.
311
+ echo "=== wayfinder:generate (stderr visible) ==="
312
+ php artisan wayfinder:generate $WAYFINDER_ARGS
313
+
314
+ - name: Build frontend assets (Vite)
315
+ run: |
316
+ npm ci
317
+ npm run build
318
+
319
+ # SSH material is created HERE, after the build, not at the top of the job:
320
+ # it exists on disk for the shortest window that still works. On a shared
321
+ # self-hosted runner that window is the exposure.
322
+ - name: Setup SSH
323
+ run: |
324
+ # Key + known_hosts live in RUNNER_TEMP, which is removed after the job —
325
+ # never in ~/.ssh, which on a self-hosted runner is shared with every
326
+ # other job on the box.
327
+ install -m 700 -d "$RUNNER_TEMP/ssh"
328
+ printf '%s\n' "${{ secrets.DEPLOY_SSH_KEY }}" > "$RUNNER_TEMP/ssh/id_deploy"
329
+ chmod 600 "$RUNNER_TEMP/ssh/id_deploy"
330
+
331
+ # EDIT (optional, recommended): set a repo variable DEPLOY_KNOWN_HOSTS to
332
+ # the host's public key line and this becomes real host verification.
333
+ # Without it, the scan below is trust-on-first-use ON EVERY RUN: it
334
+ # accepts whatever answers on that address today, so strict host-key
335
+ # checking is enforcing a fact learned thirty seconds ago. That is the
336
+ # honest description; it is a deliberate trade for setup simplicity on a
337
+ # private network path, not a verified channel.
338
+ if [ -n "${{ vars.DEPLOY_KNOWN_HOSTS }}" ]; then
339
+ printf '%s\n' "${{ vars.DEPLOY_KNOWN_HOSTS }}" > "$RUNNER_TEMP/ssh/known_hosts"
340
+ echo "known_hosts pinned from repo variable"
341
+ else
342
+ echo "::notice::DEPLOY_KNOWN_HOSTS is not set — the host key is being learned at run time (trust on first use)."
343
+ # Retry with backoff, and REQUIRE a non-empty result: a single network
344
+ # blip on the SSH port must not break a release, and an empty
345
+ # known_hosts file would silently defeat strict host-key checking
346
+ # rather than fail. From a runner near the host this succeeds first try.
347
+ for attempt in 1 2 3 4 5; do
348
+ if ssh-keyscan -T 10 -p "$SSH_PORT" "$SSH_HOST" > "$RUNNER_TEMP/ssh/known_hosts" 2>/dev/null \
349
+ && [ -s "$RUNNER_TEMP/ssh/known_hosts" ]; then
350
+ echo "ssh-keyscan ok (attempt $attempt)"
351
+ break
352
+ fi
353
+ if [ "$attempt" = 5 ]; then
354
+ echo "::error::ssh-keyscan could not reach $SSH_HOST:$SSH_PORT after 5 attempts"
355
+ exit 1
356
+ fi
357
+ echo "ssh-keyscan attempt $attempt failed — retrying in $((attempt * 3))s"
358
+ sleep "$((attempt * 3))"
359
+ done
360
+ fi
361
+
362
+ - name: Rsync release to the server
363
+ run: |
364
+ # --delete keeps the server a mirror of the release, so a file deleted in
365
+ # git disappears in production. The excludes are what makes that safe:
366
+ # everything listed is server-owned state that must survive the mirror.
367
+ # THINK BEFORE REMOVING ONE — an exclude dropped here deletes production
368
+ # data on the next deploy.
369
+ #
370
+ # .env / .env.* server-only configuration, written by hand once
371
+ # /storage/ uploads, logs, generated keys — irreplaceable
372
+ # /bootstrap/cache/ regenerated on the server, below
373
+ # /database/database.sqlite the throwaway build-time database
374
+ #
375
+ # EDIT: add any other server-owned path this app writes into.
376
+ rsync -az --delete \
377
+ -e "ssh -p $SSH_PORT -i $RUNNER_TEMP/ssh/id_deploy -o UserKnownHostsFile=$RUNNER_TEMP/ssh/known_hosts -o IdentitiesOnly=yes" \
378
+ --exclude='.env' \
379
+ --exclude='.env.*' \
380
+ --exclude='/storage/' \
381
+ --exclude='/.git/' \
382
+ --exclude='/node_modules/' \
383
+ --exclude='/bootstrap/cache/' \
384
+ --exclude='/tests/' \
385
+ --exclude='/database/database.sqlite' \
386
+ ./ "$SSH_USER@$SSH_HOST:$APP_DIR/"
387
+
388
+ # ---------------------------------------------------------------------------
389
+ # THIS STEP MIGRATES PRODUCTION.
390
+ #
391
+ # `migrate --force` runs pending migrations against the live database, with
392
+ # no backup taken here and no confirmation asked. That is intentional and it
393
+ # is the step to read before every release: check what migrations the tag
394
+ # carries, and take a database snapshot yourself if any of them is
395
+ # destructive. Do not make this quieter, do not add `|| true` to the migrate
396
+ # line, and do not move it behind a condition — a deploy that silently skips
397
+ # a migration produces a running site with the wrong schema, which is worse
398
+ # than a failed deploy in every case.
399
+ # ---------------------------------------------------------------------------
400
+ - name: Reconcile, migrate & cache on server
401
+ run: |
402
+ ssh -p "$SSH_PORT" -i "$RUNNER_TEMP/ssh/id_deploy" \
403
+ -o UserKnownHostsFile="$RUNNER_TEMP/ssh/known_hosts" -o IdentitiesOnly=yes \
404
+ "$SSH_USER@$SSH_HOST" bash -s <<REMOTE
405
+ set -euo pipefail
406
+ cd "$APP_DIR"
407
+ PHP="$PHP_BIN"
408
+
409
+ echo "==> ensure writable dirs"
410
+ # rsync excludes /storage/ and /bootstrap/cache/, so a BRAND NEW install
411
+ # has neither — and package:discover dies immediately without them. This
412
+ # only ever bites on the very first deploy, which is exactly why one
413
+ # ancestor of this template lacked it: the directories were already there
414
+ # from an earlier manual setup, so nobody found out. mkdir -p is free on
415
+ # every subsequent run.
416
+ mkdir -p bootstrap/cache storage/app/public storage/logs \
417
+ storage/framework/cache/data storage/framework/sessions storage/framework/views
418
+
419
+ echo "==> package:discover"
420
+ # Deferred from the composer step, which ran --no-scripts: the manifest
421
+ # must be generated where the real .env is.
422
+ \$PHP artisan package:discover --ansi
423
+
424
+ echo "==> reconcile generated migrations"
425
+ # Mark create-table migrations as already run when their table exists.
426
+ # This absorbs schema drift — a table created by a code generator or by
427
+ # hand outside the migration ledger — which otherwise fails the migrate
428
+ # below with "table already exists" and aborts the deploy.
429
+ #
430
+ # EDIT (required): the glob(s) naming your generated migrations. The path
431
+ # below is a PLACEHOLDER — point it at your generator's output directory,
432
+ # or reconciliation silently matches nothing and the migrate below fails
433
+ # on the first pre-existing table.
434
+ #
435
+ # Both a flat directory and one level of subdirectories are covered: a
436
+ # repo with only the flat layout gets an empty second glob, which costs
437
+ # nothing, and a repo that later grows subdirectories does not silently
438
+ # stop reconciling them. That asymmetry existed between the copies this
439
+ # came from — the one with nested output had to discover it the hard way.
440
+ #
441
+ # The temp file is mktemp'd, not a fixed name. Several repos can deploy
442
+ # into the SAME hosting account, and each ancestor of this template
443
+ # avoided the collision by inventing its own filename — which works right
444
+ # up until two of them choose the same one.
445
+ RECONCILE="\$(mktemp /tmp/reconcile.XXXXXX)"
446
+ trap 'rm -f "\$RECONCILE"' EXIT
447
+ cat > "\$RECONCILE" <<'PHP'
448
+ \$ran = DB::table('migrations')->pluck('migration')->all();
449
+ \$files = array_merge(
450
+ glob(base_path('database/migrations/generated/*.php')) ?: [],
451
+ glob(base_path('database/migrations/generated/*/*.php')) ?: []
452
+ );
453
+ \$batch = (DB::table('migrations')->max('batch') ?? 0) + 1;
454
+ foreach (\$files as \$file) {
455
+ \$mig = basename(\$file, '.php');
456
+ if (in_array(\$mig, \$ran)) { continue; }
457
+ if (preg_match('/create_(.+)_table/', \$mig, \$m) && Schema::hasTable(\$m[1])) {
458
+ DB::table('migrations')->insert(['migration' => \$mig, 'batch' => \$batch]);
459
+ echo 'Reconciled: ' . \$mig . PHP_EOL;
460
+ }
461
+ }
462
+ PHP
463
+ # The trailing "|| true" is deliberate: reconciliation is best-effort and
464
+ # cleans up the PREVIOUS deploy's mess. The migrate below is the step that
465
+ # must not be forgiving — do not copy this tolerance down to it.
466
+ #
467
+ # (Note for anyone editing inside this heredoc: it is UNQUOTED, so the
468
+ # runner's shell expands it before sending. Backticks and un-escaped $
469
+ # are substituted HERE, even inside comments. Write \$ for the far side.)
470
+ \$PHP artisan tinker --no-interaction --execute "\$(cat \$RECONCILE)" 2>&1 || true
471
+
472
+ echo "==> migrate (PRODUCTION DATABASE)"
473
+ \$PHP artisan migrate --force
474
+
475
+ # EDIT: app-specific commands that are PART OF the migration, not extras.
476
+ # If a schema change has a paired data backfill, it belongs here and not
477
+ # in a human's memory — a migrated schema with an unfilled table is a
478
+ # half-deployed release that looks fully deployed. Keep such commands
479
+ # idempotent so re-running a deploy is harmless, and let a verifier exit
480
+ # non-zero: a red job after the site is already updated is a loud alarm,
481
+ # which is what you want. Examples from repos this came from:
482
+ # \$PHP artisan <your>:backfill-<thing>
483
+ # \$PHP artisan <your>:verify-<thing>
484
+ # \$PHP artisan passport:keys 2>/dev/null || true # if using OAuth;
485
+ # idempotent, and the keys live in storage/ which rsync never overwrites
486
+
487
+ echo "==> caches"
488
+ \$PHP artisan config:cache
489
+ # route:cache fails on closure-based routes; tolerated because an
490
+ # uncached route table is slow, not broken.
491
+ \$PHP artisan route:cache 2>/dev/null || true
492
+ \$PHP artisan event:cache
493
+ \$PHP artisan storage:link 2>/dev/null || true
494
+
495
+ echo "==> ensure docroot symlink"
496
+ # Re-asserted every deploy: panels recreate the docroot as a real
497
+ # directory when the domain is touched, which silently starts serving an
498
+ # empty folder instead of the app.
499
+ if [ ! -L "$DOCROOT_LINK" ]; then rm -rf "$DOCROOT_LINK"; fi
500
+ ln -sfn "/home/$SSH_USER/$APP_DIR/public" "$DOCROOT_LINK"
501
+
502
+ echo "==> server steps complete"
503
+ REMOTE
504
+
505
+ # ---------------------------------------------------------------------------
506
+ # KEEP THIS STEP. It is the only one that asks the question the whole workflow
507
+ # exists to answer. Everything above proves the pipeline ran; this proves the
508
+ # site answers. A deploy can rsync perfectly, migrate cleanly, exit zero, and
509
+ # serve a 500 or the host's default placeholder page — green workflow, dead
510
+ # site — and without this step the first report comes from a user.
511
+ # ---------------------------------------------------------------------------
512
+ - name: Verify the deployed site answers
513
+ run: |
514
+ code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 20 "$SMOKE_URL" || echo 000)
515
+ echo "smoke: HTTP $code from $SMOKE_URL"
516
+ for ok in $SMOKE_OK_CODES; do
517
+ if [ "$code" = "$ok" ]; then
518
+ echo "OK — the app is serving"
519
+ exit 0
520
+ fi
521
+ done
522
+ echo "::error::Unexpected smoke status $code (expected one of: $SMOKE_OK_CODES)"
523
+ echo "000 means the request never completed: DNS, TLS or the host being down."
524
+ exit 1
525
+
526
+ - name: Cleanup
527
+ # always(): the key must not survive a failed run. On a self-hosted runner
528
+ # the workspace persists, so a skipped cleanup leaves a usable private key
529
+ # on a shared machine until something else happens to overwrite it.
530
+ if: always()
531
+ run: rm -rf "$RUNNER_TEMP/ssh"