feat: route-git-token — runner-level private-git routing

The unsealed sibling of cargo-fetch's git-token input, for jobs that run plain cargo build or git clone on the runner.
Exports the url.insteadOf rewrite as GIT_CONFIG_* environment entries — they die with the job, so nothing lands in a gitconfig file on self-hosted runners — and sets CARGO_NET_GIT_FETCH_WITH_CLI so cargo's fetches honor it.
Invocations append behind each other.

The defaults speak GitHub, but any authenticated https git host works: host takes an optional port, username carries the host's convention (oauth2 for GitLab, x-token-auth for Bitbucket), and path scopes the rewrite to a namespace, nested groups included.
Host, username and path are each validated against their charset before they can reach a gitconfig key; minting stays with the caller.

Selftest covers the GitHub defaults, a self-hosted GitLab group with port and username, the append behavior, and the invalid-path and invalid-host refusals.
Documented in the README action list and docs/private-git-dependencies.md.

Author: gronke

.github/actions/route-git-token/action.yml

@@ -0,0 +1,52 @@
+name: Route git token
+description: >-
+  Route git fetches on the RUNNER through a short-lived token: an url.insteadOf rewrite that
+  authenticates https fetches with the token, plus CARGO_NET_GIT_FETCH_WITH_CLI=1 so cargo's
+  fetches go through the git CLI, which honors the rewrite (cargo's libgit2 path does not). This is
+  the unsealed sibling of `cargo-fetch`'s git-token input — for jobs that run plain `cargo build`
+  or `git clone` on the runner instead of inside the sealed container. The rewrite lives in
+  GIT_CONFIG_* environment entries exported via $GITHUB_ENV, NOT in a gitconfig file: it dies with
+  the job, which matters on self-hosted runners, and it appends to (never clobbers) entries a
+  previous invocation exported. The defaults speak GitHub, but any authenticated https git host
+  works — the username carries the host's convention (GitHub App tokens: x-access-token; GitLab
+  OAuth: oauth2; Bitbucket: x-token-auth; Gitea accepts the token under any username). Minting is
+  the caller's business (e.g. actions/create-github-app-token, whose post step revokes the token);
+  scope the token there — the rewrite is a transport detail, the token is the security boundary.
+
+inputs:
+  token:
+    description: >-
+      Token the fetches authenticate with. Pass a secret carrying read access on the repositories
+      the job needs; the action masks it in logs either way.
+    required: true
+  host:
+    description: >-
+      Git host to route, optionally with a port (my.gitlab.example:8443). Default github.com.
+    required: false
+    default: "github.com"
+  username:
+    description: >-
+      Userinfo name the token is presented under — the host's convention, not a real user.
+      Default x-access-token (GitHub App installation tokens; GitHub PATs accept it too).
+    required: false
+    default: "x-access-token"
+  path:
+    description: >-
+      Restrict the rewrite to a namespace under the host (an owner, or a nested group like
+      my-group/sub-group). Empty routes every fetch on the host, matching `cargo-fetch`'s
+      in-container behavior. Restricting is about predictability, not security — a rewrite for a
+      repository the token cannot read fails exactly like no rewrite at all.
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - name: Export the rewrite
+      shell: bash
+      env:
+        ROUTE_TOKEN: ${{ inputs.token }}
+        ROUTE_HOST: ${{ inputs.host }}
+        ROUTE_USERNAME: ${{ inputs.username }}
+        ROUTE_PATH: ${{ inputs.path }}
+      run: bash "$GITHUB_ACTION_PATH/route.sh"

