feat: Add mirror and mirror-token inputs for custom Python distribution sources

[luhenry]

Description:

Users who need custom CPython builds (internal mirrors, GHES-hosted forks, special build configurations, compliance builds, air-gapped runners) could not previously point setup-python at anything other than actions/python-versions.

Adds two new inputs:

• mirror: base URL hosting versions-manifest.json and the Python distributions it references. Defaults to the existing https://raw.githubusercontent.com/actions/python-versions/main.
• mirror-token: optional token used to authenticate requests to the mirror.

If mirror is a https://raw.githubusercontent.com/{owner}/{repo}/{branch} URL, the manifest is fetched via the GitHub REST API (authenticated rate limit applies); otherwise the action falls back to a direct GET of {mirror}/versions-manifest.json.

This approach is largely inspired from how it's done in actions/setup-node

Token interaction

token is never forwarded to arbitrary hosts. Auth resolution is per-URL:

1. if mirror-token is set, use mirror-token
2. else if token is set AND the target host is github.com, *.github.com, or *.githubusercontent.com, use token
3. else send no auth

Cases:

Default (no inputs set)
  mirror = default raw.githubusercontent.com URL, mirror-token empty,
  token = github.token.
  → manifest API call and tarball downloads use `token`.
  Identical to prior behavior.

Custom raw.githubusercontent.com mirror (e.g. personal fork)
  mirror-token empty, token = github.token.
  → manifest API call and tarball downloads use `token`
    (target hosts are GitHub-owned).

Custom non-GitHub mirror, no mirror-token
  mirror-token empty, token = github.token.
  → manifest fetched via direct URL (no auth attached),
    tarball downloads use no auth.
  `token` is NOT forwarded to the custom host — this is the
  leak-prevention case.

Custom non-GitHub mirror with mirror-token
  mirror-token set, token may be set.
  → manifest fetch and tarball downloads use `mirror-token`.

Custom GitHub mirror with both tokens set
  mirror-token wins. Used for both the manifest API call and
  tarball downloads.

Related issue:

Fixes #1288

Check list:

• Mark if documentation changes are required.
• Mark if tests were added or updated to cover the changes.

[luhenry]

Relates to #1289

[luhenry]

I've verified it works as expected with https://github.com/riseproject-dev/riscv-runner-sample/actions/runs/24014042747/job/70030253499

[luhenry]

@gdams 👋 would you know who would be a good person to have a loot at that? That would greatly unblock riscv64 on github more generally. Thank you very much!

[gdams]

@gdams 👋 would you know who would be a good person to have a loot at that? That would greatly unblock riscv64 on github more generally. Thank you very much!

I'll ask around internally, just to clarify is your question Python specific or more generally about the state of riscv64 native runners?

[luhenry]

Merging that PR would enable a feature which would unblock users like using actions/setup-python on riscv64 runners, regardless where they are hosted. It would also enable other use cases like allowing Microsoft or any users of GitHub to point to their own builds of Python as well of course, which applies more broadly than just the support for riscv64.

[luhenry]

Hello! Following up on that. Also, please let me know if there is no chance this will get integrated, so that I can focus on workarounds.

[priyagupta108]

Hi @luhenry,
Thanks for this PR, the mirror design is a nice addition. A few things before we merge:

Rebase first. It's conflicting, and install-python.ts on main now has fetchValidManifest() (retry + validation), RHEL filtering, and ESM imports. A couple of notes below only apply on the new base.

1. Scope mirror-token to the mirror's host, and don't prefix it. authForUrl() returns token ${mirrorToken} before host is checked, so a manifest entry pointing at objects.githubusercontent.com gets the private mirror credential. Hardcoding token is also wrong for internal mirrors, which want Bearer or Basic; setup-node passes its mirror token verbatim and lets the user own the scheme.

For downloads, decide by host: mirror host with mirror-token set sends it verbatim, GitHub host sends token ${token}, anything else no auth. Leave getManifestFromRepo() alone. It only runs for GitHub repo mirrors, where mirror-token is the user's explicit intent and the API needs the prefix anyway, and the host rule would drop it there since api.github.com never matches the mirror host.

Knock-on: the "takes precedence" lines in both input descriptions, the auth bullets in advanced-usage.md, and the case table in the PR description, plus a test for mirror-token being withheld from an incidental GitHub host.

2. Throw-as-control-flow costs 3 retries after rebase. getManifestFromRepo() throwing for non-GitHub mirrors lands inside fetchValidManifest(), and as a plain Error it won't short-circuit, so every custom-mirror run burns 3 attempts with backoff before falling back. Check resolveRepoCoords() in getManifest() and route straight to the URL fetch. Worth a test.

3. Docs and tests disagree on manifest auth. Docs say mirror-token covers "manifest fetch and tarball downloads," but getManifestFromURL() does a bare getJson() and the test asserts no auth header. Not a regression, but a private non-GitHub mirror will 401 on the manifest. Wire it through or fix the docs.

4. Slash branches silently lose auth. REPO_COORDS_RE uses ([^/]+) + $, so a fork on feature/riscv drops to an anonymous raw GET. Loosening the regex is ambiguous, so please warn on parse failure and document the limit instead.

5. getMirror() can throw from the error path. It re-validates on every call, including from find-python.ts when building the "version not found" message, so a malformed mirror masks the real cause. Memoizing restores the single-evaluation behaviour the old MANIFEST_URL const had.

6. PyPy and GraalPy ignore mirror. Neither installer reads the input, so it silently does nothing for pypy-*/graalpy-*. Worth a docs caveat or warning.

7. The E2E job doesn't exercise the new paths. setup-versions-via-mirror-input sets mirror to the default value, so it resolves to the same coordinates as a run with no mirror. A fork of actions/python-versions would at least cover non-default coordinates.

Once those are addressed, happy to take another look. Thanks!

[luhenry]

I’m OoO this week but will absolutely rebase and address feedback next week! Thank you very much 🙏