From 9307b0bb0b20c549980ff81f5ef04a4a525e0ca0 Mon Sep 17 00:00:00 2001
From: Shaan Majid <shaanmajid64@gmail.com>
Date: Mon, 26 Jan 2026 10:42:10 -0600
Subject: [PATCH 1/2] feat(git): add GIT_CONFIG_PARAMETERS to env var allowlist

Allow GIT_CONFIG_PARAMETERS to pass through to git commands, enabling
users to configure credentials for private repositories via environment
variables.

Closes #1377
---
 crates/prek/src/git.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/crates/prek/src/git.rs b/crates/prek/src/git.rs
index 92ebf832..632ec098 100644
--- a/crates/prek/src/git.rs
+++ b/crates/prek/src/git.rs
@@ -53,6 +53,7 @@ pub(crate) static GIT_ENV_TO_REMOVE: LazyLock<Vec<(String, String)>> = LazyLock:
         "GIT_SSL_CAINFO",
         "GIT_SSL_NO_VERIFY",
         "GIT_CONFIG_COUNT",
+        "GIT_CONFIG_PARAMETERS",
         "GIT_HTTP_PROXY_AUTHMETHOD",
         "GIT_ALLOW_PROTOCOL",
         "GIT_ASKPASS",

From 5b9003a42308ec035c22fa7e9be93c9c9e75f2e5 Mon Sep 17 00:00:00 2001
From: Shaan Majid <shaanmajid64@gmail.com>
Date: Mon, 26 Jan 2026 12:28:09 -0600
Subject: [PATCH 2/2] docs(faq): add private repository authentication guide

Document how to authenticate with private hook repositories:
- Credential helpers (gh CLI, osxkeychain, Git Credential Manager)
- SSH URLs with agent
- URL rewriting with tokens for CI
---
 docs/faq.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/docs/faq.md b/docs/faq.md
index e0d64f95..0decdec0 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -11,6 +11,69 @@ It's a little confusing because it refers to two different kinds of hooks:
 
 Running `prek install` installs the first type: it writes the Git hook so that Git knows to call prek. Adding `--install-hooks` tells prek to do that **and** proactively create the environments and caches required by the hooks that prek manages. That way, the next time the Git hook fires, the managed hooks are ready to run without additional setup.
 
+## How do I use hooks from private repositories?
+
+prek supports cloning hooks from private repositories that require authentication.
+Since prek disables interactive terminal prompts (to prevent CI hangs), you'll need
+to configure credentials via credential helpers, environment variables, or SSH.
+
+### Option 1: Credential helpers (recommended)
+
+If you use GitHub CLI, Git Credential Manager, macOS Keychain, or similar tools,
+authentication often works automatically with no extra configuration:
+
+```shell
+# GitHub CLI users: configure git to use gh for credentials
+gh auth setup-git
+
+# Now HTTPS URLs work automatically
+prek install
+```
+
+Other credential helpers that work out of the box:
+
+- **macOS**: Keychain (`credential.helper=osxkeychain`)
+- **Windows**: Git Credential Manager (`credential.helper=manager`)
+- **Linux**: GNOME Keyring, KWallet, or `credential.helper=store`
+
+You can also use `GIT_ASKPASS` to point to a custom credential program:
+
+```shell
+export GIT_ASKPASS=/path/to/credential-script
+```
+
+### Option 2: SSH URLs
+
+Use SSH URLs in your `.pre-commit-config.yaml` instead of HTTPS:
+
+```yaml
+repos:
+  - repo: git@github.com:myorg/private-hooks.git
+    rev: v1.0.0
+    hooks:
+      - id: my-hook
+```
+
+This works automatically if you have SSH keys configured with an agent.
+
+### Option 3: URL rewriting with tokens (for CI)
+
+In CI environments without credential helpers, use environment variables to
+rewrite HTTPS URLs to include credentials:
+
+```shell
+# GitHub Actions example
+export GIT_CONFIG_COUNT=1
+export GIT_CONFIG_KEY_0="url.https://oauth2:${GITHUB_TOKEN}@github.com/.insteadOf"
+export GIT_CONFIG_VALUE_0="https://github.com/"
+
+# Or using GIT_CONFIG_PARAMETERS (more compact)
+export GIT_CONFIG_PARAMETERS="'url.https://oauth2:${GITHUB_TOKEN}@github.com/.insteadOf=https://github.com/'"
+```
+
+> **Security note:** Be careful with tokens in environment variables. Ensure your
+> CI system masks secrets in logs.
+
 ## How is `prek` pronounced?
 
 Like "wreck", but with a "p" sound instead of the "w" at the beginning.