From 8e5e873c11739b0cd852925c27f90f3df3755526 Mon Sep 17 00:00:00 2001 From: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com> Date: Tue, 3 Feb 2026 17:02:04 +0000 Subject: [PATCH 1/6] Document private Git repository authentication for Registry Server Add documentation for configuring authentication when using private Git repositories as a registry source. Includes configuration options for username and passwordFile, along with a Kubernetes deployment example showing how to mount secrets. Closes stacklok/toolhive-registry-server#439 Co-Authored-By: Claude Opus 4.5 --- .../guides-registry/configuration.mdx | 81 ++++++++++++++++++- 1 file changed, 78 insertions(+), 3 deletions(-) diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index b460e51b..bd926390 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -109,9 +109,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 +119,83 @@ 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: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: registry-server +spec: + template: + spec: + containers: + - name: registry + volumeMounts: + - name: git-credentials + mountPath: /secrets/git + readOnly: true + volumes: + - name: git-credentials + secret: + secretName: git-credentials + items: + - key: token + path: token +``` + +Then reference `/secrets/git/token` as the `passwordFile` in your registry +configuration. + ### API endpoint source Sync from upstream MCP Registry APIs. Supports federation and aggregation From 109649614f60ab05f12e0919a63f87858791b207 Mon Sep 17 00:00:00 2001 From: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com> Date: Tue, 3 Feb 2026 17:14:00 +0000 Subject: [PATCH 2/6] adds some clarifications Signed-off-by: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com> --- docs/toolhive/guides-registry/configuration.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index bd926390..e3eac599 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -162,6 +162,13 @@ provided, the configuration will fail validation. In Kubernetes deployments, mount a secret containing your Git token and reference the mount path: +:::note + +This is not the full `Deployment` manifest and has been shortened to display the +git credentials configuration + +::: + ```yaml title="registry-deployment.yaml" apiVersion: v1 kind: Secret @@ -176,6 +183,7 @@ kind: Deployment metadata: name: registry-server spec: + ... template: spec: containers: From a96f35859c4f9d4320059234920a92bed8f620e3 Mon Sep 17 00:00:00 2001 From: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com> Date: Tue, 3 Feb 2026 17:45:23 +0000 Subject: [PATCH 3/6] adds data volumes for git clone Signed-off-by: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com> --- docs/toolhive/guides-registry/configuration.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index e3eac599..1b83d0aa 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -192,6 +192,9 @@ spec: - name: git-credentials mountPath: /secrets/git readOnly: true + - name: data + mountPath: /data + readOnly: false volumes: - name: git-credentials secret: @@ -199,6 +202,8 @@ spec: items: - key: token path: token + - name: data + emptyDir: {} ``` Then reference `/secrets/git/token` as the `passwordFile` in your registry From e427c1e45168ecd780e35ba07117cbcde2d21fb7 Mon Sep 17 00:00:00 2001 From: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com> Date: Wed, 4 Feb 2026 14:13:32 +0000 Subject: [PATCH 4/6] adds note for /data directory Signed-off-by: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com> --- docs/toolhive/guides-registry/configuration.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index 1b83d0aa..175444b9 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -206,6 +206,13 @@ spec: emptyDir: {} ``` +:::note + +The `/data` mount path is used by the registry server in order to storage cloned +Git repositories. + +::: + Then reference `/secrets/git/token` as the `passwordFile` in your registry configuration. From 9f17fb96e6d58f532e823f24191989f0a647a1db Mon Sep 17 00:00:00 2001 From: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com> Date: Wed, 18 Feb 2026 17:56:29 +0000 Subject: [PATCH 5/6] Move /data directory note to Git repository source section Co-Authored-By: Claude Opus 4.6 --- docs/toolhive/guides-registry/configuration.mdx | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index 175444b9..2ff00225 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -89,6 +89,14 @@ 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 cloned data in a +`/data` directory. In containerized deployments, mount a volume at `/data` to +persist cloned repositories across restarts and avoid re-cloning on every sync. + +::: + ```yaml title="config-git.yaml" registries: - name: toolhive @@ -206,13 +214,6 @@ spec: emptyDir: {} ``` -:::note - -The `/data` mount path is used by the registry server in order to storage cloned -Git repositories. - -::: - Then reference `/secrets/git/token` as the `passwordFile` in your registry configuration. From 939589388a03cd09641e4f728a14910ed5a253a1 Mon Sep 17 00:00:00 2001 From: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com> Date: Thu, 19 Feb 2026 17:37:07 +0000 Subject: [PATCH 6/6] Address review feedback on private Git auth docs Co-Authored-By: Claude Opus 4.6 --- .../guides-registry/configuration.mdx | 21 ++++++------------- 1 file changed, 6 insertions(+), 15 deletions(-) diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index 2ff00225..b5414e7e 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -91,9 +91,10 @@ Clone and sync from Git repositories. Ideal for version-controlled registries. :::note -When the registry server clones a Git repository, it stores the cloned data in a -`/data` directory. In containerized deployments, mount a volume at `/data` to -persist cloned repositories across restarts and avoid re-cloning on every sync. +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. ::: @@ -170,13 +171,6 @@ provided, the configuration will fail validation. In Kubernetes deployments, mount a secret containing your Git token and reference the mount path: -:::note - -This is not the full `Deployment` manifest and has been shortened to display the -git credentials configuration - -::: - ```yaml title="registry-deployment.yaml" apiVersion: v1 kind: Secret @@ -184,14 +178,14 @@ metadata: name: git-credentials type: Opaque stringData: - token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + 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: @@ -214,9 +208,6 @@ spec: emptyDir: {} ``` -Then reference `/secrets/git/token` as the `passwordFile` in your registry -configuration. - ### API endpoint source Sync from upstream MCP Registry APIs. Supports federation and aggregation