Skip to content

Commit 82c9f4d

Browse files
Ilyes512Ilyes512
authored
Merge pull request #101 from specsnl/ci/GH-91-docs-deploy
Deploy the docs site to GitHub Pages (GH-91)
2 parents 5181d38 + ad67d2a commit 82c9f4d

2 files changed

Lines changed: 125 additions & 0 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
# Serialised against every other Pages deployment, and never cancelled — a
14+
# half-finished deploy would leave the live site on a partial artifact.
15+
concurrency:
16+
group: pages
17+
cancel-in-progress: false
18+
19+
jobs:
20+
changes:
21+
name: Changes Filter
22+
runs-on: ubuntu-24.04
23+
outputs:
24+
docs: ${{ steps.filter.outputs.docs }}
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@v7
28+
29+
- uses: dorny/paths-filter@v4
30+
id: filter
31+
with:
32+
filters: |
33+
docs:
34+
- 'docs/**'
35+
- '.github/workflows/docs.yml'
36+
37+
build:
38+
name: Build
39+
runs-on: ubuntu-24.04
40+
needs: changes
41+
if: ${{ github.event_name == 'workflow_dispatch' || needs.changes.outputs.docs == 'true' }}
42+
steps:
43+
- name: Checkout
44+
uses: actions/checkout@v7
45+
with:
46+
# enableGitInfo needs the history to date each page.
47+
fetch-depth: 0
48+
49+
- name: Setup Hugo
50+
uses: peaceiris/actions-hugo@v3
51+
with:
52+
# Keep in step with the hugomods/hugo tag in compose.yml.
53+
hugo-version: 0.161.1
54+
extended: true
55+
56+
- name: Cache Hugo modules
57+
uses: actions/cache@v6
58+
with:
59+
path: /tmp/hugo_cache
60+
key: ${{ runner.os }}-hugo-${{ hashFiles('docs/go.sum') }}
61+
restore-keys: |
62+
${{ runner.os }}-hugo-
63+
64+
- name: Build
65+
env:
66+
HUGO_CACHEDIR: /tmp/hugo_cache
67+
HUGO_ENVIRONMENT: production
68+
run: hugo --minify
69+
working-directory: docs
70+
71+
- name: Upload Pages artifact
72+
uses: actions/upload-pages-artifact@v5
73+
with:
74+
path: docs/public
75+
76+
deploy:
77+
name: Deploy
78+
runs-on: ubuntu-24.04
79+
needs: build
80+
environment:
81+
name: github-pages
82+
url: ${{ steps.deployment.outputs.page_url }}
83+
steps:
84+
- name: Deploy to GitHub Pages
85+
id: deployment
86+
uses: actions/deploy-pages@v5

‎docs/content/docs/architecture/distribution.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,45 @@ does not, the release fails at `loading go mod information`, before it builds an
9696
sets `GOTOOLCHAIN=auto` so `go.mod` stays the only pin, matching the workflow, which resolves its
9797
toolchain from `go-version-file: go.mod`.
9898

99+
## The documentation site
100+
101+
This site is the other thing the repository publishes, and it ships on its own schedule: not on a
102+
tag, but on every push to `main` that touches `docs/**` or the workflow itself.
103+
[`.github/workflows/docs.yml`](https://github.com/specsnl/labelsync/blob/main/.github/workflows/docs.yml)
104+
runs `hugo --minify` in `docs/` and hands `docs/public/` to `actions/deploy-pages`. There is no
105+
`gh-pages` branch: Pages is configured with **GitHub Actions** as its source, so the artifact the
106+
workflow uploads *is* the deployment.
107+
108+
Three details are load-bearing:
109+
110+
- **`fetch-depth: 0`.** `hugo.toml` sets `enableGitInfo`, which dates each page from the last commit
111+
that touched it. A shallow clone has no such commit for most files, and the dates silently
112+
collapse onto the checkout.
113+
- **`concurrency: { group: pages, cancel-in-progress: false }`.** Pages allows one deployment at a
114+
time. Cancelling in progress would abort a deploy midway and leave the live site on whatever the
115+
half-uploaded artifact contained, so runs queue instead.
116+
- **The Hugo version is pinned to the `hugomods/hugo` tag in `compose.yml`.** Hextra is consumed as
117+
a Hugo module and tracks Hugo's template API; a floating `latest` in CI means the site that
118+
builds locally is not the site that builds on `main`. One version, two places, kept in step by
119+
hand.
120+
121+
The theme itself is cached across runs by `docs/go.sum`, which is why the module download does not
122+
show up in the build time of a typical docs change.
123+
124+
### The custom domain
125+
126+
`labelsync.specs.dev` is set in Settings → Pages rather than in a `CNAME` file under
127+
`docs/static/` — the same arrangement as `cli.specs.dev`. Keeping it in settings means a local
128+
`hugo` build never emits a `CNAME` that could disagree with what the repository is actually
129+
configured to serve.
130+
131+
DNS is a `CNAME` at `labelsync.specs.dev` pointing at **`specsnl.github.io`** — the *account*, not
132+
the repository. A record pointing at `labelsync.github.io` resolves anyway, because `*.github.io`
133+
is a wildcard onto the same Pages edge addresses and the edge routes on the `Host` header, but
134+
GitHub's Pages DNS check flags it and it can block certificate issuance. Domain ownership is
135+
already proven by the `_github-pages-challenge-specsnl` TXT record on the `specs.dev` apex, which
136+
covers subdomains, so no per-repository verification step is needed.
137+
99138
---
100139

101140
The design record this grew out of — including why a `gh` CLI extension was considered and rejected

0 commit comments

Comments
 (0)