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. The {branch} may also be given in the refs/heads/{branch} form.

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

Token interaction

Neither token nor mirror-token is forwarded to a host the user did not nominate. Auth is resolved per request URL:

1. if mirror-token is set AND the request origin (scheme + host + port) equals the mirror origin, use mirror-token, sent verbatim
2. else if token is set AND the target host is github.com, *.github.com, or *.githubusercontent.com, use token, sent as token <token>
3. else send no auth

One exception: when mirror is a raw.githubusercontent.com/{owner}/{repo}/{branch} URL, the manifest is fetched from the GitHub REST API (api.github.com, a different origin than the mirror). There mirror-token is preferred over token — with the token prefix the API requires — because naming a repo mirror is explicit intent to read that repo.

Cases:

Default (no inputs set)
  mirror = default raw.githubusercontent.com URL, mirror-token empty,
  token = github.token.
  → manifest REST 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 REST API call and GitHub-hosted 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.
  → requests to the mirror origin use `mirror-token`. A download_url on
    a different origin — including http:// on the same host — does not
    receive it.

Custom GitHub repo mirror with both tokens set
  → manifest REST API call uses `mirror-token` (prefixed). Downloads to
    the mirror origin use `mirror-token`; downloads GitHub serves from
    another GitHub host use `token`.

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.

[v-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 🙏

[v-priyagupta108]

Hi @luhenry,
Just a gentle reminder about the rebase and review feedback above when you have a chance. Please let us know if anything needs clarification. Thanks!

[luhenry]

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.

How should I handle that? Are you happy to point to a "external" mirror (can be hosted on github as well)? But then your testing would take a dependency on this external mirror.

[v-priya-kinthali]

Hello @luhenry👋, Thanks for the quick turnaround. A few more things worth a look:

1. The PyPy/GraalPy warning fires on every run. warnIfMirrorUnsupported() returns early on !core.getInput('mirror'), but action.yml gives mirror a default, so getInput always returns the default URL and the guard never trips. Every pypy-*/graalpy-* run now warns about an input the user never set.

2. setup-versions-via-mirror-input doesn't reach the mirror. 3.12 is preinstalled on all three images, so tc.find() short-circuits and the manifest is never fetched. The job passes without contacting the mirror it's meant to exercise, and would stay green even if the mirror code path regressed. check-latest: true (or an uncached patch like 3.11.7) would force the manifest fetch and make the job meaningful.

3. The slash-branch warning misfires on refs/heads/ URLs. REPO_COORDS_RE allows exactly three path segments, so https://raw.githubusercontent.com/actions/python-versions/refs/heads/main fails to match and falls into the "branch name contains a slash" branch, except the branch is main. The user gets told to remove a slash that isn't there, with no clear way to act on it.

4. That warning is also wrong about the consequence. It says the manifest is fetched by direct URL without the authenticated rate limit, and the docs caveat calls it "an anonymous direct GET with the 60/hr unauthenticated rate limit", but getManifestFromURL() calls authForUrl(), and raw.githubusercontent.com matches isGitHubHost(), so token is still sent. The new test sends token as a prefixed header for a GitHub-hosted raw manifest asserts exactly that, for this same URL shape. (Separately, raw.githubusercontent.com isn't the REST API, so the 60/hr figure doesn't apply to it either way.) On a real run:

Warning: Could not parse owner/repo/branch out of mirror
"https://raw.githubusercontent.com/actions/python-versions/refs/heads/main", so the
manifest will be fetched by direct URL instead of the GitHub API. Branch names
containing '/' are not supported; use a branch without a slash to get the
authenticated API rate limit.
Resolved as '3.12.10'
Successfully set up CPython (3.12.10)

Since that's the URL the new job uses, fixing (2) will surface this on every run.

5. getMirrorHost() swallows an invalid mirror. It catches the getMirror() throw and returns undefined, so authForUrl() quietly skips the mirror branch, while getManifestUrl() throws on the same input. The two disagree on whether a bad mirror is fatal.

6. Scheme-mismatch on the mirror host. getMirrorHost() returns URL.host, which carries the port but not the scheme, so a manifest served from https://mirror.example that lists a download_url at http://mirror.example/... still matches and mirror-token goes out in the clear.

Also, the PR description's precedence list ("if mirror-token is set, use mirror-token") doesn't match authForUrl(), which only uses mirror-token when the target host equals the mirror host. Worth updating to the host-keyed behaviour the code implements.

[v-priya-kinthali]

Hello @luhenry 👋 Just a gentle reminder. Whenever you have a moment, could you please address the review points above so we can take another look? Thanks!

[luhenry]

@v-priya-kinthali I updated the PR, thanks for your review! :)