ContextQMD
Back to Gitlabhq

Configure GitLab Duo

doc/administration/gitlab_duo/configure/_index.md

18.11.28.9 KB
Original Source

{{< details >}}

  • Offering: GitLab Self-Managed

{{< /details >}}

GitLab Duo is an AI-native assistant that helps you across the software development lifecycle.

You can configure GitLab Duo to use:

  • Cloud-based AI Gateway (default): GitLab-hosted AI Gateway with vendor language models.
  • Self-hosted models: Your own AI Gateway and language models for full control over your data and security.
  • Hybrid configuration: Self-hosted models for some features and cloud-based models for others.

Prerequisites

Turn on composite identity (removed)

<!--- start_remove The following content will be removed on remove_date: '2026-04-11' -->

This feature was removed in GitLab 18.9.

<!--- end_remove -->

Allow outbound connections from the GitLab instance to GitLab Duo

  • GitLab application nodes must connect to the GitLab Duo Workflow at https://duo-workflow-svc.runway.gitlab.net with HTTP/2. The application and service communicate with gRPC.
  • For GitLab Duo Agent Platform features your firewalls and HTTP/S proxy servers must allow outbound connections to duo-workflow-svc.runway.gitlab.net on port 443 with https:// and support for HTTP/2 traffic.

Allow inbound connections from clients to the GitLab instance

Your GitLab instance must allow inbound connections from IDE clients.

  1. Allow WebSocket Protocol upgrade requests with headers:
    • Connection: upgrade
    • Upgrade: websocket
    • HTTP/2 protocol support
    • Standard WebSocket security headers: Sec-WebSocket-*
  2. Enable wss:// (WebSocket Secure) protocol support.
  3. Add specific endpoints to allow:
    • Primary endpoint: wss://<customer-instance>/-/cable
    • Ensure HTTP/2 protocol is not downgraded to HTTP/1.1.
    • Port: 443 (HTTPS/WSS)

If you have issues:

  • Check for restrictions on WebSocket traffic to wss://gitlab.example.com/-/cable and other .com domains.
  • If you use reverse proxies like Apache, you might see GitLab Duo Chat connection issues in your logs, like WebSocket connection to .... failures.

To resolve this issue, edit your proxy settings:

apache
# Enable WebSocket reverse Proxy
# Needs proxy_wstunnel enabled
  RewriteCond %{HTTP:Upgrade} websocket [NC]
  RewriteCond %{HTTP:Connection} upgrade [NC]
  RewriteRule ^/?(.*) "ws://127.0.0.1:8181/$1" [P,L]

Allow connections from the runner

For GitLab Duo Agent Platform features that make use of runners, like flows, the runner must be able to connect to the GitLab instance.

The same inbound connections from clients to the GitLab instance must be allowed as outbound connections from the runner to the GitLab instance.

In addition, runners must be able to connect to:

DestinationPortPurpose
registry.npmjs.org443Download the Duo CLI package at runtime
registry.gitlab.com443Download the default Docker image (unless using a custom image)

If your organization cannot allow access to the public npm registry, you can use a custom Docker image with the required dependencies already installed.

Share usage data with GitLab

{{< history >}}

{{< /history >}}

To help improve service quality, you can share usage data about GitLab Duo Agent Platform features with GitLab.

When you turn on data collection, GitLab logs information about GitLab Duo feature usage. This data is used exclusively for service improvement and debugging, and not for training AI models.

For more information about what data is collected, see Agent Platform usage data.

Prerequisites:

  • Have GitLab 18.9.1 or later

To turn on extended logging:

  1. In the upper-right corner, select Admin.
  2. In the left sidebar, select GitLab Duo.
  3. Select Change configuration.
  4. Select the Collect usage data checkbox.
  5. Select Save changes.

Data usage with self-hosted models

If you use a self-hosted AI gateway and self-hosted models, detailed logs are stored on your infrastructure and are not shared with GitLab. To share data with GitLab, you must configure your self-hosted AI Gateway to send traces to an external observability service.

You can use Service Ping to send usage data to GitLab. This data is different from the telemetry data.

Run a health check for GitLab Duo

{{< details >}}

  • Status: Beta

{{< /details >}}

{{< history >}}

{{< /history >}}

You can determine if your instance meets the requirements to use GitLab Duo. When the health check completes, it displays a pass or fail result and the types of issues. If the health check fails any of the tests, users might not be able to use GitLab Duo features in your instance.

This is a beta feature.

Prerequisites:

  • You must be an administrator.

To run a health check:

  1. In the upper-right corner, select Admin.
  2. In the left sidebar, select GitLab Duo.
  3. In the upper-right corner, select Run health check.
  4. Optional. In GitLab 17.5 and later, after the health check is complete, you can select Download report to save a detailed report of the health check results.

These tests are performed:

TestDescription
AI GatewayGitLab Duo Self-Hosted models only. Tests whether the AI Gateway URL is configured as an environment variable. This connectivity is required for self-hosted model deployments that use the AI Gateway.
NetworkTests whether your instance can connect to customers.gitlab.com and cloud.gitlab.com.

If your instance cannot connect to either destination, ensure that your firewall or proxy server settings allow connection. | | Synchronization | Tests whether your subscription:

  • Has been activated with an activation code and can be synchronized with customers.gitlab.com.
  • Has correct access credentials.
  • Has been synchronized recently. If it hasn't or the access credentials are missing or expired, you can manually synchronize your subscription data. | | Code Suggestions | GitLab Duo Self-Hosted models only. Tests whether Code Suggestions is available:
  • Your license includes access to Code Suggestions.
  • You have the necessary permissions to use the feature. | | GitLab Duo Agent Platform | Tests whether the backend service is operational and accessible. This service is required for agentic features like the Agent Platform and GitLab Duo Agentic Chat. | | System exchange | Tests whether Code Suggestions can be used in your instance. If the system exchange assessment fails, users might not be able to use GitLab Duo features. |

For GitLab instances earlier than version 17.10, if you are encountering any issues with the health check, see the troubleshooting page.

Other hosting options

By default, GitLab Duo uses supported AI vendor language models and sends data through a cloud-based AI Gateway that's hosted by GitLab.

If you want to host your own language models or AI Gateway: