Context
PR #13434 (#13431) added a self-diagnosing hint for the gitlab-pat healthcheck-token 401 — that treats the symptom. The root surfaced when the deploy operator (a self-managed GitLab admin) could not provision a suitable non-personal token for NEO_MCP_HEALTHCHECK_TOKEN: the instance offers no project/group access tokens, only personal PATs (which they will not use for a service) and OAuth (which needs an app registration / app_id). So the requirement — a full GitLab user-token for an internal container self-probe — carries real, recurring operational cost.
The Problem
The in-container healthcheck (ai/scripts/diagnostics/mcpHealthcheck.mjs) probes its own MCP server on 127.0.0.1. Under NEO_AUTH_MODE=gitlab-pat that loopback probe must present a bearer that validates against /api/v4/user — so every gitlab-pat deploy must provision a GitLab user/service token just for the container to talk to itself. That is a heavyweight coupling for a loopback liveness check, and (per the deploy friction above) not always cheaply satisfiable.
#12990 explicitly considered and rejected an "AuthService loopback/health exemption (weakens the gate; the token route is the supported shape)" and chose the token route. This ticket re-opens that decision with new operational evidence — not a unilateral reversal.
Decision Record impact
challenges #12990 (its rejected loopback/health exemption + token-route choice). The shape needs cross-family convergence before implementation — strong candidate to route through /ideation-sandbox (challenges a prior decision + a security analysis is required).
Candidate Shapes (design surface — converge before implementing)
- Loopback-trusted health path — exempt requests originating from
127.0.0.1 inside the container. #12990 called this gate-weakening; re-evaluate whether 127.0.0.1-in-container is materially different from a general exemption (the public ingress still requires auth; a loopback exemption is not internet-reachable). Open security question: can a request be spoofed as loopback through the proxy chain?
- Dedicated static health secret — a separate secret the server accepts only for the
healthcheck tool, independent of the GitLab gate. Not an exemption (still a secret), not a GitLab token. #12990 framed the choice as exemption-vs-token and did not weigh this third option. Cost: a parallel auth path.
- Status quo + the #13434 hint — keep the requirement; the hint makes the failure self-diagnosing. Lowest-change, but leaves the provisioning cost.
Open Questions (V-B-A before converging)
#12990's exact "weakens the gate" rationale for loopback — re-read + engage it (do not assume it is wrong).- Whether the MCP transport can reliably distinguish a genuine container-loopback request from a proxied/forwarded one (
AuthService / transport request-origin handling).
- The security delta of a static health secret vs the GitLab gate.
Out of Scope
- Weakening the internet-facing auth gate. The public ingress stays
gitlab-pat; this is only about the internal self-probe.
Related
Release classification
post-release (deployment DX / architecture). Boardless. Likely routes to /ideation-sandbox for shape convergence.
Origin Session ID: 0b27b21a-2146-4976-945f-f1682c6a1c9c
Context
PR #13434 (#13431) added a self-diagnosing hint for the
gitlab-pathealthcheck-token 401 — that treats the symptom. The root surfaced when the deploy operator (a self-managed GitLab admin) could not provision a suitable non-personal token forNEO_MCP_HEALTHCHECK_TOKEN: the instance offers no project/group access tokens, only personal PATs (which they will not use for a service) and OAuth (which needs an app registration /app_id). So the requirement — a full GitLab user-token for an internal container self-probe — carries real, recurring operational cost.The Problem
The in-container healthcheck (
ai/scripts/diagnostics/mcpHealthcheck.mjs) probes its own MCP server on127.0.0.1. UnderNEO_AUTH_MODE=gitlab-patthat loopback probe must present a bearer that validates against/api/v4/user— so every gitlab-pat deploy must provision a GitLab user/service token just for the container to talk to itself. That is a heavyweight coupling for a loopback liveness check, and (per the deploy friction above) not always cheaply satisfiable.#12990explicitly considered and rejected an "AuthServiceloopback/health exemption (weakens the gate; the token route is the supported shape)" and chose the token route. This ticket re-opens that decision with new operational evidence — not a unilateral reversal.Decision Record impact
challenges #12990 (its rejected loopback/health exemption + token-route choice). The shape needs cross-family convergence before implementation — strong candidate to route through
/ideation-sandbox(challenges a prior decision + a security analysis is required).Candidate Shapes (design surface — converge before implementing)
127.0.0.1inside the container.#12990called this gate-weakening; re-evaluate whether127.0.0.1-in-container is materially different from a general exemption (the public ingress still requires auth; a loopback exemption is not internet-reachable). Open security question: can a request be spoofed as loopback through the proxy chain?healthchecktool, independent of the GitLab gate. Not an exemption (still a secret), not a GitLab token.#12990framed the choice as exemption-vs-token and did not weigh this third option. Cost: a parallel auth path.Open Questions (V-B-A before converging)
#12990's exact "weakens the gate" rationale for loopback — re-read + engage it (do not assume it is wrong).AuthService/ transport request-origin handling).Out of Scope
gitlab-pat; this is only about the internal self-probe.Related
Release classification
post-release (deployment DX / architecture). Boardless. Likely routes to
/ideation-sandboxfor shape convergence.Origin Session ID: 0b27b21a-2146-4976-945f-f1682c6a1c9c