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
name: docs
on:
push:
branches:
workflow_dispatch:
# Least privilege at the workflow level. Only the deploy job can write to
# Pages or mint an OIDC token; the build job, which builds the site and runs
# cargo doc, and the verify job, which only reads the live site, carry neither.
permissions:
contents: read
concurrency:
group: "pages"
cancel-in-progress: false
env:
# Builds the site. Keep in step with BUN_VERSION in ci.yml, whose docsite
# floor gates the same build.
BUN_VERSION: 1.3.12
BUN_SHA256: 11dc3ee11bc1695e149737c6ca3d5619302cf4346e6b8a6ec7988967ef01ddc5
jobs:
build:
name: Build site + rustdoc
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
# Full history: a design record's citations open at the commit it
# was read at, and the build reads those lines there
# (site/README.md, The Blueprints components).
fetch-depth: 0
- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master
with:
toolchain: stable
- uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2
- name: Install bun
run: |
set -euo pipefail
mkdir -p "$HOME/.local/bin"
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
curl -sSLf -o "$RUNNER_TEMP/bun.zip" \
"https://github.com/oven-sh/bun/releases/download/bun-v${BUN_VERSION}/bun-linux-x64.zip"
echo "${BUN_SHA256} $RUNNER_TEMP/bun.zip" | sha256sum -c -
unzip -q -j "$RUNNER_TEMP/bun.zip" bun-linux-x64/bun -d "$HOME/.local/bin"
# The SvelteKit site in site/ (EP-0012), prerendered for the Pages base
# path. The build itself fails, before anything is uploaded, when the
# emitted asset URLs or internal links do not match BASE_PATH
# (site/scripts/verify-base-path.ts).
- name: Build the site
working-directory: site
env:
BASE_PATH: /matra
# Comments (giscus) render only when both ids are set; see
# site/README.md. The category id is set once the Docs discussion
# category exists.
PUBLIC_GISCUS_REPO_ID: R_kgDORzS1lQ
PUBLIC_GISCUS_CATEGORY_ID: ""
run: |
bun install --frozen-lockfile
bun run build
- name: Build rustdoc
env:
RUSTDOCFLAGS: -Dwarnings
run: cargo doc --no-deps --all-features
- name: Assemble site
run: |
mkdir -p _site
cp -r site/build/. _site/
mkdir -p _site/api
cp -r target/doc/* _site/api/
# Landing page for /api/ that redirects to the crate's index.
cat > _site/api/index.html <<'HTML'
<!doctype html>
<meta charset="utf-8">
<title>matra API reference</title>
<meta http-equiv="refresh" content="0; url=matra/index.html">
<link rel="canonical" href="matra/index.html">
<p>Redirecting to <a href="matra/index.html">matra API reference</a>.</p>
HTML
# Every published path (site/urls.txt) is in the artifact, rustdoc's
# included, before anything is uploaded.
- name: Check the artifact holds every published path
run: bash scripts/check-url-manifest.sh --dir _site
- name: Upload Pages artifact
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: _site
deploy:
name: Deploy to GitHub Pages
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
outputs:
page_url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy
id: deployment
uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
# The deploy succeeding says Pages accepted the artifact, not that readers
# can reach it. This asks the live site for every published path, and the
# root, and fails on any answer but 200, retrying while a new deploy reaches
# every edge.
verify:
name: Verify the live site
needs: deploy
runs-on: ubuntu-latest
# A reachable site checks in well under a minute. This bounds the case
# where it never answers, which the script's retries would otherwise
# stretch out.
timeout-minutes: 15
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Every published URL answers 200
env:
PAGE_URL: ${{ needs.deploy.outputs.page_url }}
run: bash scripts/check-url-manifest.sh --live "${PAGE_URL:-https://mox-labs.github.io/matra/}"