deploy: improve support for external HTTPS

The official `git-scm.com` website is currently built by Hugo with
`--baseURL http://git-scm.com/`. This commit allows changing the URL
scheme to `https`, in order to avoid unnecessary redirects between
HTTPS and unencrypted HTTP.

Such redirects occur when one of the following URLs is requested:

* URLs in `layouts/alias.html`, e.g. in <https://git-scm.com/docs/>
* Image URLs in <https://git-scm.com/application.min.css>
* Endpoint URLs in <https://git-scm.com/sitemap.xml>

Since these URLs have the `http` scheme, the client is supposed to send
the new request unencrypted, only to be told by the server to use HTTPS
again. Modern web browsers tend to stick with HTTPS in certain cases,
so the downgrade may not always happen, but it's better to eliminate
the redirects nevertheless, for security and performance reasons.

Instead of trying to use relative URLs everywhere, this commit takes a
simpler approach by using the `https` scheme in the base URL. One way
to do this is to enable the "Enforce HTTPS" option in the GitHub Pages
settings, but it's infeasible because the `git-scm.com` domain points to
Cloudflare instead of GitHub.

Therefore, this commit introduces a GitHub Actions variable,
`EXTERNAL_HTTPS`, which can be set to true if HTTPS is provided by a
third party, so that the URL scheme can be safely overridden. This also
generalizes the special case of `git-scm.com` for any domain with a
similar setup, allowing tests to be run more reliably in a uniform way.

See-also: c22a1a5 (deploy(playwright): work around externally-enforced HTTPS, 2024-10-07)
See-also: d4f88c1 (deploy: be more careful when auto-upgrading from HTTP -> HTTPS, 2024-10-07)

Author: b9a1

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

@@ -20,6 +20,10 @@ inputs:
   cloudflare-zone:
     description: The Cloudflare zone to purge.
     required: false
+  external-https:
+    description: Whether HTTPS is set up externally, e.g. on Cloudflare instead of GitHub.
+    default: false
+    required: false
 outputs:
   url:
     description: The URL to which the site was deployed
@@ -41,6 +45,15 @@ runs:
       id: pages
       uses: actions/configure-pages@v5
 
+    - name: set base URL
+      shell: bash
+      run: |
+        base_url="${{ steps.pages.outputs.base_url }}"
+        if [ "${{ inputs.external-https }}" = true ] ; then
+          base_url="$(echo "$base_url" | sed 's/^http:/https:/')"
+        fi
+        echo "base_url=$base_url" >>"$GITHUB_ENV"
+
     - name: configure Hugo and Pagefind version
       shell: bash
       run: |
@@ -59,7 +72,7 @@ runs:
       env:
         HUGO_RELATIVEURLS: false
       shell: bash
-      run: hugo config && hugo --baseURL "${{ steps.pages.outputs.base_url }}/"
+      run: hugo config && hugo --baseURL "${{ env.base_url }}/"
 
     - name: run Pagefind ${{ env.PAGEFIND_VERSION }} to build the search index
       shell: bash
@@ -110,7 +123,6 @@ runs:
       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
@@ -120,14 +132,25 @@ runs:
           sed -n 's|^\(https\?:\/\/.*\)\(/git-scm\.com\)$|--remap '\''(\1.*) file://../$1'\''|p')" \
           >>$GITHUB_OUTPUT
 
+    - name: check for downgrades to unencrypted HTTP
+      if: startsWith(env.base_url, 'https://')
+      shell: bash
+      # The `--require-https` option of lychee could come in handy,
+      # but it also complains about `http://` links to other sites,
+      # and (more importantly) doesn't work in offline mode.
+      # A simple `grep` should work without any false positives,
+      # unless git-scm.com mentions the base URL of one of its forks,
+      # which is unlikely.
+      run: '! grep -FInr "http:${base_url#https:}" public'
+
     - name: check for broken links
       id: lychee
       uses: lycheeverse/lychee-action@v2
       with:
         args: >-
           --offline
           --fallback-extensions html
-          --base '${{ steps.pages.outputs.base_url }}'
+          --base '${{ env.base_url }}'
           --remap '${{ steps.remap.outputs.result }}'
           ${{ steps.remap.outputs.remap-dotdot }}
           --exclude file:///path/to/repo.git/
@@ -192,23 +215,21 @@ runs:
     - name: Install @playwright/test
       shell: bash
       run: npm install @playwright/test
-    - name: Edit /etc/hosts to map git-scm.com to GitHub
+    - name: Edit /etc/hosts to map the deployed domain to GitHub
       shell: bash
-      # This side-steps the Cloudflare caches
-      run: sudo sh -c 'echo "185.199.108.153 git-scm.com" >>/etc/hosts'
+      # This side-steps any caches that might be configured on the domain,
+      # and works even when the real server is not reachable from GitHub.
+      run: |
+        host="$(echo "$base_url" | sed -E 's|^https?://([^:/]+).*|\1|')"
+        sudo sh -c "echo '185.199.108.153 $host' >>/etc/hosts"
     - name: Run Playwright tests
       shell: bash
       id: playwright
       env:
-        PLAYWRIGHT_TEST_URL: ${{ steps.pages.outputs.base_url }}
-      run: |
+        PLAYWRIGHT_TEST_URL: ${{ env.base_url }}
         # avoid test failures when HTTPS is enforced half-way through
-        case "$PLAYWRIGHT_TEST_URL" in
-        https://*|http://git-scm.com) ;; # okay, leave as-is
-        http://*) PLAYWRIGHT_TEST_URL="https://${PLAYWRIGHT_TEST_URL#http://}";;
-        esac &&
-        echo "result=$PLAYWRIGHT_TEST_URL" >>$GITHUB_OUTPUT &&
-        npx playwright test --project=chrome
+        PLAYWRIGHT_EXTERNAL_HTTPS: ${{ inputs.external-https }}
+      run: npx playwright test --project=chrome
     - uses: actions/upload-artifact@v4
       if: always() && steps.playwright.outputs.result != ''
       with:

.github/workflows/deploy.yml

@@ -27,3 +27,4 @@ jobs:
         with:
           cloudflare-token: ${{ secrets.CLOUDFLARE_TOKEN }}
           cloudflare-zone: ${{ secrets.CLOUDFLARE_ZONE }}
+          external-https: ${{ vars.EXTERNAL_HTTPS }}

ARCHITECTURE.md

@@ -34,6 +34,16 @@ With this change, the site can be tested in the fork by pushing to the
 `gh-pages` branch (which will trigger the `deploy.yml` workflow) and then
 navigating to https://git-scm.<user>.github.io/.
 
+If the site will be deployed to a custom domain that supports HTTPS,
+but the "[Enforce HTTPS]" option cannot be enabled in the GitHub Pages settings
+(this can happen if the domain points to a third-party gateway),
+the [GitHub Actions variable] `EXTERNAL_HTTPS` should be set to `true`,
+so that the site can be built with a proper HTTPS base URL.
+The official `git-scm.com` domain is an example of such a setup.
+
+[Enforce HTTPS]: https://docs.github.com/en/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https#enforcing-https-for-your-github-pages-site
+[GitHub Actions variable]: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#defining-configuration-variables-for-multiple-workflows
+
 ## Non-static parts
 
 While the site consists mostly of static content, there are a couple of

playwright.config.js

@@ -34,6 +34,10 @@ module.exports = defineConfig({
 
     /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
     trace: 'on-first-retry',
+
+    /* Ignore ERR_CERT_COMMON_NAME_INVALID when tesing against GitHub's server,
+    if the real certificate is hosted by a third party (e.g. Cloudflare). */
+    ignoreHTTPSErrors: process.env.PLAYWRIGHT_EXTERNAL_HTTPS === 'true',
   },
 
   /* Configure projects for major browsers */