diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx
index b460e51b..b5414e7e 100644
--- a/docs/toolhive/guides-registry/configuration.mdx
+++ b/docs/toolhive/guides-registry/configuration.mdx
@@ -89,6 +89,15 @@ options. You can configure multiple registries in a single server instance.
 
 Clone and sync from Git repositories. Ideal for version-controlled registries.
 
+:::note
+
+When the registry server clones a Git repository, it stores the local copy in
+`/data`. Mounting a persistent volume there is optional but recommended for
+production deployments. Without it, the registry server re-clones the repository
+on every container restart, adding startup latency and increasing network usage.
+
+:::
+
 ```yaml title="config-git.yaml"
 registries:
   - name: toolhive
@@ -109,9 +118,7 @@ registries:
 - `commit` (optional): Commit SHA to pin to a specific commit
 - `path` (optional): Path to the registry file within the repository (defaults
   to `registry.json`)
-- `auth.username` (optional): Username for Git authentication
-- `auth.passwordFile` (optional): Path to a file containing the Git password or
-  token
+- `auth` (optional): Authentication for private repositories (see below)
 
 :::tip
 
@@ -121,6 +128,86 @@ precedence over `branch`.
 
 :::
 
+#### Private repository authentication
+
+To access private Git repositories, configure the `auth` section with your
+credentials:
+
+```yaml title="config-git-private.yaml"
+registries:
+  - name: private-registry
+    format: toolhive
+    git:
+      repository: https://github.com/my-org/private-registry.git
+      branch: main
+      path: registry.json
+      # highlight-start
+      auth:
+        username: oauth2
+        passwordFile: /secrets/git/token
+      # highlight-end
+    syncPolicy:
+      interval: '30m'
+```
+
+**Authentication options:**
+
+- `auth.username` (required with `passwordFile`): Git username for HTTP Basic
+  authentication. For GitHub and GitLab, use `oauth2` as the username when
+  authenticating with a personal access token (PAT).
+- `auth.passwordFile` (required with `username`): Absolute path to a file
+  containing the Git password or token. Whitespace is trimmed from the file
+  content.
+
+:::warning
+
+Both `username` and `passwordFile` must be specified together. If only one is
+provided, the configuration will fail validation.
+
+:::
+
+**Using with Kubernetes secrets:**
+
+In Kubernetes deployments, mount a secret containing your Git token and
+reference the mount path:
+
+```yaml title="registry-deployment.yaml"
+apiVersion: v1
+kind: Secret
+metadata:
+  name: git-credentials
+type: Opaque
+stringData:
+  token: <YOUR_GITHUB_TOKEN>
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: registry-server
+spec:
+  # Other deployment fields omitted, refer to the Deployment in Kubernetes guide
+  template:
+    spec:
+      containers:
+        - name: registry
+          volumeMounts:
+            - name: git-credentials
+              mountPath: /secrets/git
+              readOnly: true
+            - name: data
+              mountPath: /data
+              readOnly: false
+      volumes:
+        - name: git-credentials
+          secret:
+            secretName: git-credentials
+            items:
+              - key: token
+                path: token
+        - name: data
+          emptyDir: {}
+```
+
 ### API endpoint source
 
 Sync from upstream MCP Registry APIs. Supports federation and aggregation