• Prerequisites
• Configure GitLab Duo on a self-managed instance
  • Allow outbound connections from the GitLab instance
  • Allow inbound connections from clients to the GitLab instance
• Run a health check for GitLab Duo
  • Health check tests
    • For online environments
    • For offline environments
• Turn off GitLab Duo features
  • Turn off for a group
  • Turn off for a project
  • Turn off for an instance
• Turn on beta and experimental features
  • On GitLab.com
  • On self-managed
• Troubleshooting
  • GitLab Duo features do not work on self-managed
  • GitLab Duo features not available for users

Control GitLab Duo availability

GitLab Duo features that are generally available are automatically turned on for all users that have access.

Prerequisites

• If you have self-managed GitLab:
  • You must allow connectivity.
  • Silent Mode must not be turned on.
  • You must activate your instance with an activation code.
  • GitLab Duo requires GitLab 17.2 and later for the best user experience and results. Earlier versions may continue to work, however the experience may be degraded.
• If you have GitLab Dedicated, you must have GitLab Duo Pro or Enterprise.
• For some generally available features, like Code Suggestions, you must assign seats to the users you want to have access.

GitLab Duo features that are experimental or beta are turned off by default and must be turned on.

Configure GitLab Duo on a self-managed instance

To use GitLab Duo on a self-managed instance, you must ensure both outbound and inbound connectivity exists.

For example, network firewalls can cause lag or delay. Check both your outbound and inbound settings:

Allow outbound connections from the GitLab instance

• Your firewalls and HTTP/S proxy servers must allow outbound connections to cloud.gitlab.com and customers.gitlab.com on port 443 both with https://. These hosts are protected by Cloudflare. Update your firewall settings to allow traffic to all IP addresses in the list of IP ranges Cloudflare publishes.
• To use an HTTP/S proxy, both gitLab_workhorse and gitLab_rails must have the necessary web proxy environment variables set.
• In multi-node GitLab installations, configure the HTTP/S proxy on all Rails and Sidekiq nodes.

Allow inbound connections from clients to the GitLab instance

• GitLab instances must allow inbound connections from Duo clients (IDEs, Code Editors, and GitLab Web Frontend) on port 443 with https:// and wss://.
• Both HTTP2 and the 'upgrade' header must be allowed, because GitLab Duo uses both REST and WebSockets.
• Check for restrictions on WebSocket (wss://) traffic to wss://gitlab.example.com/-/cable and other .com domains. Network policy restrictions on wss:// traffic can cause issues with some GitLab Duo Chat services. Consider policy updates to allow these services.
• If you use reverse proxies, such as Apache, you might see GitLab Duo Chat connection issues in your logs, like WebSocket connection to …. failures.

To resolve this problem, try editing your Apache proxy settings:

# 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]

Run a health check for GitLab Duo

Run a health check to test 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. On the left sidebar, at the bottom, select Admin.
2. Select GitLab Duo.
3. On 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.

Health check tests

To verify if your instance meets the requirements to use GitLab Duo, the health check performs tests for online and offline environments.

For online environments

For offline environments

Turn off GitLab Duo features

You can turn off GitLab Duo for a group, project, or instance.

When GitLab Duo is turned off for a group, project, or instance:

• GitLab Duo features that access resources, like code, issues, and vulnerabilities, are not available.
• Code Suggestions is not available.
• Duo Chat is not available.

Turn off for a group

Turn off for a project

Turn off for an instance

Turn on beta and experimental features

GitLab Duo features that are experimental and beta are turned off by default. These features are subject to the Testing Agreement.

On GitLab.com

This setting cascades to all projects that belong to the group.

On self-managed

Troubleshooting

GitLab Duo features do not work on self-managed

In addition to turning on GitLab Duo features, you can also do the following:

1. As administrator, run a health check for GitLab Duo.

   In 17.5 and later

   In GitLab 17.5 and later, you can use the UI to run health checks and download a detailed report that helps identify and troubleshoot issues.

   In 17.4

   In GitLab 17.4, you can run the health check Rake task to generate a detailed report that helps identify and troubleshoot issues.

   sudo gitlab-rails 'cloud_connector:health_check(root,report.json)'
   

   In 17.3 and earlier

   In GitLab 17.3 and earlier, you can download and run the health_check script to generate a detailed report that helps identify and troubleshoot issues.

   1. Download the health check script:

      wget https://gitlab.com/gitlab-org/gitlab/-/snippets/3734617/raw/main/health_check.rb
      

   2. Run the script using Rails Runner:

      gitlab-rails runner [full_path/to/health_check.rb] --debug --username [username] --output-file [report.txt]
      

       Usage: gitlab-rails runner full_path/to/health_check.rb
              --debug                Enable debug mode
              --output-file FILE     Write a report to FILE
              --username USERNAME    Provide a username to test seat assignments
              --skip [CHECK]         Skip specific check (options: access_data, token, license, host, features, end_to_end)
      

2. Verify that the GitLab instance can reach the required GitLab.com endpoints. You can use command-line tools such as curl to verify the connectivity.

    curl --verbose "https://cloud.gitlab.com"
   
    curl --verbose "https://customers.gitlab.com"
   

   If an HTTP/S proxy is configured for the GitLab instance, include the proxy parameter in the curl command.

    # https proxy for curl
    curl --verbose --proxy "http://USERNAME:PASSWORD@example.com:8080" "https://cloud.gitlab.com"
    curl --verbose --proxy "http://USERNAME:PASSWORD@example.com:8080" "https://customers.gitlab.com"
   

3. Optional. If you are using a proxy server between the GitLab application and the public internet, disable DNS rebinding protection.

4. Manually synchronize subscription data.

   • Verify that the GitLab instance synchronizes your subscription data with GitLab.

GitLab Duo features not available for users

In addition to turning on GitLab Duo features, you can also do the following:

1. Verify that subscription seats have been purchased.
2. Ensure that seats are assigned to users.
3. For IDE users with the GitLab Duo extension:
   • Verify that the extension is up-to-date.
   • Run extension setting health checks, and test the authentication.