Skip to content

Commit 45d81f7

Browse files
feltroidprimefeltroidprime
committed
Add GitHub Actions workflow for syncing documentation between main an… (#402)
1 parent 3ae871f commit 45d81f7

File tree

1 file changed

+180
-0
lines changed

1 file changed

+180
-0
lines changed

‎.github/workflows/docs-sync.yml

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# .github/workflows/docs-sync.yml
2+
#
3+
# Keep GitBook docs (docs/gitbook) and source code in sync.
4+
# ├─ create-docs-pr : docs ➜ main (PR auto-merges if docs-only)
5+
# └─ sync-main-to-docs : main ➜ docs (keeps non-docs files identical to main)
6+
7+
name: Documentation Sync
8+
9+
permissions:
10+
contents: write # allow pushing branches / squash-merge
11+
pull-requests: write # allow opening / merging PRs
12+
issues: write # create & apply labels
13+
14+
on:
15+
push:
16+
branches: [ main, docs ] # run on every push to either branch
17+
defaults:
18+
run:
19+
shell: bash # strict mode added in scripts
20+
21+
concurrency:
22+
group: docs-sync-${{ github.ref }}
23+
cancel-in-progress: true
24+
25+
jobs:
26+
#───────────────────────────────────────────────────────────────────────────────
27+
# A. docs ➜ main – single rolling PR on branch: docs-sync
28+
#───────────────────────────────────────────────────────────────────────────────
29+
create-docs-pr:
30+
if: >-
31+
github.event.ref == 'refs/heads/docs' &&
32+
( github.actor == 'gitbook-com[bot]' ||
33+
github.actor == 'gitbook-io[bot]' ||
34+
contains(github.event.head_commit.message, '[gitbook]') )
35+
runs-on: ubuntu-latest
36+
37+
steps:
38+
# 1️⃣ Check out the latest MAIN in a clean worktree
39+
- uses: actions/checkout@v4
40+
with:
41+
ref: main
42+
fetch-depth: 0
43+
persist-credentials: false
44+
45+
- run: |
46+
git config user.name "GitBook Docs Bot"
47+
git config user.email "[email protected]"
48+
49+
# 2️⃣ Overlay docs/gitbook from the docs branch
50+
- name: Sync docs/gitbook from docs branch
51+
run: |
52+
set -euo pipefail
53+
git fetch --quiet origin docs
54+
git checkout origin/docs -- docs/gitbook
55+
56+
# Exit early if nothing changed
57+
if git diff --quiet; then
58+
echo "No documentation changes — skipping PR."
59+
echo "SKIP_PR=true" >>"$GITHUB_ENV"
60+
fi
61+
62+
# 3️⃣ Commit the changes (only if any)
63+
- name: Commit docs update
64+
if: env.SKIP_PR != 'true'
65+
run: |
66+
set -euo pipefail
67+
git add docs/gitbook
68+
git commit -m "📚 Sync docs/gitbook @ ${{ github.sha }}"
69+
70+
# 4️⃣ Create / update the rolling PR on branch docs-sync
71+
- uses: peter-evans/create-pull-request@v7
72+
if: env.SKIP_PR != 'true'
73+
id: cpr
74+
with:
75+
token: ${{ secrets.GITHUB_TOKEN }}
76+
branch: docs-sync # ← single, reusable branch
77+
base: main
78+
title: "📚 Update documentation from GitBook"
79+
commit-message: "📚 docs(branch=docs) → main @ ${{ github.sha }}"
80+
labels: documentation,auto-generated
81+
delete-branch: true # auto-delete after you squash-merge
82+
83+
# 5️⃣ Add an extra label & comment if non-docs files slipped in
84+
- name: Flag mixed-content PRs
85+
if: env.SKIP_PR != 'true'
86+
env:
87+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
88+
run: |
89+
set -euo pipefail
90+
# If *any* file outside docs/gitbook changed, add label + comment
91+
if git diff --name-only origin/main | grep -vqE '^docs/gitbook/'; then
92+
gh pr edit "${{ steps.cpr.outputs.pull-request-number }}" \
93+
--add-label "needs-review"
94+
gh pr comment "${{ steps.cpr.outputs.pull-request-number }}" \
95+
--body "⚠️ *Mixed content* – this PR touches files outside \`docs/gitbook\`. Please review."
96+
fi
97+
98+
#───────────────────────────────────────────────────────────────────────────────
99+
# B. main ➜ docs – keep non-docs files identical to main
100+
#───────────────────────────────────────────────────────────────────────────────
101+
sync-main-to-docs:
102+
if: >-
103+
github.event.ref == 'refs/heads/main' &&
104+
!contains(github.event.head_commit.message, '[gitbook]') &&
105+
github.actor != 'gitbook-com[bot]' &&
106+
github.actor != 'gitbook-io[bot]'
107+
runs-on: ubuntu-latest
108+
109+
steps:
110+
# 1) Check out docs branch (create it if it doesn’t exist)
111+
- uses: actions/checkout@v4
112+
with:
113+
ref: docs
114+
fetch-depth: 0
115+
persist-credentials: false
116+
117+
- name: Configure Git
118+
run: |
119+
git config user.name "GitHub Docs Sync"
120+
git config user.email "[email protected]"
121+
git fetch origin main --tags --prune
122+
123+
# 2) Bring code (everything except docs/gitbook) up to date with main
124+
- name: Sync non-docs files from main
125+
run: |
126+
set -euo pipefail
127+
TMP=$(mktemp -d)
128+
# Save current docs
129+
if [[ -d docs/gitbook ]]; then
130+
cp -R docs/gitbook "$TMP/"
131+
fi
132+
# Overwrite working tree with main
133+
git checkout origin/main -- .
134+
# Restore docs
135+
rm -rf docs/gitbook
136+
if [[ -d "$TMP/gitbook" ]]; then
137+
mkdir -p docs
138+
cp -R "$TMP/gitbook" docs/
139+
fi
140+
rm -rf "$TMP"
141+
142+
# Stage everything, but commit only if something changed
143+
git add -A
144+
if git diff --cached --quiet; then
145+
echo "No updates required – docs branch already matches main."
146+
exit 0
147+
fi
148+
149+
git commit -m "🔄 Sync non-docs files from main @ ${{ github.sha }}"
150+
151+
# ─── 3) Open (or update) a PR towards docs ─────────────────────────────
152+
- uses: peter-evans/create-pull-request@v7
153+
id: cpr
154+
with:
155+
token: ${{ secrets.GITHUB_TOKEN }}
156+
# the current HEAD contains the commit we just made
157+
branch: main-sync-${{ github.sha }}-${{ github.run_id }}
158+
base: docs
159+
commit-message: "🔄 Sync non-docs files from main @ ${{ github.sha }}"
160+
title: "🔄 Sync main → docs (non-docs files)"
161+
body: |
162+
This PR keeps the **docs** branch in sync with **main** for every file \
163+
**outside** `docs/gitbook/`.
164+
165+
Source commit: ${{ github.sha }}
166+
167+
> 🤖 _docs-sync workflow_
168+
labels: documentation,auto-generated,auto-merge
169+
delete-branch: true
170+
draft: false # open as a normal PR
171+
172+
# ─── 4) Enable auto-merge; will complete when checks are green ─────────
173+
- name: Enable auto-merge
174+
if: steps.cpr.outputs.pull-request-number
175+
env:
176+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
177+
run: |
178+
gh pr merge ${{ steps.cpr.outputs.pull-request-number }} \
179+
--auto --squash --delete-branch --repo "$GITHUB_REPOSITORY" || \
180+
echo "Auto-merge pending required checks."

0 commit comments

Comments
 (0)