diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
index 76d0331eac..c7df9b4839 100644
--- a/.github/workflows/docs.yaml
+++ b/.github/workflows/docs.yaml
@@ -11,9 +11,7 @@ on:
workflow_dispatch:
permissions:
- contents: read
- pages: write
- id-token: write
+ contents: write
jobs:
pre:
@@ -32,7 +30,7 @@ jobs:
case $branch in
famedly-release/v*)
- # strip 'release-' from the name for release branches.
+ # strip 'famedly-release/' from the name for release branches.
branch="${branch#famedly-release/v}"
;;
master)
@@ -47,7 +45,7 @@ jobs:
branch-version: ${{ steps.vars.outputs.branch-version }}
################################################################################
- build:
+ pages-docs:
name: GitHub Pages
runs-on: ubuntu-latest
needs:
@@ -72,10 +70,6 @@ jobs:
cargo install mdbook-linkcheck mdbook-mermaid
cargo install mdbook --no-default-features --features search --vers "${{ env.MDBOOK_VERSION }}" --locked
- - name: Setup Pages
- id: pages
- uses: actions/configure-pages@v5
-
- name: Set version of docs
run: echo 'window.SYNAPSE_VERSION = "${{ needs.pre.outputs.branch-version }}";' > ./docs/website_files/version.js
@@ -106,38 +100,37 @@ jobs:
yq < schema/synapse-config.schema.yaml \
> book/schema/synapse-config.schema.json
- - name: Restructure for versioning
+ # Deploy to the target directory without wiping other versions.
+ # We use a git worktree so we can merge into gh-pages incrementally,
+ # equivalent to what peaceiris/actions-gh-pages (action used by element/synapse)
+ # does with destination_dir.
+ - name: Deploy to gh-pages
run: |
- # Create a clean output directory
- mkdir -p _site/${{ needs.pre.outputs.branch-version }}
+ git config user.name "github-actions[bot]"
+ git config user.email "github-actions[bot]@users.noreply.github.com"
- # Move the built book (and schemas) into the versioned subdirectory
- mv book/* _site/${{ needs.pre.outputs.branch-version }}/
+ VERSION="${{ needs.pre.outputs.branch-version }}"
- # Create a root index.html that redirects to the versioned docs
- # This ensures https://famedly.github.io/synapse/ still works
- if [ "${{ needs.pre.outputs.branch-version }}" = "latest" ]; then
- echo '' > _site/index.html
+ # Set up a worktree pointing at the gh-pages branch (create it if absent).
+ git fetch origin gh-pages || true
+ if git show-ref --verify --quiet refs/remotes/origin/gh-pages; then
+ git worktree add gh-pages-dir origin/gh-pages
+ else
+ git worktree add --orphan -b gh-pages gh-pages-dir
fi
- - name: Upload artifact
- uses: actions/upload-pages-artifact@v3
- with:
- path: ./_site
-
- deploy:
- if: ${{ github.ref == 'refs/heads/master' }}
- # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
- # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
- concurrency:
- group: "pages"
- cancel-in-progress: false
- environment:
- name: github-pages
- url: ${{ steps.deployment.outputs.page_url }}
- runs-on: ubuntu-latest
- needs: build
- steps:
- - name: Deploy to GitHub Pages
- id: deployment
- uses: actions/deploy-pages@v4
+ # Replace only this version's directory, preserving all others.
+ rm -rf "gh-pages-dir/$VERSION"
+ mkdir -p "gh-pages-dir/$VERSION"
+ cp -r book/. "gh-pages-dir/$VERSION/"
+
+ # Ensure a root redirect to latest exists.
+ if [ ! -f gh-pages-dir/index.html ]; then
+ echo '' \
+ > gh-pages-dir/index.html
+ fi
+
+ cd gh-pages-dir
+ git add .
+ git diff --staged --quiet || git commit -m "docs: deploy $VERSION"
+ git push origin HEAD:gh-pages