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
name: docs-sync
# The published documentation follows `main`, never `dev`.
#
# `main` is reached exclusively through a `dev` → `main` pull request, so what
# lands here is what was delivered — which is exactly what the site should
# serve. Triggering on `dev` would publish pages describing behaviour nobody
# can install yet; triggering on tags would be worse still, since GitHub's
# `v*.*.*` glob also matches `v0.8.0-rc.4` (the trap `release.yml` guards
# against by hand) and every release candidate's docs would go live as stable.
#
# The split of work is deliberate: this repo owns the documentation sources
# (`docs/`, `changelogs/`) and nothing else. The conversion script, the
# Starlight site and the deploy live in `kbrdn1/kbrdn-docs`, so this workflow
# only rings the bell. Doing the sync here would drag a Bun monorepo into the
# CLI's CI for a build this repo cannot verify.
#
# Bootstrap: see CONTRIBUTING.md > Releases > Documentation site.
on:
push:
branches:
# Kept in step with the roots the site's sync script reads. A root dropped
# here fails silently — the site just stops refreshing — so
# `tests/release_workflow_tests.rs` pins the list.
paths:
- 'docs/**'
- 'changelogs/**'
# Not documentation, but the site reads it: the sync script pulls the
# `[package]` version out of it for the release badge in the header.
# A release usually moves `changelogs/` in the same push, so this only
# matters when a version bump travels alone, which is exactly the case
# nobody would think to check.
- 'Cargo.toml'
workflow_dispatch:
# The dispatch authenticates with a PAT scoped to the docs repository; the
# workflow token needs nothing at all.
permissions:
jobs:
notify:
name: notify kbrdn-docs
runs-on: ubuntu-latest
# While DOCS_SITE_TOKEN is being provisioned the first time, a missing
# secret would paint the merge to `main` red for a docs refresh that can be
# re-driven by hand at any time (`gh workflow run docs-sync.yml`). Flip to
# false once the first dispatch has succeeded.
continue-on-error: true
steps:
- name: verify DOCS_SITE_TOKEN is configured
env:
DOCS_SITE_TOKEN: ${{ secrets.DOCS_SITE_TOKEN }}
run: |
if [ -z "${DOCS_SITE_TOKEN:-}" ]; then
echo "::error::DOCS_SITE_TOKEN secret is not configured."
echo "Bootstrap: see CONTRIBUTING.md > Releases > Documentation site."
exit 1
fi
# No checkout: the docs repository reads this repo itself, at the commit
# `main` points to when it runs. Two merges in quick succession therefore
# converge on the later one instead of racing, and this job stays a
# single API call with nothing on disk to leak.
- name: dispatch the docs sync
env:
GH_TOKEN: ${{ secrets.DOCS_SITE_TOKEN }}
run: |
gh api repos/kbrdn1/kbrdn-docs/dispatches \
--method POST \
-f event_type=gwm-docs