feat(ci): add lychee broken link test

skjnldsv · skjnldsv · commit e16fd0608c6c · 2026-04-07T18:08:39.000+02:00
Signed-off-by: skjnldsv &lt;skjnldsv@protonmail.com&gt;
diff --git a/.github/workflows/generate-top-index.yml b/.github/workflows/generate-top-index.yml
@@ -61,15 +61,25 @@ jobs:
         git config --local user.email "nextcloud-command@users.noreply.github.com"
         git config --local user.name "nextcloud-command"
     
-    - name: Commit and push changes
+    - name: Create Pull Request for documentation index deployment
       if: github.event_name == 'push'
-      run: |
-        # Move the generated index.html and static files to the root of the gh-pages branch
-        rm -rf index.html static/
-        mv /tmp/index.html index.html
-        mv /tmp/static/ static/
-        git add index.html static/
-        git commit -m "chore: update index.html for documentation" || echo "No changes to commit"
-        git push origin gh-pages || echo "Nothing to push (expected if no changes)"
+      uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
+      id: cpr
+      with:
+        token: ${{ secrets.COMMAND_BOT_PAT }}
+        commit-message: 'chore: deploy documentation index for ${{ github.ref_name }}'
+        committer: nextcloud-command <nextcloud-command@users.noreply.github.com>
+        author: nextcloud-command <nextcloud-command@users.noreply.github.com>
+        signoff: true
+        branch: 'automated/deploy/documentation-index-${{ github.ref_name }}'
+        base: gh-pages
+        title: 'Deploy documentation index for ${{ needs.stage.outputs.branch_name }}'
+        body: 'Automated documentation index deployment from branch ${{ github.ref_name }}'
+        delete-branch: true
+        labels: 'automated, 3. to review'
+  
+    - name: Enable Pull Request Automerge
+      if: github.event_name == 'push'
+      run: gh pr merge --merge --auto "${{ steps.cpr.outputs.pull-request-number }}"
       env:
         GH_TOKEN: ${{ secrets.COMMAND_BOT_PAT }}
diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml
@@ -58,49 +58,42 @@ jobs:
     - name: Checkout repository
       uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-    - name: Configure apt cache to use /dev/shm
+    - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+      with:
+        python-version: '3.12'
+        cache: 'pip'
+
+    - name: Install pip dependencies
+      run: pip install -r requirements.txt
+
+    - name: Configure apt cache to use /tmp for caching LaTeX packages
       if: ${{ matrix.manual.build_pdf_path }}
       run: |
-        mkdir -p /dev/shm/apt/cache/archives
-        echo 'Dir::Cache::archives "/dev/shm/apt/cache/archives";' | sudo tee /etc/apt/apt.conf.d/apt-cache-shm
+        mkdir -p /tmp/apt/cache/archives
+        echo 'Dir::Cache::archives "/tmp/apt/cache/archives";' | sudo tee /etc/apt/apt.conf.d/apt-cache-tmp
 
     - name: Cache LaTeX apt packages
       if: ${{ matrix.manual.build_pdf_path }}
       uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
       with:
-        path: /dev/shm/apt/cache/archives
+        path: /tmp/apt/cache/archives
         key: latex-apt-${{ runner.os }}-${{ hashFiles('.github/workflows/sphinxbuild.yml') }}
         restore-keys: |
           latex-apt-${{ runner.os }}-
 
     - name: Install LaTeX dependencies
       if: ${{ matrix.manual.build_pdf_path }}
       run: |
+        # Install required packages for PDF generation via LaTeX
         sudo DEBIAN_FRONTEND=noninteractive apt-get update
-        sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \
-          --no-install-recommends \
-          python3-pil \
-          python3-pip \
-          texlive-fonts-recommended \
-          latexmk \
-          texlive-latex-extra \
-          texlive-latex-recommended \
-          texlive-xetex \
-          texlive-fonts-extra-links \
-          texlive-fonts-extra \
-          xindy
+        sudo DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+          python3-pil python3-pip texlive-fonts-recommended latexmk \
+          texlive-latex-extra texlive-latex-recommended texlive-xetex \
+          texlive-fonts-extra-links texlive-fonts-extra xindy
 
     - name: Fix apt cache ownership for caching
       if: ${{ matrix.manual.build_pdf_path }}
