feat: add GitHub App auth for installing private repository dependencies

intent(private-repo-app): integrate the standalone app.yml prototype into action.yml so users can pull private GitHub deps via this action's inputs

decision(input-naming): named the inputs private-repo-app-* so the purpose (private repo access via a GitHub App) is obvious from the input list
rejected(input-naming): bare app-* / owner / repositories from the prototype — too generic, no hint that they enable private repo access

decision(rewrite-mechanism): GIT_CONFIG_COUNT / GIT_CONFIG_KEY_<n> / GIT_CONFIG_VALUE_<n> env vars to layer url.*.insteadOf on top of the existing global git config
rejected(rewrite-mechanism): replacing GIT_CONFIG_GLOBAL with a temp gitconfig — drops the runner's existing global settings and hardcodes ~/.gitconfig while git also reads ~/.config/git/config

decision(rewrite-scope): emit per-repository url.*.insteadOf entries so the token only attaches to repos that are in the App installation scope
rejected(rewrite-scope): owner-wide rewrite — would catch other repos under the same owner and 404 because the installation token is scoped to specific repos

constraint(poetry-git-client): Poetry's default dulwich client ignores GIT_CONFIG_* env vars; POETRY_SYSTEM_GIT_CLIENT / POETRY_EXPERIMENTAL_SYSTEM_GIT_CLIENT are forced so the rewrite applies
constraint(cleanup-position): cleanup runs after pre-commit/prek (not right after Setup environment) so private hook repos can still be fetched while the rewrite is active
constraint(cleanup-failure-mode): cleanup uses always() so the rewrite is dropped even when poetry install / uv sync fails, preventing the token-bearing env vars from leaking into later if: always() steps

learned(actionlint-client-id): actionlint < rhysd/actionlint#652 does not yet recognize client-id on actions/create-github-app-token, hence the .github/actionlint.yaml ignore entries

Author: rcmdnk

.github/actionlint.yaml

@@ -0,0 +1,6 @@
+paths:
+  .github/workflows/**/*.{yml,yaml}:
+    ignore:
+      # Ignore the following errors for actions/create-github-app-token, until https://github.com/rhysd/actionlint/pull/652 is merged and released.
+      - 'missing input "app-id" which is required by action'
+      - 'input "client-id" is not defined in action'

README.md

@@ -26,6 +26,11 @@ coverage-push-condition | Condition to push the coverage. This will be shown in
 github_token | Token to push `coverage` branch.| `${{ github.token }}` | No
 pre-commit | Set `1` to run pre-commit. | `0` | No
 prek | Set `1` to run prek. | `0` | No
