AI 지원 기능 아키텍처
GitLab v19.5요약
GitLab의 AI 지원 기능은 GitLab Duo Workflow Service를 기반으로 동작합니다. GitLab Self-Managed 인스턴스에서는 네트워크 제한이나 보안 정책 때문에 GitLab Duo Workflow Service가 GitLab 인스턴스로 HTTP 요청을 직접 보낼 수 없습니다.
GitLab의 AI 지원 기능은 GitLab Duo Workflow Service를 기반으로 동작합니다. 이 외부 서비스는 대규모 언어 모델(LLM)에 요청을 수행하고 AI 워크플로를 조율합니다. Workhorse는 GitLab Rails 애플리케이션과 GitLab Duo Workflow Service 사이의 다리 역할을 하며, 다양한 배포 형태(GitLab.com 및 GitLab Self-Managed)를 지원하면서 안전하고 효율적인 통신을 가능하게 합니다.
주요 구성 요소#
- GitLab Rails: 인증, 권한 부여, API 요청을 처리하는 GitLab 본체 애플리케이션입니다.
- Workhorse: WebSocket 연결을 관리하고 클라이언트와 GitLab Duo Workflow Service 사이의 요청을 프록시하는 스마트 리버스 프록시입니다. 백그라운드 job의 통합 핸들러처럼 액션을 실행할 수 없는 호출자를 위해 Workhorse가 플로를 직접 실행하기도 합니다.
- GitLab Duo Workflow Service: LLM에 요청을 수행하고 AI 워크플로를 조율하는 외부 서비스입니다.
- MCP 서버: AI 에이전트에 도구와 정보를 제공하는 Model Context Protocol 서버입니다(예: GitLab MCP 서버 및 외부 MCP 서버).
아키텍처 다이어그램#
고수준 아키텍처#
소스 코드 보기
graph TB
Client["Client<br/>(Web Browser)"]
Workhorse["Workhorse<br/>(Reverse Proxy)"]
Rails["GitLab Rails<br/>(Application)"]
DWS["GitLab Duo Workflow Service<br/>(AI Flows Orchestration)"]
MCP["MCP Servers<br/>(Tools & Context)"]
Client -->|WebSocket| Workhorse
Workhorse -->|HTTP| Rails
Workhorse -->|gRPC| DWS
DWS -->|gRPC| Workhorse
Workhorse -->|HTTP| MCP
Rails -->|Configuration| Workhorse
style Workhorse fill:#f9f,stroke:#333,stroke-width:2px
style DWS fill:#bbf,stroke:#333,stroke-width:2px
style MCP fill:#bfb,stroke:#333,stroke-width:2px</code></pre></details></div>
AI 상호작용 요청 흐름#
GitLab Self-Managed 인스턴스에서는 네트워크 제한이나 보안 정책 때문에 GitLab Duo Workflow Service가 GitLab 인스턴스로 HTTP 요청을 직접 보낼 수 없습니다. 대신 Workhorse가 RunHTTPRequest 액션을 가로채 GitLab Duo Workflow Service를 대신해 실행합니다. GitLab.com에서도 일관성을 위해, 그리고 GitLab Duo Workflow Service의 직접 요청을 허용하지 않는 IP 제한을 적용한 고객을 지원하기 위해 같은 방식을 사용합니다.
Mermaid 다이어그램 (27줄)소스 코드 보기
sequenceDiagram
participant User as User<br/>(Browser)
participant WH as Workhorse
participant Rails as GitLab Rails
participant DWS as Duo Workflow<br/>Service
participant MCP as MCP Server
User->>WH: 1. Establish WebSocket connection
WH->>Rails: 2. Pre-authorize request (/ws endpoint)
Rails->>WH: 3. Return DWS config & MCP servers
WH->>DWS: 4. Establish gRPC stream (ExecuteWorkflow)
User->>WH: 5. Send user input
WH->>DWS: 6. Forward ClientEvent
DWS->>WH: 7. Send Action (e.g., RunHTTPRequest)
WH->>Rails: 8. Execute action (API call)
Rails->>WH: 9. Return response
WH->>DWS: 10. Send ActionResponse
DWS->>WH: 11. Send Action (e.g., RunMCPTool)
WH->>MCP: 12. Call MCP tool
MCP->>WH: 13. Return tool result
WH->>DWS: 14. Send ActionResponse
DWS->>WH: 15. Send final response
WH->>User: 16. Forward response via WebSocket</code></pre></details></div>
서버 측 실행#
일부 호출자는 플로 실행을 대신 받아야 하며 액션을 전혀 실행할 수 없습니다. Slack 통합에서 들어와 백그라운드 job에서 처리되는 채팅 턴에는 파일 시스템도, 셸도, Action에 응답할 방법도 없습니다. 이러한 호출자를 위해 Workhorse가 플로를 직접 시작하고, 플로의 체크포인트를 개행으로 구분된 JSON 형태로 단일 HTTP 응답을 통해 스트리밍합니다.
Mermaid 다이어그램 (25줄)소스 코드 보기
sequenceDiagram
accTitle: Server-side flow execution
accDescr: Workhorse starts a flow for a server-side caller, streams checkpoints back as newline-delimited JSON, and answers on the caller's behalf the actions the caller cannot execute.
participant Caller as Server-side caller<br/>(Integration handler)
participant WH as Workhorse
participant Rails as GitLab Rails
participant DWS as Duo Workflow<br/>Service
Caller->>WH: 1. POST StartWorkflowRequest
WH->>Rails: 2. Pre-authorize request (/execute endpoint)
Rails->>WH: 3. Return workflow ID, DWS config & MCP servers
WH->>DWS: 4. Establish gRPC stream (ExecuteWorkflow)
WH->>DWS: 5. Send StartWorkflowRequest
DWS->>WH: 6. Send Action (NewCheckpoint)
WH->>Caller: 7. Stream checkpoint as ndjson line
DWS->>WH: 8. Send Action (RunCommand)
WH->>DWS: 9. Send ActionResponse carrying an error
DWS->>WH: 10. Send Action (NewCheckpoint)
WH->>Caller: 11. Stream checkpoint as ndjson line
DWS->>WH: 12. Close gRPC stream
WH->>Caller: 13. End response</code></pre></details></div>
호출자는 액션에 응답하지 않습니다. GitLab Duo Workflow Service는 자신이 보낸 모든 액션에 대한 응답을 기다리며, 응답이 없는 액션은 서비스가 시간 초과될 때까지 플로를 멈추게 하므로 Workhorse가 호출자를 대신해 응답합니다. 호출자가 실행할 수 없는 액션에는 오류를 담은 ActionResponse가 전달됩니다. RunHTTPRequest 나 MCP 도구 호출처럼 Workhorse가 모든 전송 방식에서 처리하는 액션은 평소와 같이 실행됩니다. 호출자에게는 NewCheckpoint 액션만 전달되며, 이것만으로도 플로의 진행 상황을 따라가기에 충분합니다.
응답 헤더는 첫 줄을 기록하는 시점에 확정되므로, 첫 액션 이전에 발생한 실패는 HTTP 상태 코드로 보고됩니다. 워크플로가 이미 다른 곳에서 실행 중이면 409, 사용량 할당량이 소진되었으면 403, 시작 요청이 올바르지 않으면 400, gRPC 스트림을 열 수 없으면 502 입니다. 첫 줄 이후에 발생한 실패는 응답을 끝내기만 하므로, 호출자는 워크플로 상태를 확인해 정상 완료와 중단을 구분합니다.
제한된 네트워크 환경#
IP 제한이 있거나 폐쇄된 네트워크 환경에서는 Workhorse가 모든 외부 요청의 프록시 역할을 합니다.
- 아웃바운드 연결: Workhorse가 GitLab Duo Workflow Service로 gRPC 연결을 수립합니다.
- 인바운드 요청: GitLab Duo Workflow Service는 수립된 gRPC 스트림을 통해 요청을 되돌려 보냅니다.
- API 호출: Workhorse가 GitLab Duo Workflow Service를 대신해 GitLab 인스턴스에 API 호출을 실행합니다.
오류 처리 및 복원력#
정상 종료#
서버 종료 과정에서 Workhorse는 다음을 수행합니다.
- 활성 워크플로 러너 전체의 정상 종료를 시작합니다.
- GitLab Duo Workflow Service에
StopWorkflow 요청을 보냅니다.
- 제한 시간 안에 워크플로가 완료되기를 기다립니다.
- 제한 시간 안에 연결이 닫히지 않으면 강제로 종료합니다.
보안 고려 사항#
인증 및 권한 부여#
- 사전 인가: 모든 요청은 WebSocket 연결을 수립하기 전에 GitLab Rails에서 사전 인가를 거칩니다.
- OAuth 토큰: 원본 요청의 OAuth 토큰으로 API 호출을 인증합니다.
- 토큰 전파: 토큰은 Workhorse를 거쳐 GitLab Duo Workflow Service로 안전하게 전달됩니다.
관련 리소스#
참조#
- MR !193149: Workhorse as a proxy to GitLab Duo Workflow
- MR !196891: Handle runHttpRequest action from GitLab Duo Workflow
- MR !206445: Implement MCP client that uses GitLab MCP server
- MR !212684: Workhorse shutdown DWS conns during blackout
- MR !254410: Introduce clientTransport interface in duoworkflow runner
- MR !254443: Add Duo Workflow server-side execution auth endpoint