Skip to content

Commit 3e87a3e

Browse files
medvednikovmedvednikov
authored
ci: deploy docs.vlang.io from GitHub Actions (fix vlang#27038) (vlang#27520)
1 parent 42fc2c0 commit 3e87a3e

1 file changed

Lines changed: 114 additions & 0 deletions

File tree

‎.github/workflows/docs_site_ci.yml‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
name: docs.vlang.io deploy
2+
3+
### Regenerate https://docs.vlang.io/ (the GitHub Pages site served from the
4+
### `main` branch of https://github.com/vlang/docs ), on every change to
5+
### doc/docs.md that lands on master.
6+
###
7+
### Historically docs.vlang.io was updated by the FreeBSD machine that also runs
8+
### cmd/tools/fast/fast.v . When that single machine stops, the site silently
9+
### goes stale (see issue #27038, where it was stuck at the 2026-02-09 snapshot).
10+
### Generating and deploying from CI removes that single point of failure, the
11+
### same way modules.vlang.io is deployed from module_docs_ci.yml .
12+
13+
on:
14+
workflow_dispatch:
15+
push:
16+
branches:
17+
- master
18+
paths:
19+
- 'doc/docs.md'
20+
- '**/docs_site_ci.yml'
21+
22+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
23+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
24+
concurrency:
25+
group: docs_site-${{ github.workflow }}-${{ github.ref }}
26+
cancel-in-progress: ${{ !contains(github.ref, 'master')}}
27+
28+
jobs:
29+
deploy-docs-site:
30+
runs-on: ubuntu-latest
31+
timeout-minutes: 20
32+
steps:
33+
- uses: actions/checkout@v7
34+
- uses: ./.github/actions/cache-apt-packages-action
35+
- name: Build V
36+
run: make -j4 && ./v symlink
37+
- name: Install dependencies (the docs generator uses the markdown module)
38+
run: ./v retry -- ./v install markdown
39+
40+
- name: Generate the HTML pages from doc/docs.md
41+
run: |
42+
set -e
43+
# The generator (the `generator` branch of vlang/docs) fetches
44+
# doc/docs.md from the master branch of vlang/v, transforms it into one
45+
# HTML page per section, and writes them into its own output/ folder.
46+
rm -rf docs_generator
47+
./v retry -- git clone --depth=1 --branch generator https://github.com/vlang/docs docs_generator
48+
./v run docs_generator/.
49+
[ -f docs_generator/output/introduction.html ]
50+
51+
- name: Deploy to vlang/docs (main branch -> docs.vlang.io)
52+
if: github.event_name != 'pull_request' && github.repository == 'vlang/v' && github.ref == 'refs/heads/master'
53+
run: |
54+
set -e
55+
git config --global user.email "vlang-bot@users.noreply.github.com"
56+
git config --global user.name "vlang-bot"
57+
58+
COMMIT_HASH="$(git rev-parse --short HEAD)"
59+
COMMIT_MSG="$(git log -1 --pretty='%s' HEAD)"
60+
61+
rm -rf docs_site
62+
./v retry -- git clone --depth=1 --branch main "https://vlang-bot:${{ secrets.VLANG_BOT_SECRET }}@github.com/vlang/docs.git" docs_site
63+
64+
# The legacy FreeBSD uploader (cmd/tools/fast/fast.v) may still be
65+
# pushing to vlang/docs main too, so our push can be rejected as
66+
# non-fast-forward. `v retry` would only rerun the same push, never
67+
# fetching the new tip, so retry here by re-syncing onto the latest main
68+
# and pushing again. The sync is idempotent, so re-applying it on top of
69+
# whatever landed meanwhile is safe.
70+
deploy_attempts=5
71+
for attempt in $(seq 1 "${deploy_attempts}"); do
72+
git -C docs_site fetch --depth=1 origin main
73+
git -C docs_site reset --hard FETCH_HEAD
74+
75+
# Sync the freshly generated pages onto the published site. --delete so
76+
# that pages/assets removed or renamed in doc/docs.md do not linger as
77+
# stale files, but protect the site-only files at the repo root that the
78+
# generator does not produce (git metadata, CNAME, .nojekyll, README.md,
79+
# favicon.ico and the legacy build.vsh).
80+
rsync -a --delete \
81+
--exclude '/.git' \
82+
--exclude '/.gitattributes' \
83+
--exclude '/.gitignore' \
84+
--exclude '/.nojekyll' \
85+
--exclude '/CNAME' \
86+
--exclude '/README.md' \
87+
--exclude '/favicon.ico' \
88+
--exclude '/build.vsh' \
89+
docs_generator/output/ docs_site/
90+
91+
git -C docs_site add -A
92+
# `git diff --cached --quiet` exits 0 with nothing staged, 1 when there
93+
# are staged changes, and >1 on a real error - so only 1 means "deploy".
94+
set +e
95+
git -C docs_site diff --cached --quiet
96+
diff_rc=$?
97+
set -e
98+
if [ "${diff_rc}" -eq 0 ]; then
99+
echo "docs.vlang.io is already up to date for ${COMMIT_HASH}; nothing to deploy."
100+
exit 0
101+
elif [ "${diff_rc}" -ne 1 ]; then
102+
echo "::error::git diff --cached failed with exit code ${diff_rc}" >&2
103+
exit "${diff_rc}"
104+
fi
105+
git -C docs_site commit -m "update docs for commit ${COMMIT_HASH} - ${COMMIT_MSG}"
106+
107+
if git -C docs_site push origin main; then
108+
echo "docs.vlang.io updated for ${COMMIT_HASH} (attempt ${attempt})."
109+
exit 0
110+
fi
111+
echo "push to vlang/docs main was rejected (attempt ${attempt}/${deploy_attempts}); refetching and retrying..."
112+
done
113+
echo "::error::could not push to vlang/docs main after ${deploy_attempts} attempts" >&2
114+
exit 1

0 commit comments

Comments
 (0)