@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.11
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.
- package/LICENSE +21 -0
- package/README.md +312 -3
- package/README.vi.md +281 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +137 -0
- package/templates/release-auto.yml +475 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13806 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +278 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify-endpoint.js +170 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +521 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +740 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- 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"
|