Repository navigation
348 lines (316 loc) · 14 KB
/
Copy pathdocs-pr-preview-deploy.yaml
File metadata and controls
348 lines (316 loc) · 14 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
# Builds a pull request's docs/ tree with docs-engine's offline export and
# publishes it as its own site on the preview-only domain in the repository
# variable DOCS_PREVIEW_DOMAIN (docs.cdr-preview.dev, so PR 123's head is
# https://pr-123.docs.cdr-preview.dev):
#
# pr-<number>.<domain> the PR head, re-aliased per build
# pr-<number>-<sha:0:9>.<domain> one per built commit
#
# After a deploy succeeds, the comment job runs docs-preview.yaml, which links
# each changed page to the first and keeps a collapsible list of the second
# for every commit built, in the PR's only preview comment. It posts nothing
# when only generated reference pages changed. docs-pr-preview-cleanup.yaml
# deletes the previews when the PR closes.
#
# Only PRs from a branch in this repository build. Fork PRs get no preview:
# their build would share the base branch's Actions cache scope and the
# private engine source.
#
# Compiling Markdown runs the engine's plugins over it, so PR content never
# shares a job with a secret:
# engine mints a docs-engine read token and packs the engine source; never
# sees PR content.
# build no secrets. Builds the export from the engine and the PR's docs/.
# deploy holds the Vercel token. Takes only the static files from build,
# lays them out with the engine's own script (checked against the
# engine job's digest), adds noindex, and deploys them prebuilt.
#
# Each job hands the next an artifact; a job's outputs cannot be rewritten by
# a later job, so the engine digest travels as an output.
name: docs-pr-preview-deploy
on:
pull_request:
types:
- opened
- synchronize
- reopened
paths:
- "docs/**"
- "!docs/.style/**"
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
cancel-in-progress: true
permissions: {}
jobs:
engine:
# Off for now: the DOCS_ENGINE_APP_ID and DOCS_ENGINE_APP_PRIVATE_KEY secrets
# this job reads aren't set, so it fails on every docs PR. The other jobs
# need this one and skip with it. Drop "false && " to turn previews back on.
if: false && github.event.pull_request.head.repo.full_name == github.repository
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: read
outputs:
digest: ${{ steps.pack.outputs.digest }}
domain: ${{ steps.domain.outputs.domain }}
steps:
- name: Harden Runner
uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
with:
egress-policy: audit
# Checked first so a missing domain fails before the build. A vercel.app
# name is first-come across every Vercel account, so anyone could claim
# a preview's name before the deploy or after cleanup frees it.
- name: Check the preview domain
id: domain
env:
DOCS_PREVIEW_DOMAIN: ${{ vars.DOCS_PREVIEW_DOMAIN }}
run: |
set -euo pipefail
domain=$(printf '%s' "$DOCS_PREVIEW_DOMAIN" | tr '[:upper:]' '[:lower:]')
if [ -z "$domain" ] || [[ "$domain" =~ (^|\.)vercel\.app\.?$ ]] || ! [[ "$domain" =~ ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ ]]; then
echo "::error::Set the repository variable DOCS_PREVIEW_DOMAIN to a Coder-owned domain (not vercel.app)." >&2
exit 1
fi
echo "domain=${domain}" >> "$GITHUB_OUTPUT"
# A PR may move the pin and preview the result; one branched before the
# pin existed uses the base branch's.
- name: Read the pinned docs-engine commit
id: ref
env:
GH_TOKEN: ${{ github.token }}
REPO: ${{ github.repository }}
PIN_SOURCE: ${{ github.event.pull_request.head.sha }}
BASE_SHA: ${{ github.event.pull_request.base.sha }}
run: |
set -euo pipefail
read_pin() { gh api -H "Accept: application/vnd.github.raw" "repos/${REPO}/contents/docs/.engine-ref?ref=$1" | tr -d '[:space:]'; }
ref=$(read_pin "$PIN_SOURCE" || read_pin "$BASE_SHA")
[[ "$ref" =~ ^[0-9a-f]{40}$ ]] || { echo "docs/.engine-ref must hold one full 40-hex commit SHA" >&2; exit 1; }
echo "ref=${ref}" >> "$GITHUB_OUTPUT"
- name: Mint a docs-engine read token
id: app-token
uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
with:
app-id: ${{ secrets.DOCS_ENGINE_APP_ID }}
private-key: ${{ secrets.DOCS_ENGINE_APP_PRIVATE_KEY }}
owner: coder
repositories: docs-engine
permission-contents: read
- name: Check out docs-engine
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: coder/docs-engine
ref: ${{ steps.ref.outputs.ref }}
token: ${{ steps.app-token.outputs.token }}
path: engine
fetch-depth: 0
persist-credentials: false
# A fork's commit can be fetched by SHA through a public repository, so
# only a commit on docs-engine main may build.
- name: Check the pin is on docs-engine main
env:
REF: ${{ steps.ref.outputs.ref }}
run: |
set -euo pipefail
git -C engine merge-base --is-ancestor "$REF" origin/main || { echo "::error::docs/.engine-ref must name a commit on coder/docs-engine main" >&2; exit 1; }
- name: Pack the engine source
id: pack
run: |
set -euo pipefail
tar -C engine --exclude=.git -czf engine.tgz .
echo "digest=$(sha256sum engine.tgz | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
- name: Upload the engine source
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: docs-engine-source
path: engine.tgz
retention-days: 1
if-no-files-found: error
build:
needs: engine
if: github.event.pull_request.head.repo.full_name == github.repository
runs-on: ubuntu-latest
timeout-minutes: 30
permissions:
contents: read
steps:
- name: Harden Runner
uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
with:
egress-policy: audit
- name: Download the engine source
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: docs-engine-source
path: ${{ runner.temp }}/engine-artifact
- name: Verify and unpack the engine source
env:
DIGEST: ${{ needs.engine.outputs.digest }}
ARTIFACT_DIR: ${{ runner.temp }}/engine-artifact
run: |
set -euo pipefail
echo "${DIGEST} ${ARTIFACT_DIR}/engine.tgz" | sha256sum -c -
mkdir engine
tar -C engine -xzf "${ARTIFACT_DIR}/engine.tgz"
- name: Check out the pull request's docs/ tree
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.event.pull_request.head.sha }}
path: content
sparse-checkout: docs
persist-credentials: false
- name: Install pnpm
uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
with:
package_json_file: engine/package.json
- name: Set up Node
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 22.23.4
package-manager-cache: false
- name: Install the engine's dependencies
working-directory: engine
run: pnpm install --frozen-lockfile
# docs/ holds no symbolic links. One added by a PR could pull files
# from elsewhere on this runner, such as the private engine source,
# into a public preview, whatever the pinned engine does with it.
- name: Build the static export
working-directory: engine
env:
DOCS_ROOT: ${{ github.workspace }}/content/docs
run: |
set -euo pipefail
if [ -L "$DOCS_ROOT" ] || [ ! -d "$DOCS_ROOT" ] || [ -n "$(find "$DOCS_ROOT" -type l -print -quit)" ]; then
echo "::error::docs/ must be a directory with no symbolic links in it." >&2
exit 1
fi
pnpm turbo run build --filter=@coder/offlinedocs
- name: Upload the static export
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: docs-preview-site
path: engine/apps/offlinedocs/out
retention-days: 1
if-no-files-found: error
deploy:
needs: [engine, build]
if: github.event.pull_request.head.repo.full_name == github.repository
runs-on: ubuntu-latest
timeout-minutes: 15
environment: docs-preview
permissions:
# Read only: the head check below. The comment job posts the comment.
pull-requests: read
outputs:
short_sha: ${{ steps.deploy.outputs.short_sha }}
env:
# 59.x needs team access, which a project-scoped token lacks.
VERCEL_CLI_VERSION: 65.11.0
REPO: ${{ github.repository }}
PR_NUMBER: ${{ github.event.pull_request.number }}
SHA: ${{ github.event.pull_request.head.sha }}
DOMAIN: ${{ needs.engine.outputs.domain }}
steps:
- name: Harden Runner
uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
with:
egress-policy: audit
- name: Download the engine source
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: docs-engine-source
path: ${{ runner.temp }}/engine-artifact
# The build job could have replaced the artifact, so only the engine
# job's digest decides whether this code may run here.
- name: Verify and unpack the engine source
env:
DIGEST: ${{ needs.engine.outputs.digest }}
ARTIFACT_DIR: ${{ runner.temp }}/engine-artifact
run: |
set -euo pipefail
echo "${DIGEST} ${ARTIFACT_DIR}/engine.tgz" | sha256sum -c -
mkdir engine
tar -C engine -xzf "${ARTIFACT_DIR}/engine.tgz"
- name: Download the static export
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: docs-preview-site
path: engine/apps/offlinedocs/out
- name: Set up Node
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 22.23.4
package-manager-cache: false
# build-output.mjs uses only Node built-ins and writes the routes and
# security headers (including the CSP) from the engine's vercel.json.
# The export comes from the job that ran PR content, so anything but
# regular files and directories is refused before it is copied: a
# symbolic link could point the upload at a file on this runner. The
# error names no path, since a PR-chosen name could read as a
# workflow command.
- name: Lay out the Build Output API directory with noindex
working-directory: engine/apps/offlinedocs
run: |
set -euo pipefail
unexpected=$(find out ! -type f ! -type d -print -quit)
if [ -n "$unexpected" ]; then
echo "::error::The static export holds a symbolic link or special file; refusing to deploy it." >&2
exit 1
fi
node scripts/build-output.mjs
config=.vercel/output/config.json
jq '.routes = [{src: "^/(.*)$", headers: {"X-Robots-Tag": "noindex"}, continue: true}] + .routes' \
"$config" > "${config}.tmp"
mv "${config}.tmp" "$config"
jq -e '.routes[0].headers["X-Robots-Tag"] == "noindex"' "$config" >/dev/null
- name: Deploy and alias the preview
id: deploy
working-directory: engine/apps/offlinedocs
env:
GH_TOKEN: ${{ github.token }}
VERCEL_TOKEN: ${{ secrets.VERCEL_PREVIEW_TOKEN }}
VERCEL_ORG_ID: ${{ vars.VERCEL_PREVIEW_ORG_ID }}
VERCEL_PROJECT_ID: ${{ vars.VERCEL_PREVIEW_PROJECT_ID }}
run: |
set -euo pipefail
short_sha="${SHA:0:9}"
head_alias="pr-${PR_NUMBER}.${DOMAIN}"
commit_alias="pr-${PR_NUMBER}-${short_sha}.${DOMAIN}"
vc() { npx --yes "vercel@${VERCEL_CLI_VERSION}" "$@" --token="$VERCEL_TOKEN"; }
vercel_api() {
curl --fail-with-body -sS --retry 3 \
-H "Authorization: Bearer ${VERCEL_TOKEN}" \
-H "Content-Type: application/json" "$@"
}
set_alias() {
vercel_api -X POST "https://api.vercel.com/v2/deployments/${deployment_id}/aliases?teamId=${VERCEL_ORG_ID}" \
--data "$(jq -cn --arg alias "$1" '{alias: $alias}')" >/dev/null
echo "Aliased https://$1"
}
vc pull --yes --environment=preview
url=$(vc deploy --prebuilt --archive=tgz --yes \
--meta pr="$PR_NUMBER" \
--meta sha="$SHA")
deployment_id=$(vercel_api "https://api.vercel.com/v13/deployments/${url#https://}?teamId=${VERCEL_ORG_ID}" | jq -er '.id')
set_alias "$commit_alias"
# A slower build of an older commit must not take the head alias back.
current_head=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}" --jq '.head.sha')
if [ "$current_head" = "$SHA" ]; then
set_alias "$head_alias"
else
echo "::notice::The PR head moved to ${current_head} during this build; ${head_alias} is left for that build."
fi
echo "short_sha=${short_sha}" >> "$GITHUB_OUTPUT"
# Runs after a successful deploy, so its per-page links never point at a
# preview that does not exist yet.
comment:
needs: deploy
if: github.event.pull_request.head.repo.full_name == github.repository
permissions:
contents: read
pull-requests: write
uses: ./.github/workflows/docs-preview.yaml
with:
short_sha: ${{ needs.deploy.outputs.short_sha }}