-      run: sudo chown -R $(id -u):$(id -g) /dev/shm/apt/cache/archives
-
-    - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
-      with:
-        python-version: '3.12'
-        cache: 'pip'
-
-    - name: Install pip dependencies
-      run: pip install -r requirements.txt
+      run: sudo chown -R $(id -u):$(id -g) /tmp/apt/cache/archives
 
     - name: Build html documentation
       run: cd ${{ matrix.manual.directory }} && make ${{ matrix.manual.make_target }}
@@ -134,14 +127,17 @@ jobs:
         name: ${{ matrix.manual.name }}
         path: ${{ matrix.manual.directory }}/${{ matrix.manual.build_path }}
 
-  deploy:
-    name: Deploy pages
+  # Assembles all artifacts into the gh-pages layout and uploads a single
+  # "staged" artifact that both `check` and `deploy` consume.  Doing the
+  # assembly once avoids repeating the checkout + merge logic in both jobs.
+  stage:
+    name: Stage documentation
     needs: build
     runs-on: ubuntu-latest
-    if: github.event_name == 'push'  # Only deploy on push, not PR
 
-    permissions:
-      contents: write
+    outputs:
+      branch_name: ${{ steps.branch.outputs.branch_name }}
+      version_name: ${{ steps.branch.outputs.version_name }}
 
     steps:
     - name: Cache git metadata
@@ -153,7 +149,7 @@ jobs:
           git-metadata-${{ github.sha }}
           git-metadata
 
-    - name: Checkout Github Pages branch
+    - name: Checkout gh-pages (for redirect sources)
       uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         ref: gh-pages
@@ -199,65 +195,142 @@ jobs:
 
     - name: Merge ${{ steps.branch.outputs.branch_name }} documentation artifacts into gh-pages
       run: |
-        # List artifacts
-        ls -la artifacts/*/
-
-        # Cleanup old documentation
-        rm -rf ${{ steps.branch.outputs.branch_name }}
+        # Remove old documentation for this branch
         rm -rf server/${{ steps.branch.outputs.branch_name }}
-        mkdir -p server/${{ steps.branch.outputs.branch_name }}
-
-        # Copy all built documentation into dedicated subdirectories
-        for artifact in artifacts/*; do
-          if [ -d "$artifact" ]; then
-            manual_name="$(basename "$artifact")"
-            mkdir -p "server/${{ steps.branch.outputs.branch_name }}/$manual_name"
-            cp -r "$artifact/"* "server/${{ steps.branch.outputs.branch_name }}/$manual_name/"
-          fi
-        done
-
-        # Move pdf files to the root of the branch_name
-        mv server/${{ steps.branch.outputs.branch_name }}/*/*.pdf server/${{ steps.branch.outputs.branch_name }}/ || true
-
-        # If this is the highest stable branch, also deploy to its versioned folder
+        
+        # Move all documentation artifacts into the server directory
+        mv artifacts/* server/ || true
+        
+        # Move PDF files to branch root
+        mv server/*/*.pdf server/${{ steps.branch.outputs.branch_name }}/ || true
+        
+        # For stable branches, also deploy to versioned folder (e.g., server/28/)
         if [ -n "${{ steps.branch.outputs.version_name }}" ]; then
           rm -rf server/${{ steps.branch.outputs.version_name }}
           cp -r server/${{ steps.branch.outputs.branch_name }} server/${{ steps.branch.outputs.version_name }}
         fi
-
-        # Cleanup
+        
+        # Clean up empty directories
         find . -type d -empty -delete
-        rm -rf artifacts
 
     - name: Add various redirects for go.php and user_manual english version
       run: |
-        # Fetch source branches so git checkout origin/... works from the gh-pages checkout
-        git fetch origin ${{ github.event.repository.default_branch }} ${{ github.ref_name }}
+        # Fetch default branch to get base redirect files
+        git fetch origin ${{ github.event.repository.default_branch }}
+        
+        # Checkout redirect files from default branch
+        git checkout origin/${{ github.event.repository.default_branch }} -- go.php/index.html user_manual/index.html
+        
+        # Create deployment directories and move redirects into place
+        mkdir -p server/${{ steps.branch.outputs.branch_name }}/{go.php,user_manual}
+        mv go.php/index.html server/${{ steps.branch.outputs.branch_name }}/go.php/
+        mv user_manual/index.html server/${{ steps.branch.outputs.branch_name }}/user_manual/
+
+    - name: Upload staged site
+      uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+      with:
+        name: staged-site
+        path: server/
 
