Migrate git-scm.com to a static site, generated via Hugo, served via GitHub Pages

.github/actions/deploy-to-github-pages/action.yml

@@ -0,0 +1,183 @@
+name: 'Run Hugo/Pagefind and deploy to GitHub Pages'
+description: 'Runs Hugo and Pagefind and then deploys the result to GitHub Pages.'
+# This composite Action requires the following things in the calling workflow:
+#
+# permissions:
+#   contents: write # to push changes (if any)
+#   pages: write # to deploy to GitHub Pages
+#   id-token: write # to verify that the deployment source is legit
+# environment:
+#   name: github-pages
+#   url: ${{ steps.<id-of-deployment-step>.outputs.url }}
+inputs:
+  github-token:
+    description: The GitHub token used to create an authenticated client
+    default: ${{ github.token }}
+    required: true
+outputs:
+  url:
+    description: The URL to which the site was deployed
+    value: ${{ steps.deploy.outputs.page_url }}
+runs:
+  using: "composite"
+  steps:
+    - name: push changes (if needed)
+      shell: bash
+      run: |
+        test "$(git rev-parse HEAD)" = "$(git rev-parse refs/remotes/origin/${{ github.ref_name }})" ||
+        git push origin HEAD:${{ github.ref }}
+
+    - name: un-sparse worktree to prepare for deployment
+      shell: bash
+      run: git sparse-checkout disable
+
+    - name: setup GitHub Pages
+      id: pages
+      uses: actions/configure-pages@v5
+
+    - name: configure Hugo and Pagefind version
+      shell: bash
+      run: |
+        set -x &&
+        echo "HUGO_VERSION=$(sed -n 's/^ *hugo_version: *//p' <hugo.yml)" >>$GITHUB_ENV
+        echo "PAGEFIND_VERSION=$(sed -n 's/^ *pagefind_version: *//p' <hugo.yml)" >>$GITHUB_ENV
+
+    - name: install Hugo ${{ env.HUGO_VERSION }}
+      shell: bash
+      run: |
+        set -x &&
+        curl -Lo /tmp/hugo.deb https://github.com/gohugoio/hugo/releases/download/v$HUGO_VERSION/hugo_extended_${HUGO_VERSION}_linux-amd64.deb &&
+        sudo dpkg -i /tmp/hugo.deb
+
+    - name: run Hugo to build the pages
+      env:
+        HUGO_RELATIVEURLS: false
+      shell: bash
+      run: hugo config && hugo --baseURL "${{ steps.pages.outputs.base_url }}/"
+
+    - name: run Pagefind ${{ env.PAGEFIND_VERSION }} to build the search index
+      shell: bash
+      run: npx -y pagefind@${{ env.PAGEFIND_VERSION }} --site public
+
+    - name: Temporarily copy some Rails assets to help the transition
+      shell: bash
+      run: |
+        # To help with the transition from the Rails app to the Hugo/Pagefind site, where
+        # at least for a while the cached version of git-scm.com might be served via
+        # Cloudflare, according to the first transition attempt on Sep 20, 2024, potentially
+        # partially, i.e. _some_ assets might still be cached, _some_ others might not, let's
+        # copy the most prominent assets to the new page so that, say, the original front page
+        # won't fail to load the style sheet and Javascript libraries that it needs.
+        set -x &&
+        mkdir -p public/assets &&
+        for f in application-93865c5c820c24f4c599e8b9c544bcd8a0d03260f9b16c9ba80b6a00082112c9.css \
+          application-f7a750114a26afea236a5cc26f6ff3925a14c5901e9ea9018fb869432d0cbee3.js \
+          modernize-b3ebe0c31c24f230dc62179d3e1030d2e57a53b1668d9382c0a27dbd44a94beb.js
+        do
+          curl -Lfo public/assets/$f https://git-scm.com/assets/$f ||
+          echo "::error::could not copy $f from https://git-scm.com/" >&2
+        done
+
+    - name: upload GitHub Pages artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: ./public
+
+    - name: deploy
+      id: deploy
+      uses: actions/deploy-pages@v4
+
+    - name: construct `--remap` option for lychee
+      id: remap
+      shell: bash
+      run: |
+        base_url='${{ steps.pages.outputs.base_url }}'
+        echo "result=$(echo "$base_url" |
+          sed 's|^\(.*\)\(/git-scm\.com\)$|(\1)?\2(.*)|') file://$PWD/public\$2" \
+          >>$GITHUB_OUTPUT
+
+    - name: check for broken links
+      id: lychee
+      uses: lycheeverse/lychee-action@d4128702eae98bbc5ecf74df0165a8156c80920a # until an official version is out that includes https://github.com/lycheeverse/lychee/pull/1422
+      with:
+        lycheeVersion: nightly # until an official version includes https://github.com/lycheeverse/lychee/pull/1422
+        args: >-
+          --offline
+          --fallback-extensions html
+          --base '${{ steps.pages.outputs.base_url }}'
+          --remap '${{ steps.remap.outputs.result }}'
+          --exclude file:///path/to/repo.git/
+          --exclude file:///caminho/para/o/reposit%C3%B3rio.git/
+          --exclude file:///ruta/a/repositorio.git/
+          --exclude file:///sl%C3%B3%C3%B0/til/hirsla.git/
+          --exclude file:///Pfad/zum/Repo.git/
+          --exclude file:///chemin/du/d%C3%A9p%C3%B4t.git/
+          --exclude file:///srv/git/project.git
+          public/
+        output: lychee.md
+        jobSummary: true
+        fail: false
+        failIfEmpty: false # needed because its default overrides `fail = false`
+
+    - name: ${{ env.lychee_exit_code != '0' && 'maybe close' || 'open or update' }} link checker issue
+      uses: actions/github-script@v7
+      with:
+        github-token: ${{ inputs.github-token }}
+        script: |
+          const fs = await import('fs')
+          // GitHub issues can only have 64k characters in their body
+          const body = (s => {
+            if (s.length < 65535) return s
+            return s.replace(/^([^]{0,65000}\n)[^]*\n(.+)\n?$/, '$1\n[...]\n\n$2')
+          })(await fs.promises.readFile('lychee.md', 'utf8'))
+
+          const issues = await (async () => {
+            const req = { owner: context.repo.owner, repo: context.repo.repo }
+            const q = `"Link+Checker+Report"+in:title+is:issue+label:linkchecker+is:open+repo:${req.owner}/${req.repo}`
+            try {
+              return await github.rest.search.issuesAndPullRequests({ ...req, q, sort: 'created', per_page: 1 })
+            } catch (e) {
+              console.log(`Warning: ${e}; sleeping for 30 seconds and falling back to calling listForRepo()`)
+              await new Promise(r => setTimeout(r, 30000))
+
+              const issues = await github.rest.issues.listForRepo({...req, state: 'open', per_page: 100})
+              return {
+                data: {
+                  items: issues.data.filter(
+                    e => e.title === 'Link Checker Report'
+                    && e.labels.filter(l => l.name === 'linkchecker').length > 0
+                  )
+                }
+              }
+            }
+          })()
+
+          if (issues.data.items.length === 0) {
+            if (process.env.lychee_exit_code !== '0') {
+              await github.rest.issues.create({ ...req, title: 'Link Checker Report', body, labels: ['linkchecker'] })
+            }
+          } else {
+            req.issue_number = issues.data.items[0].number
+            await github.rest.issues.createComment({ ...req, body })
+            if (process.env.lychee_exit_code === '0') {
+              await github.rest.issues.update({ ...req, state: 'closed' })
+            }
+          }
+
+    - name: Install @playwright/test
+      shell: bash
+      run: npm install @playwright/test
+    - name: Edit /etc/hosts to map git-scm.com to GitHub
+      shell: bash
+      # This side-steps the Cloudflare caches
+      run: sudo sh -c 'echo "185.199.108.153 git-scm.com" >>/etc/hosts'
+    - name: Run Playwright tests
+      shell: bash
+      env:
+        PLAYWRIGHT_TEST_URL: ${{ steps.pages.outputs.base_url }}
+      run: npx playwright test --project=chrome
+    - uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: playwright-report
+        path: playwright-report/