.github/actions/route-git-token/route.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Export an url.insteadOf rewrite as GIT_CONFIG_* environment entries via
+# $GITHUB_ENV, appending after any entries an earlier invocation exported.
+#   ROUTE_TOKEN     the token (required; masked before anything else)
+#   ROUTE_HOST      git host, optionally with a port (default github.com)
+#   ROUTE_USERNAME  userinfo name the token is presented under
+#   ROUTE_PATH      optional namespace under the host to scope the rewrite to
+set -euo pipefail
+
+[ -n "${ROUTE_TOKEN:-}" ] || { echo "::error::token input is empty"; exit 1; }
+printf '::add-mask::%s\n' "$ROUTE_TOKEN"
+
+# Every validated piece ends up inside a gitconfig KEY; these gates keep
+# injection structurally impossible.
+HOST="${ROUTE_HOST:-github.com}"
+if ! [[ "$HOST" =~ ^[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?(:[0-9]{1,5})?$ ]]; then
+  echo "::error::host '${HOST}' is not a valid host[:port]"
+  exit 1
+fi
+
+USERNAME="${ROUTE_USERNAME:-x-access-token}"
+if ! [[ "$USERNAME" =~ ^[A-Za-z0-9._-]+$ ]]; then
+  echo "::error::username '${USERNAME}' is not a valid userinfo name"
+  exit 1
+fi
+
+PREFIX="https://${HOST}/"
+if [ -n "${ROUTE_PATH:-}" ]; then
+  # One or more /-separated segments, each of the forge login/group charset
+  # (GitLab namespaces nest, so a single segment would be too narrow).
+  if ! [[ "$ROUTE_PATH" =~ ^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?(/[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?)*$ ]]; then
+    echo "::error::path '${ROUTE_PATH}' is not a valid namespace path"
+    exit 1
+  fi
+  PREFIX="https://${HOST}/${ROUTE_PATH}/"
+fi
+
+# Append behind existing entries: GIT_CONFIG_COUNT is the authoritative
+# cursor, whether set by a previous invocation or by the workflow itself.
+N="${GIT_CONFIG_COUNT:-0}"
+{
+  echo "GIT_CONFIG_COUNT=$((N + 1))"
+  echo "GIT_CONFIG_KEY_${N}=url.https://${USERNAME}:${ROUTE_TOKEN}@${PREFIX#https://}.insteadOf"
+  echo "GIT_CONFIG_VALUE_${N}=${PREFIX}"
+  # cargo's libgit2 path ignores git config rewrites; the CLI honors them.
+  echo "CARGO_NET_GIT_FETCH_WITH_CLI=true"
+} >> "$GITHUB_ENV"
+
+echo "Routing ${PREFIX} fetches through the provided token (entry ${N})."

.github/workflows/selftest.yml

@@ -1474,3 +1474,63 @@ jobs:
             retry_transient always' >/dev/null 2>&1 || status=$?
           [ "$status" = "2" ] || { echo "::error::a non-numeric RETRY_ATTEMPTS did not fail fast ($status)"; exit 1; }
           echo "✓ registry timeouts retry; build errors fail once keeping their status; the contract enforces itself"
+
+  # route-git-token: the exported GIT_CONFIG_* entries resolve as git
+  # config in later steps, a second invocation appends behind the first
+  # instead of clobbering it, a non-GitHub host carries its own username
+  # convention, and host/path values that could not name a forge namespace
+  # are refused before anything reaches the environment.
+  selftest-route-git-token:
+    name: exercise the route-git-token action
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: route a github.com namespace (defaults)
+        uses: ./.github/actions/route-git-token
+        with:
+          token: not-a-real-token
+          path: octo-test
+
+      - name: route a self-hosted GitLab group, appending
+        uses: ./.github/actions/route-git-token
+        with:
+          token: second-fake-token
+          host: gitlab.example.com:8443
+          username: oauth2
+          path: my-group/sub-group
+
+      - name: the rewrites resolve and cargo is switched to the git CLI
+        shell: bash
+        run: |
+          set -euo pipefail
+          [ "$GIT_CONFIG_COUNT" = "2" ] || { echo "::error::expected 2 entries, got ${GIT_CONFIG_COUNT:-none}"; exit 1; }
+          [ "$CARGO_NET_GIT_FETCH_WITH_CLI" = "true" ] || { echo "::error::cargo git-CLI switch missing"; exit 1; }
+          got="$(git config --get 'url.https://x-access-token:not-a-real-token@github.com/octo-test/.insteadOf')"
+          [ "$got" = "https://github.com/octo-test/" ] || { echo "::error::github rewrite did not resolve (got '$got')"; exit 1; }
+          got="$(git config --get 'url.https://oauth2:second-fake-token@gitlab.example.com:8443/my-group/sub-group/.insteadOf')"
+          [ "$got" = "https://gitlab.example.com:8443/my-group/sub-group/" ] || { echo "::error::gitlab rewrite did not resolve (got '$got')"; exit 1; }
+
+      - name: an invalid path is refused
+        id: bad-path
+        continue-on-error: true
+        uses: ./.github/actions/route-git-token
+        with:
+          token: t
+          path: "evil/../traversal"
+
+      - name: an invalid host is refused
+        id: bad-host
+        continue-on-error: true
+        uses: ./.github/actions/route-git-token
+        with:
+          token: t
+          host: "github.com/../evil"
+
+      - name: the refusals actually happened
+        shell: bash
+        run: |
+          [ "${{ steps.bad-path.outcome }}" = "failure" ] \
+            || { echo "::error::invalid path was accepted"; exit 1; }
+          [ "${{ steps.bad-host.outcome }}" = "failure" ] \
+            || { echo "::error::invalid host was accepted"; exit 1; }

README.md

@@ -322,6 +322,20 @@ See [the action's README](.github/actions/cargo-install/README.md) for the secur
 Run a `cargo-install`'d tool from the shared cache, sealed and network-isolated by default.
 See [the action's README](.github/actions/cargo-use/README.md).
 
+### `route-git-token`
+
+Route git fetches ON THE RUNNER through a short-lived token: an `url.insteadOf` rewrite exported as `GIT_CONFIG_*` environment entries (they die with the job — nothing lands in a gitconfig file, which matters on self-hosted runners) plus `CARGO_NET_GIT_FETCH_WITH_CLI` so cargo's fetches honor it.
+The unsealed sibling of `cargo-fetch`'s `git-token` input, for jobs that run plain `cargo build` or `git clone` outside the container.
+The defaults speak GitHub, but any authenticated https git host works: `host:` and `username:` carry the host's convention (GitLab OAuth: `oauth2`; Bitbucket: `x-token-auth`), and `path:` optionally scopes the rewrite to a namespace — nested groups included.
+Invocations append, so two tokens for two hosts or namespaces coexist.
+
+```yaml
+- uses: gronke/rust-ci/.github/actions/route-git-token@main
+  with:
+    token: ${{ steps.deps-token.outputs.token }}
+    path: my-org
+```
+
 ### `publish-dry-run`
 
 A release gate split into **network-with-no-code** then **code-with-no-network**.
@@ -423,6 +437,7 @@ The token must carry `contents: read` on every private dependency repository.
 The default `GITHUB_TOKEN` only grants access to the workflow's own repository, so a cross-repository dependency needs a fine-grained PAT or a GitHub App installation token, stored as a secret.
 See [docs/private-git-dependencies.md](docs/private-git-dependencies.md) for the GitHub App setup and an in-workflow minting example.
 The sealed `lint-and-test-docker` passes run `--offline` against the cache `cargo-fetch` populated, so they need no token.
+Jobs that build on the runner instead of in the container route the same token with [`route-git-token`](#route-git-token).
 
 ## Cache-size operations
 

docs/private-git-dependencies.md

@@ -58,6 +58,23 @@ Mint the token just before `cargo-fetch` and hand the output to `git-token`:
 
 The token expires after one hour, is masked in logs by the action, and is revoked automatically in the action's `post` step, so it never lingers.
 
+### Without the sealed container
+
+A job that runs plain `cargo build` or `git clone` on the runner — no `cargo-fetch`, no seal — routes the same token with `route-git-token`:
+
+```yaml
+- name: Route private git fetches through the token
+  uses: gronke/rust-ci/.github/actions/route-git-token@main
+  with:
+    token: ${{ steps.deps-token.outputs.token }}
+    path: ${{ github.repository_owner }}   # optional; empty routes the whole host
+```
+
+The action is not GitHub-bound: `host:` (with an optional port) and `username:` route any authenticated https git host — a self-hosted GitLab takes `host: gitlab.example.com` with `username: oauth2` and a nested `path: group/sub-group`.
+Only the minting is ecosystem-specific, and that stays with the caller.
+
+It exports the `url.insteadOf` rewrite as `GIT_CONFIG_*` environment entries (they die with the job — nothing lands in a gitconfig file, which matters on self-hosted runners) and sets `CARGO_NET_GIT_FETCH_WITH_CLI` so cargo's fetches honor it. The rewrite is a transport detail: scope the TOKEN, as above — a rewrite for a repository the token cannot read fails exactly like no rewrite at all.
+
 ## Fine-grained PAT (simpler alternative)
 
 Create a fine-grained PAT with **Contents: Read** on each private dependency repository, store it as a secret, and pass it directly: