From b383f4f627893e95f27416f4e528d4a925b424a3 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/4] 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 | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index c490a77e..e1535e03 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -102,6 +102,7 @@ registries: - `tag` (optional): Tag name to pin to a specific version - `commit` (optional): Commit SHA to pin to a specific commit - `path` (required): Path to the registry file within the repository +- `auth` (optional): Authentication for private repositories (see below) :::tip @@ -111,6 +112,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 9b5a5c265422b637fd5c6b4d17d10d461b50bef4 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/4] 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 e1535e03..41dfc9cb 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -155,6 +155,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 @@ -169,6 +176,7 @@ kind: Deployment metadata: name: registry-server spec: + ... template: spec: containers: From b89fcf966229b2405a980ee67eeab5824676c04b 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/4] 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 41dfc9cb..4e8dd0a6 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -185,6 +185,9 @@ spec: - name: git-credentials mountPath: /secrets/git readOnly: true + - name: data + mountPath: /data + readOnly: false volumes: - name: git-credentials secret: @@ -192,6 +195,8 @@ spec: items: - key: token path: token + - name: data + emptyDir: {} ``` Then reference `/secrets/git/token` as the `passwordFile` in your registry From 47700d14bb5dded76b4123c9078f2a4adfa06d47 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/4] 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 4e8dd0a6..7438a479 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -199,6 +199,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.