<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Label this issue](https://contributors.gitlab.com/manage-issue?action=label&projectId=278964&issueIid=598328) </details> <!--IssueSummary end--> ## Summary Customers using Geo with a unified URL setup may incorrectly configure Secondary's `gitlab_url` (gitlab-shell) and `[gitlab] url` (gitaly) to point directly to Primary Rails, assuming this is required for the unified URL to work. This misconfiguration causes SSH pushes to fail with 500 errors. ## Problem In a unified URL setup, customers understand that `external_url` should be the same across all sites. However, it's not clearly documented that: - `gitlab_url` (gitlab-shell config) must still point to **local** Rails - `[gitlab] url` (gitaly config) must still point to **local** Rails When misconfigured to point to Primary, the SSH proxy flow breaks because: 1. Primary Rails returns gitaly connection info with a unix socket path 2. GitLab Shell connects to the local socket, reaching Secondary Gitaly instead of Primary 3. Secondary Gitaly's pre-receive hook calls Primary Rails with quarantine context that only exists on Secondary 4. Primary Gitaly cannot access Secondary's quarantine objects → 500 error ## Proposed documentation update Add a note or section to the [Geo secondary proxy documentation](https://docs.gitlab.com/ee/administration/geo/secondary_proxy/) clarifying: > **Internal service configuration** > > When using a unified URL, only the `external_url` setting should be the same across all Geo sites. The internal service URLs (`gitlab_url` for gitlab-shell and `[gitlab] url` for gitaly) must still point to the local Rails instance on each site. Do not configure Secondary site services to point directly to Primary Rails. ## Related - Parent issue: #596761 - Affected docs: `doc/administration/geo/secondary_proxy/_index.md`