Skip to content

Commit afb7688

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

File tree

1 file changed

+179
-0
lines changed

1 file changed

+179
-0
lines changed

‎.github/workflows/docs-sync.yml

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

0 commit comments

Comments
 (0)