+private-repo-app-client-id | GitHub App Client ID for accessing private GitHub repositories. When set together with `private-repo-app-private-key`, `private-repo-app-owner`, and `private-repo-app-repositories`, a GitHub App installation token is generated and `url.*.insteadOf` rewrites are layered on the existing git config via `GIT_CONFIG_COUNT` so that the dependency installation step (`uv sync` / `poetry install` / `pip install`) can pull from the listed private repositories. | `''` | No
+private-repo-app-private-key | Private key of the GitHub App used to access private GitHub repositories. Used together with `private-repo-app-client-id`. | `''` | No
+private-repo-app-owner | GitHub organization or user where the GitHub App used for private repository access is installed. Used to scope the generated token and the `insteadOf` rewrites. | `''` | No
+private-repo-app-repositories | Private repositories to scope the generated token and `insteadOf` rewrites to. One repository name per line. | `''` | No
+private-repo-app-debug | Set `1` to print the resolved (token-redacted) `url.*.insteadOf` git config and run `git ls-remote` against each listed repository after the rewrite is configured. | `0` | No
 tmate | Set `1` to run [tmate](https://mxschmitt.github.io/action-tmate/). | `0` | No
 
 If you want to enable `coverage`,
@@ -154,3 +159,21 @@ jobs:
 * Set `IS_MAIN` to run `prek` and `push` only for the main combination of the matrix of `os` and `python-version`.
 
 Ref: https://github.com/rcmdnk/python-action-test/actions
+
+### Installing private GitHub dependencies via a GitHub App
+
+If your project depends on private repositories on GitHub, register a GitHub App
+installed on the relevant repositories with `Contents: read` permission, then
+pass its credentials to the action:
+
+```yaml
+- uses: rcmdnk/python-action@v1
+  with:
+    setup-type: uv
+    private-repo-app-client-id: ${{ vars.MY_APP_CLIENT_ID }}
+    private-repo-app-private-key: ${{ secrets.MY_APP_PRIVATE_KEY }}
+    private-repo-app-owner: my-org
+    private-repo-app-repositories: |
+      my-private-lib
+      another-private-lib
+```

action.yml

@@ -14,6 +14,26 @@ inputs:
     description: 'Optional shell command(s) to run right after checkout. Multiple commands can be passed as a multi-line string.'
     default: ''
     required: false
+  private-repo-app-client-id:
+    description: 'GitHub App Client ID for accessing private GitHub repositories. If set together with private-repo-app-private-key, private-repo-app-owner, and private-repo-app-repositories, a GitHub App token is generated and used to rewrite git URLs so that private GitHub repositories can be accessed during dependency installation.'
+    default: ''
+    required: false
+  private-repo-app-private-key:
+    description: 'Private key of the GitHub App used to access private GitHub repositories. Used together with private-repo-app-client-id.'
+    default: ''
+    required: false
+  private-repo-app-owner:
+    description: 'GitHub organization or user where the GitHub App used for private repository access is installed. Used to scope the generated GitHub App token.'
+    default: ''
+    required: false
+  private-repo-app-repositories:
+    description: 'Private GitHub repositories to scope the generated GitHub App token to. One repository name per line.'
+    default: ''
+    required: false
+  private-repo-app-debug:
+    description: 'Set 1 to print sanitized git config and run git ls-remote tests after configuring the GitHub App token for private repository access.'
+    default: '0'
+    required: false
   setup-python:
     description: 'Set 1 to run setup-python.'
     default: '1'
@@ -137,6 +157,79 @@ runs:
         ${{ inputs.post-checkout-command }}
         echo "::endgroup::"
       shell: bash
+    - name: Generate GitHub App token for private repository access
+      id: private-repo-app-token
+      if: ${{ inputs.private-repo-app-client-id != '' && inputs.private-repo-app-private-key != '' && inputs.private-repo-app-owner != '' && inputs.private-repo-app-repositories != '' }}
+      uses: actions/create-github-app-token@v3
+      with:
+        client-id: ${{ inputs.private-repo-app-client-id }}
+        private-key: ${{ inputs.private-repo-app-private-key }}
+        owner: ${{ inputs.private-repo-app-owner }}
+        repositories: ${{ inputs.private-repo-app-repositories }}
+        permission-contents: read
+    - name: Configure Git URL rewrite for private repositories
+      id: private-repo-app-config
+      if: ${{ inputs.private-repo-app-client-id != '' && inputs.private-repo-app-private-key != '' && inputs.private-repo-app-owner != '' && inputs.private-repo-app-repositories != '' }}
+      shell: bash
+      env:
+        APP_TOKEN: ${{ steps.private-repo-app-token.outputs.token }}
+        APP_OWNER: ${{ inputs.private-repo-app-owner }}
+        APP_REPOS: ${{ inputs.private-repo-app-repositories }}
+      run: |
+        set -euo pipefail
+
+        # Use GIT_CONFIG_COUNT/GIT_CONFIG_KEY_<n>/GIT_CONFIG_VALUE_<n> to add
+        # url.*.insteadOf entries on top of the runner's existing global git
+        # config (~/.gitconfig or $XDG_CONFIG_HOME/git/config). This avoids
+        # replacing the global config and assuming a particular path.
+        # Per-repository entries keep the token attached only to the listed
+        # repositories.
+        count=0
+        while IFS= read -r repo; do
+          repo="$(echo "$repo" | xargs)"
+          [ -z "$repo" ] && continue
+          target="https://x-access-token:${APP_TOKEN}@github.com/${APP_OWNER}/${repo}"
+          for src in \
+            "ssh://git@github.com/${APP_OWNER}/${repo}" \
+            "git@github.com:${APP_OWNER}/${repo}" \
+            "https://github.com/${APP_OWNER}/${repo}"
+          do
+            key_name="GIT_CONFIG_KEY_${count}"
+            val_name="GIT_CONFIG_VALUE_${count}"
+            key_val="url.${target}.insteadOf"
+            export "${key_name}=${key_val}"
+            export "${val_name}=${src}"
+            {
+              echo "${key_name}=${key_val}"
+              echo "${val_name}=${src}"
+            } >> "$GITHUB_ENV"
+            count=$((count + 1))
+          done
+        done <<< "$APP_REPOS"
+        export GIT_CONFIG_COUNT="${count}"
+        echo "GIT_CONFIG_COUNT=${count}" >> "$GITHUB_ENV"
+        echo "count=${count}" >> "$GITHUB_OUTPUT"
+
+        # Poetry uses dulwich by default, which does not honor GIT_CONFIG_*
+        # env vars. Force the system git client so the rewrite applies.
+        echo "POETRY_SYSTEM_GIT_CLIENT=true" >> "$GITHUB_ENV"
+        echo "POETRY_EXPERIMENTAL_SYSTEM_GIT_CLIENT=true" >> "$GITHUB_ENV"
+
+        if [ "${{ inputs.private-repo-app-debug }}" = "1" ]; then
+          echo "::group::git config (effective)"
+          git config --get-regexp '^url\..*\.insteadOf$' \
+            | sed -E 's#x-access-token:[^@]+@#x-access-token:***@#g' || true
+          echo "::endgroup::"
+
+          echo "::group::git ls-remote tests"
+          while IFS= read -r repo; do
+            repo="$(echo "$repo" | xargs)"
+            [ -z "$repo" ] && continue
+            echo "Testing ${APP_OWNER}/${repo}"
+            git ls-remote "ssh://git@github.com/${APP_OWNER}/${repo}" HEAD
+          done <<< "$APP_REPOS"
+          echo "::endgroup::"
+        fi
     - name: Install poetry
       if: ${{ inputs.setup-type == 'poetry' }}
       run: |
@@ -276,6 +369,31 @@ runs:
         git checkout .
         echo "::endgroup::"
       shell: bash
+    - name: Clear GitHub App token git environment
+      # Use always() so the rewrite is dropped even when an earlier step
+      # (e.g. poetry install / uv sync) fails, preventing the tokenized git
+      # access from leaking into later workflow steps that use if: always().
+      if: ${{ always() && inputs.private-repo-app-client-id != '' && inputs.private-repo-app-private-key != '' && inputs.private-repo-app-owner != '' && inputs.private-repo-app-repositories != '' }}
+      shell: bash
+      env:
+        COUNT: ${{ steps.private-repo-app-config.outputs.count }}
+      run: |
+        set -euo pipefail
+        # Disable the env-based git config layer so subsequent git operations
+        # see only the runner's normal global config.
+        echo "GIT_CONFIG_COUNT=0" >> "$GITHUB_ENV"
+        # Scrub the token-bearing GIT_CONFIG_KEY_<n>/VALUE_<n> values so the
+        # app token does not appear in `printenv` for later steps.
+        if [ -n "${COUNT:-}" ] && [ "${COUNT}" -gt 0 ] 2>/dev/null; then
+          i=0
+          while [ "${i}" -lt "${COUNT}" ]; do
+            echo "GIT_CONFIG_KEY_${i}=" >> "$GITHUB_ENV"
+            echo "GIT_CONFIG_VALUE_${i}=" >> "$GITHUB_ENV"
+            i=$((i + 1))
+          done
+        fi
+        echo "POETRY_SYSTEM_GIT_CLIENT=" >> "$GITHUB_ENV"
+        echo "POETRY_EXPERIMENTAL_SYSTEM_GIT_CLIENT=" >> "$GITHUB_ENV"
     - name: Pytest coverage comment
       id: coverageComment
       if: ${{ inputs.coverage == '1' }}