From bb1458080af00b6d109f81acf247e0336aeff311 Mon Sep 17 00:00:00 2001
From: William Woodruff <william@astral.sh>
Date: Mon, 13 Apr 2026 14:29:56 -0400
Subject: [PATCH] Fix linkcheck timeouts

Signed-off-by: William Woodruff <william@astral.sh>
---
 .github/workflows/test.yml |  4 ++++
 source/conf.py             | 10 +++++++++-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 1f67bad8e..8d230d6ba 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -24,6 +24,7 @@ jobs:
     name: ${{ matrix.noxenv }}
     if: ${{ github.repository_owner == 'pypa' || github.event_name != 'schedule' }}
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     strategy:
       matrix:
         noxenv:
@@ -47,6 +48,9 @@ jobs:
           python -m pip install --upgrade nox virtualenv
 
       - name: Nox ${{ matrix.noxenv }}
+        env:
+          # Authenticate github.com requests during linkcheck to avoid rate limits.
+          GITHUB_TOKEN: ${{ github.token }}
         run: |
           python -m nox -s ${{ matrix.noxenv }}
 
diff --git a/source/conf.py b/source/conf.py
index 37d00dd55..fb0669bb5 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -161,7 +161,8 @@
     # Ref: https://github.com/pypa/packaging.python.org/issues/1998
     r"https://blog\.ganssle\.io/.*",
 ]
-linkcheck_retries = 5
+linkcheck_retries = 2
+linkcheck_timeout = 30
 # Ignore anchors for common targets when we know they likely won't be found
 linkcheck_anchors_ignore_for_url = [
     # GitHub synthesises anchors in JavaScript, so Sphinx can't find them in the HTML
@@ -171,6 +172,13 @@
     # https://github.com/pypa/packaging.python.org/issues/1744
     r"https://pypi\.org/",
 ]
+# Authenticate requests to github.com (when a token is available) to avoid
+# unauthenticated rate limits that can stall linkcheck for hours on CI.
+if _gh_token := os.getenv("GITHUB_TOKEN"):
+    linkcheck_request_headers = {
+        "https://github.com/": {"Authorization": f"Bearer {_gh_token}"},
+        "https://api.github.com/": {"Authorization": f"Bearer {_gh_token}"},
+    }
 
 # -- Options for extlinks ----------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html#configuration