.github/workflows/ci.yml

@@ -1,22 +1,85 @@
 name: CI
-on: pull_request
+on: [pull_request]
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
 
-    - name: ruby setup
-      uses: ruby/setup-ruby@v1
+    - name: configure Hugo and Pagefind version
+      run: |
+        set -x &&
+        echo "HUGO_VERSION=$(sed -n 's/^ *hugo_version: *//p' <hugo.yml)" >>$GITHUB_ENV
+        echo "PAGEFIND_VERSION=$(sed -n 's/^ *pagefind_version: *//p' <hugo.yml)" >>$GITHUB_ENV
+
+    - name: install Hugo ${{ env.HUGO_VERSION }}
+      run: |
+        set -x &&
+        curl -Lo /tmp/hugo.deb https://github.com/gohugoio/hugo/releases/download/v$HUGO_VERSION/hugo_extended_${HUGO_VERSION}_linux-amd64.deb &&
+        sudo dpkg -i /tmp/hugo.deb
+
+    - name: run Hugo to build the pages
+      run: hugo
+
+    - name: ensure that there are no absolute URLs
+      run: |
+        set -x
+        if git grep --untracked --no-exclude-standard "\\(href\|src\) *= *[\"']/" \
+          -- public/ ':^public/js/jquery*' >/tmp/abs-urls.txt
+        then
+          cat /tmp/abs-urls.txt
+          exit 1
+        fi
+
+    - name: run Pagefind ${{ env.PAGEFIND_VERSION }} to build the search index
+      run: npx -y pagefind@${{ env.PAGEFIND_VERSION }} --site public
+
+    - name: build tar archive
+      run: cd public && tar czvf ../pages.tar.gz *
+
+    - name: Upload build artifact
+      uses: actions/upload-artifact@v4
       with:
-        bundler-cache: true
+        name: pages
+        path: pages.tar.gz
 
-    - name: rails setup
-      run: bundle exec rake db:create db:schema:load
+    - name: verify search results
+      run: |
+        set -x
+        res=0
+        for term in commit config log rev-parse
+        do
+          node ./script/run-pagefind.js "$term" | tee search.results >&2
+          grep "^1. /docs/git-$term\\.html" search.results || {
+            echo "::error::Search for $term failed to show the manual page first" >&2
+            res=1
+          }
+        done
+        exit $res
 
-    - name: rubocop
-      run: bundle exec rubocop -P
+    - name: check for broken links
+      id: lychee
+      uses: lycheeverse/lychee-action@d4128702eae98bbc5ecf74df0165a8156c80920a # until an official version is out that includes https://github.com/lycheeverse/lychee/pull/1422
+      with:
+        lycheeVersion: nightly # until an official version includes https://github.com/lycheeverse/lychee/pull/1422
+        args: >-
+          --offline
+          --fallback-extensions html
+          --exclude file:///path/to/repo.git/
+          --exclude file:///caminho/para/o/reposit%C3%B3rio.git/
+          --exclude file:///ruta/a/repositorio.git/
+          --exclude file:///sl%C3%B3%C3%B0/til/hirsla.git/
+          --exclude file:///Pfad/zum/Repo.git/
+          --exclude file:///chemin/du/d%C3%A9p%C3%B4t.git/
+          --exclude file:///srv/git/project.git
+          public/
+        output: lychee.md
+        jobSummary: true
 
-    - name: rspec
-      run: bundle exec rspec
+    - name: Install @playwright/test
+      run: npm install @playwright/test
+    - name: Run Playwright tests
+      env:
+        PLAYWRIGHT_TEST_URL: http://localhost:5000/
+      run: npx playwright test --project=chrome

.github/workflows/deploy.yml

@@ -0,0 +1,23 @@
+name: Deploy to GitHub Pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - gh-pages
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write # to deploy to GitHub Pages
+      id-token: write # to verify that the deployment source is legit
+      issues: write # to open tickets upon broken links
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.url }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: deploy to GitHub Pages
+        id: deploy
+        uses: ./.github/actions/deploy-to-github-pages

.github/workflows/playwright.yml

@@ -0,0 +1,33 @@
+name: Playwright Tests
+on:
+  workflow_dispatch:
+    inputs:
+      url:
+        description: 'URL to test'
+        required: true
+        default: 'https://git-scm.com'
+      assume-rails-app:
+        description: 'Whether the URL points to the original Rails app variant of the site'
+        required: false
+        default: 'false'
+jobs:
+  test:
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: lts/*
+    - name: Install @playwright/test
+      run: npm install @playwright/test
+    - name: Run Playwright tests
+      env:
+        PLAYWRIGHT_TEST_URL: ${{ github.event.inputs.url }}
+        PLAYWRIGHT_ASSUME_RAILS_APP: ${{ github.event.inputs.assume-rails-app }}
+      run: npx playwright test --project=chrome
+    - uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: playwright-report
+        path: playwright-report/