-        # Generate go.php redirect from main branch
-        git checkout origin/${{ github.event.repository.default_branch }} -- go.php/index.html
-        mkdir -p server/${{ steps.branch.outputs.branch_name }}/go.php
-        mv go.php/index.html server/${{ steps.branch.outputs.branch_name }}/go.php/index.html
+  check:
+    name: Check staged documentation
+    needs: stage
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Download staged site
+      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+      with:
+        name: staged-site
+        path: server/
+
+    - name: Check for broken links with lychee
+      uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0
+      with:
+        fail: true
+        token: ${{ secrets.GITHUB_TOKEN }}
+        jobSummary: true
+        args: |
+          --offline --no-progress --verbose
+          --remap "https://docs.nextcloud.com/server/${{ needs.stage.outputs.branch_name }} file://$(pwd)/server/${{ needs.stage.outputs.branch_name }}"
+          'server/${{ needs.stage.outputs.branch_name }}/**/*.html'
 
-        # Generate user_manual english redirect
-        git checkout origin/${{ github.ref_name }} -- user_manual/index.html
-        mkdir -p server/${{ steps.branch.outputs.branch_name }}/user_manual
-        mv user_manual/index.html server/${{ steps.branch.outputs.branch_name }}/user_manual/index.html
 
-    - name: Commit ${{ steps.branch.outputs.branch_name }} documentation and push to gh-pages
+  deploy:
+    name: Deploy documentation to gh-pages
+    needs: [stage, check]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+    - name: Cache git metadata
+      uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+      with:
+        path: .git
+        key: git-metadata-${{ github.sha }}
+        restore-keys: |
+          git-metadata-${{ github.sha }}
+          git-metadata
+
+    - name: Checkout gh-pages branch
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      with:
+        ref: gh-pages
+        fetch-depth: 0
+        persist-credentials: false
+
+    - name: Download staged site
+      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+      with:
+        name: staged-site
+        path: incoming/
+
+    - name: Apply staged site to gh-pages working tree
       run: |
-        git config --local user.email "nextcloud-command@users.noreply.github.com"
-        git config --local user.name "nextcloud-command"
-        git add .
-        git diff --staged --quiet || git commit -m "chore: deploy documentation for ${{ steps.branch.outputs.branch_name }}"
-        # Ensure we are up to date with the remote gh-pages branch
-        git pull --rebase origin gh-pages || true
-        git push origin gh-pages || echo "Nothing to push (expected if no changes)"
+        branch="${{ needs.stage.outputs.branch_name }}"
+        version="${{ needs.stage.outputs.version_name }}"
+
+        rm -rf "server/${branch}"
+        cp -r "incoming/${branch}" "server/${branch}"
+
+        if [ -n "${version}" ]; then
+          rm -rf "server/${version}"
+          cp -r "incoming/${version}" "server/${version}"
+        fi
+
+        find . -type d -empty -delete
+
+        # QUickly log the directory structure for debugging purposes
+        echo "Directory structure after applying staged site:"
+        find server -type d -print
+
+    - name: Create Pull Request for documentation deployment
+      uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
+      id: cpr
+      with:
+        token: ${{ secrets.COMMAND_BOT_PAT }}
+        commit-message: 'chore: deploy documentation for ${{ needs.stage.outputs.branch_name }}'
+        committer: nextcloud-command <nextcloud-command@users.noreply.github.com>
+        author: nextcloud-command <nextcloud-command@users.noreply.github.com>
+        signoff: true
+        branch: 'automated/deploy/documentation-${{ needs.stage.outputs.branch_name }}'
+        base: gh-pages
+        title: 'Deploy documentation for ${{ needs.stage.outputs.branch_name }}'
+        body: 'Automated documentation deployment from branch ${{ github.ref_name }}'
+        delete-branch: true
+        labels: 'automated, 3. to review'
+  
+    - name: Enable Pull Request Automerge
+      run: gh pr merge --merge --auto "${{ steps.cpr.outputs.pull-request-number }}"
       env:
         GH_TOKEN: ${{ secrets.COMMAND_BOT_PAT }}
 
   summary:
-    needs: build
+    needs: [build, check]
     runs-on: ubuntu-latest-low
     if: always()
 
@@ -267,6 +340,5 @@ jobs:
     name: build-deploy-summary
 
     steps:
-      # Only check if the build was successful
       - name: Summary status
-        run: if ${{ needs.build.result != 'success' }}; then exit 1; fi
+        run: if ${{ needs.build.result != 'success' || needs.check.result != 'success' }}; then exit 1; fi
