Repository navigation
290 lines (264 loc) · 14.1 KB
/
Copy pathdocumentation.yml
File metadata and controls
290 lines (264 loc) · 14.1 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
name: Documentation
on:
workflow_call:
inputs:
use_ct_registry:
required: false
default: false
type: boolean
# GPU-backed docs build (control-toolbox/OptimalControl.jl#885 part 2).
# Default '' reproduces today's behaviour exactly for every caller: `build-gpu`
# is skipped and only `build` runs. A caller opts in with e.g. '["occidata"]'.
#
# Design: *publish then upgrade*, not probe-then-fallback. `build` always runs
# first and deploys, unchanged — so docs publishing never depends on a
# self-hosted box being online. `build-gpu` runs only once `build` has
# succeeded and, with `continue-on-error: true`, never fails the workflow: on
# success it redeploys the same site with real GPU numbers; on failure or a
# long SLURM queue (self-hosted GPU boxes are not always immediately
# available) the already-published site from `build` is simply left in place.
gpu_runner:
description: "Self-hosted GPU runner labels for a docs-build upgrade pass (JSON array, e.g. '[\"occidata\"]'), or 'auto': kkt if online and idle, else occidata if online and idle, else no pass (needs the CT_RUNNERS_* secrets). Empty (default) disables the pass entirely."
required: false
default: ''
type: string
gpu_timeout_minutes:
description: "Timeout for the GPU upgrade pass. Budget for a cold build (self-hosted depots can be purged by maintenance jobs), not a warm one."
required: false
default: 120
type: number
ctactions_ref:
description: "Ref of CTActions whose scripts the `changes` job runs (main; a branch to test a change)"
required: false
type: string
default: main
secrets:
DOCUMENTER_KEY:
description: 'Deploy key of gh-pages; optional: without it, Documenter deploys with GITHUB_TOKEN (what every caller does today)'
required: false
SSH_KEY:
required: false
CT_RUNNERS_CLIENT_ID:
description: "ct-runners App, reads the state of the organization's runners for gpu_runner: 'auto'; without it the fallback (occidata) is used"
required: false
CT_RUNNERS_PRIVATE_KEY:
required: false
# Superseded runs: on a pull request, a new run cancels the previous one of the same pull
# request (docs/workflows/superseded-runs.md). On a push to main, a tag, a schedule or a manual
# run, the group is the run itself: nothing is cancelled and nothing waits. Declared here,
# not in the caller: a label that changes nothing creates a run whose calling job is
# skipped, and a `concurrency` of the caller would still cancel the run in progress. The
# group starts with a name of its own: it must differ from every group of a caller.
# A run started by label-dispatch.yml (a `workflow_dispatch` with the input `pr`) is a
# run of that pull request: same group, same cancellation.
concurrency:
group: ctactions-documentation-${{ github.workflow }}-${{ github.event.pull_request.number || github.event.inputs.pr || github.run_id }}
cancel-in-progress: ${{ github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && github.event.inputs.pr != '') }}
jobs:
# A run started by label-dispatch.yml shows as a commit status (pr-status.yml).
status-start:
if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.pr != '' }}
permissions:
statuses: write
uses: control-toolbox/CTActions/.github/workflows/pr-status.yml@main
with:
context: Documentation
phase: start
status-end:
needs: [changes, build]
if: ${{ always() && github.event_name == 'workflow_dispatch' && github.event.inputs.pr != '' }}
permissions:
statuses: write
uses: control-toolbox/CTActions/.github/workflows/pr-status.yml@main
with:
context: Documentation
phase: end
results: ${{ toJSON(needs.*.result) }}
preview_pr: ${{ github.event.inputs.preview == 'true' && github.event.inputs.pr || '' }}
# Whether the jobs below run (docs/workflows/guard.md): no on a pull request that is not
# open; on a push to main, yes unless the merged pull request carries the label
# `ci on main: changes only` (docs/workflows/ci-on-main.md); yes otherwise.
changes:
permissions:
contents: read
pull-requests: read
actions: read
uses: control-toolbox/CTActions/.github/workflows/guard.yml@main
with:
scope: docs
job: build
ctactions_ref: ${{ inputs.ctactions_ref }}
actors: ${{ vars.CT_CI_CHANGES_ONLY_ACTORS }}
build:
needs: changes
if: ${{ !cancelled() && needs.changes.outputs.run != 'false' }}
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: actions/checkout@v7
- name: Setup Julia
id: julia
uses: julia-actions/setup-julia@latest
with:
version: '1.12'
# Add ct-registry (only if use_registry is true and SSH_KEY is provided)
- name: Add ct-registry
if: inputs.use_ct_registry
uses: control-toolbox/CTActions/.github/actions/add-ct-registry@main
with:
key: ${{ secrets.SSH_KEY }}
# 🧰 Cache des artefacts (binaires des paquets)
- name: Cache Julia artifacts
uses: actions/cache@v6
with:
path: ~/.julia/artifacts
key: ${{ runner.os }}-julia-${{ steps.julia.outputs.julia-version }}-artifacts-${{ hashFiles('**/Project.toml') }}
restore-keys: |
${{ runner.os }}-julia-${{ steps.julia.outputs.julia-version }}-artifacts-
# ⚡ Cache du code précompilé (fichiers .ji)
- name: Cache Julia compiled code
uses: actions/cache@v6
with:
path: ~/.julia/compiled
key: ${{ runner.os }}-julia-${{ steps.julia.outputs.julia-version }}-compiled-${{ hashFiles('**/Project.toml') }}
restore-keys: |
${{ runner.os }}-julia-${{ steps.julia.outputs.julia-version }}-compiled-
- uses: julia-actions/julia-buildpkg@latest
- name: Install dependencies
run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
# PR previews are opt-in: `DOCUMENTER_PUSH_PREVIEW` is "true" only on a PR carrying
# the `documentation push preview` label, "false" otherwise. A caller's make.jl reads
# it as `push_preview = get(ENV, "DOCUMENTER_PUSH_PREVIEW", "false") == "true"`.
# Inside a reusable workflow `github.event` is the caller's event: the PR's labels
# are visible here on a `pull_request`, and on a `workflow_dispatch` from
# label-dispatch.yml the inputs `pr` and `preview` say the same. A make.jl that
# still hardcodes `push_preview` ignores it.
# Documenter takes a build for a preview only on `GITHUB_EVENT_NAME=pull_request` and
# `GITHUB_REF=refs/pull/<n>/merge`; a dispatched run has neither, so the build is told.
- name: Build and deploy
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
DOCUMENTER_PUSH_PREVIEW: ${{ (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'documentation push preview')) || (github.event_name == 'workflow_dispatch' && github.event.inputs.pr != '' && github.event.inputs.preview == 'true') }}
DISPATCH_PR: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.pr || '' }}
GKSwstype: 100
run: |
if [ -n "$DISPATCH_PR" ]; then
export GITHUB_EVENT_NAME=pull_request GITHUB_REF="refs/pull/$DISPATCH_PR/merge"
fi
julia --project=docs/ -e 'ENV["GKSwstype"]="nul"; include("docs/make.jl")'
echo "📂 Listing docs/build/assets:"
ls -R docs/build/assets || true
# The GPU upgrade pass. See the `gpu_runner` input doc above for the design
# rationale. Never on the critical path of publishing: it only starts once
# `build` has already deployed, and `continue-on-error: true` means its outcome
# never fails the workflow either way.
# With `gpu_runner: 'auto'`, `select-gpu` picks kkt if it is online and idle, else
# occidata if it is online and idle, else skips the pass (`when_busy: 'skip'`,
# select-gpu-runner.yml). A pass queued for a busy runner would hold the concurrency
# group of the caller, and the runs of the next commits, CPU build included, would wait
# for it (CTActions#174). Chosen once `build` is done, i.e. as late as possible, since
# `build` can take a while.
select-gpu:
needs: build
# `!cancelled()`: `changes` is skipped on a tag or a manual run, and the default
# `success()` of a `needs` is false when a job anywhere upstream was skipped, even though
# `build` ran.
if: >
!cancelled() && needs.build.result == 'success' &&
inputs.gpu_runner == 'auto' && github.event_name != 'pull_request' && !github.event.inputs.pr
uses: control-toolbox/CTActions/.github/workflows/select-gpu-runner.yml@main
with:
when_busy: skip
ctactions_ref: ${{ inputs.ctactions_ref }}
secrets:
CT_RUNNERS_CLIENT_ID: ${{ secrets.CT_RUNNERS_CLIENT_ID }}
CT_RUNNERS_PRIVATE_KEY: ${{ secrets.CT_RUNNERS_PRIVATE_KEY }}
build-gpu:
# `always()`: `select-gpu` is skipped unless `gpu_runner` is 'auto', and a skipped
# need would skip this job too. With 'auto', `skip` is 'true' when no GPU runner is
# online and idle: the site published by `build` stays, as when the pass fails.
needs: [build, select-gpu]
if: >
always() && needs.build.result == 'success' &&
inputs.gpu_runner != '' && github.event_name != 'pull_request' && !github.event.inputs.pr &&
(inputs.gpu_runner != 'auto' || (needs.select-gpu.result == 'success' && needs.select-gpu.outputs.skip != 'true'))
runs-on: ${{ fromJSON(inputs.gpu_runner == 'auto' && needs.select-gpu.outputs.runs_on_labels || inputs.gpu_runner) }}
timeout-minutes: ${{ inputs.gpu_timeout_minutes }}
continue-on-error: true
steps:
- uses: actions/checkout@v7
- name: Setup Julia
id: julia
uses: julia-actions/setup-julia@latest
with:
version: '1.12'
# Self-hosted depots are persistent and not necessarily at ~/.julia (ci.yml's
# own comment on this: setup-julia does not set JULIA_DEPOT_PATH, and
# different self-hosted runners can have different real depot locations) —
# ask Julia instead of guessing, same pattern as ci.yml.
- name: Resolve Julia depot path
id: depot
run: echo "path=$(julia -e 'print(Base.DEPOT_PATH[1])')" >> "$GITHUB_OUTPUT"
# The node's /tmp is wiped every hour at HH:01 (occidata specifically; see
# ci.yml's "Keep the Pkg sandbox out of /tmp" step, commit 2f00b67). A docs
# build is longer than a test run, so it will almost certainly cross an hour
# boundary — redirect before any Julia step runs.
- name: Redirect TMPDIR off the node's periodically-wiped /tmp
run: |
mkdir -p "$RUNNER_TEMP/jltmp"
echo "TMPDIR=$RUNNER_TEMP/jltmp" >> "$GITHUB_ENV"
- name: Add ct-registry
if: inputs.use_ct_registry
uses: control-toolbox/CTActions/.github/actions/add-ct-registry@main
with:
key: ${{ secrets.SSH_KEY }}
# No actions/cache: the self-hosted depot persists, as in ci.yml.
- uses: julia-actions/julia-buildpkg@latest
- name: Install dependencies
run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
# Self-hosted depots persist, and are shared across jobs: Pkg runs a package's
# `deps/build.jl` only when it installs the package, never when the sources are
# already in the depot. A package whose build output is missing there (KNITRO.jl:
# `deps/deps.jl`, "KNITRO.jl is not installed correctly") then fails to load for
# good, while the same build on a GitHub-hosted runner (fresh depot) succeeds. Run
# every build script of the docs environment again; it is idempotent.
- name: Build the packages of the docs environment
run: julia --project=docs/ -e 'using Pkg; Pkg.build(; verbose=true)'
# Only the builds themselves need CUDA: on occidata they run on a GPU node
# through $OCCIDATA_GPU_RUN (see ci.yml's self-hosted "Run tests" step);
# the expansion is empty on any other runner. SLURM reads a bare number as
# minutes, so the GPU allocation gets the same budget as the job.
#
# Self-hosted depots persist across runs and across branches, unlike
# GitHub-hosted runners' fresh-per-job disk — a compiled/ cache left over
# from a different Manifest can drift out of sync and break precompilation.
# Retry once after purging it, as ci.yml's self-hosted "Run tests" step
# does. continue-on-error is enough here because this step is a plain
# `run:`, not a composite action.
- name: Build and deploy
id: build_deploy
continue-on-error: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
GKSwstype: 100
OCCIDATA_GPU_TIME: ${{ inputs.gpu_timeout_minutes }}
run: |
${OCCIDATA_GPU_RUN:-} julia --project=docs/ -e 'ENV["GKSwstype"]="nul"; include("docs/make.jl")'
- name: Purge stale compiled cache and retry once
if: steps.build_deploy.outcome == 'failure'
run: |
echo "::warning::GPU docs build failed on first attempt — purging ${{ steps.depot.outputs.path }}/compiled in case it's a stale precompile cache, then retrying once"
rm -rf "${{ steps.depot.outputs.path }}/compiled"
- name: Build and deploy (retry after cache purge)
if: steps.build_deploy.outcome == 'failure'
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
GKSwstype: 100
OCCIDATA_GPU_TIME: ${{ inputs.gpu_timeout_minutes }}
run: |
${OCCIDATA_GPU_RUN:-} julia --project=docs/ -e 'ENV["GKSwstype"]="nul"; include("docs/make.jl")'
echo "📂 Listing docs/build/assets:"
ls -R docs/build/assets || true