docs(adr): propose Gitaly proxy in Workhorse (ADR 018)

What does this MR do and why?

This ADR proposes a generic Gitaly proxy in Workhorse for Orbit and other consumers. It uses gRPC tunneled over a WebSocket, with each connection preauthorized by Rails and Gitaly credentials never leaving GitLab. The capacity section includes production request rates, durations, and concurrency bounds.

Note

Click here to see the rendered version of the ADR.

Relates to #1252

Testing

Markdownlint and Vale at error level pass. The existing offline link check also passes. Documentation only.

Performance Analysis

Documentation only, no runtime change.

  • This merge request does not introduce any performance regression. If a performance regression is expected, explain why.
Agent context — long-form analysis, file-by-file walkthroughs, profiler output, alternatives considered

ADR 018 defines one project-scoped proxy connection per indexing job. Rails preauthorization returns the repository's Gitaly coordinates, read-only policy, stream cap, and enforced client_name; Workhorse rejects consumer-supplied metadata. Orbit authenticates with its existing Rails JWT.

The capacity model bounds active archive connections at fetch_concurrency × indexer pods: the default 10 across four GitLab.com code-indexer pods gives about 40 slots, independent of repository count. Production Gitaly data shows about 0.7 GetArchive requests per second in steady state, bursts around 200 requests per second, 2.0-second average duration, and 36-second p99 duration.

Little's law gives incremental concurrency of about 0.7 req/s × 2.0 s = 1.4, or one to two connections. Backfill concurrency cannot exceed the configured cap, about 40 connections for the current pool.

Rollout uses one gitaly_proxy flag at Rails preauthorization: off is the kill switch, namespace actors support gradual rollout, and global enablement is GA. The rails_http transport default remains configuration rather than a feature flag.

Alignment-audit follow-up: ADR 018 now records Workhorse’s 30-second hard-kill grace, admission defaults, and Rails-vouched consumer attribution.

Implementation Drafts, in dependency order: gitlab-org/gitlab!253414 (Workhorse core), gitlab-org/gitlab!253431 (Workhorse route and sessions), gitlab-org/gitlab!253417 (Rails preauthorization), !2381 (client transport), !2382 (indexer archive path).

%{all_commits}

Edited by Dmitry Gruzd

Merge request reports

Loading
Loading