Set up GitLab Duo with Amazon Q

Tier: Ultimate Offering: Self-managed Status: Preview/Beta
History
  • Introduced as an experiment in GitLab 17.7 with a flag named amazon_q_integration. Disabled by default.
The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is a Preview/Beta and is available for testing, but not ready for production use.
These instructions are for users of the GDK only. Others should request access to a lab environment.

You can use GitLab Duo with Amazon Q to perform a variety of tasks, from creating merge requests and adding test coverage to reviewing changes for security and quality.

Set up GitLab Duo with Amazon Q

To set up GitLab Duo with Amazon Q, you must:

Prerequisites

  • You must have a self-managed GitLab instance:
    • With an HTTPS URL that can be accessed by Amazon Q.
    • With an Ultimate subscription that is synchronized with GitLab. (No trial access.)
    • With the amazon_q_integration feature flag enabled.
  • GitLab Duo features must be turned on. (Experimental and beta features are off by default.)

Create an IAM identity provider

Start by creating an IAM identity provider.

First, you need the some values from GitLab:

  1. Sign in to GitLab.
  2. On the left sidebar, at the bottom, select Admin.
  3. Select Settings > General.
  4. Expand Configure GitLab Duo with Amazon Q.
  5. Under step 1, copy the provider URL and audience. You will need them in the next step.

Now, create an AWS identity provider:

  1. Sign in to the AWS IAM console.
  2. Select Access Management > Identity providers.
  3. Select Add provider.
  4. For Provider type, select OpenID Connect.
  5. For Provider URL, enter the value from GitLab.
  6. For Audience, enter the value from GitLab.
  7. Select Add provider.

Create an IAM role

Next, you must create an IAM role that trusts the IAM identity provider and can access Amazon Q.

  1. In the AWS IAM console, select Access Management > Roles > Create role.
  2. Select Web identity.
  3. For Web identity, select the provider URL you entered earlier.
  4. For Audience, select the audience value you entered earlier.
  5. Skip Permissions policies by selecting Next. You will create an inline policy later.

  6. Ensure the trust policy is correct. It should look like this: 

    {
 "Version": "2012-10-17",
 "Statement": [
     {
         "Effect": "Allow",
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Principal": {
             "Federated": "arn:aws:iam::<AWS_Account_ID>:oidc-provider/auth.token.gitlab.com/cc/oidc/<Instance_ID>"
         },
         "Condition": {
             "StringEquals": {
                 "auth.token.gitlab.com/cc/oidc/<Instance_ID>": "gitlab-cc-<Instance_ID>"
             },

         }
      }
   ]
}
  7. Name the role, for example QDeveloperAccess, and select Create role.

Now edit the role and add the policy:

  1. Find the role that you just created and select it.

  2. Change the session time to 12 hours. The AssumeRoleWithWebIdentity will fail in the AI Gateway if the session is not set to 12 hours or more.

    1. In the Roles search field, enter the name of your IAM role and then choose the role name.
    2. In Summary, choose Edit to edit the session duration.
    3. Choose the Maximum session duration dropdown menu, and then choose 12 hours.
    4. Choose Save changes.
  3. Select Permissions > Add permissions > Create inline policy.

  4. Select JSON and paste the following in the editor: 

    {
   "Version": "2012-10-17",
   "Statement": [
      {
         "Sid": "GitLabDuoPermissions",
         "Effect": "Allow",
         "Action": [
            "q:SendEvent",
            "q:CreateOAuthAppConnection",
            "q:CreateAuthGrant",
            "q:UpdateAuthGrant",
            "q:UpdateOAuthAppConnection"
         ],
         "Resource": "*"
      }
   ]
}
  5. Select Actions > Optimize for readability to make AWS format and parse the JSON.
  6. Select Next.
  7. Name the policy gitlab-duo-amazon-q-policy and select Create policy.

  8. Copy the ARN listed on the page. It will look similar to this: 

    arn:aws:iam::123456789:role/QDeveloperAccess

Enter the ARN in GitLab and enable Amazon Q

Now, enter the ARN into GitLab and determine which groups and projects can access the feature.

Prerequisites:

  • You must be a GitLab administrator.
  1. Sign in to GitLab.
  2. On the left sidebar, at the bottom, select Admin.
  3. Select Settings > General.
  4. Expand Configure GitLab Duo with Amazon Q.
  5. Select View configuration setup.
  6. Under IAM role’s ARN, paste the ARN.
  7. To determine which groups and projects can use GitLab Duo with Amazon Q, choose an option:
    • To turn it on for the instance, but let groups and projects turn it off, select On by default.
    • To turn it off for the instance, but let groups and projects turn it on, select Off by default.
    • To turn it off for the instance, and to prevent groups or projects from ever turning it on, select Always off.
  8. Select Save changes.

When you save, an API should contact the AI Gateway to create an OAuth application on Amazon Q. To confirm that it was successful, check the logs for a 204.

Configure the AI gateway

Now configure your AI gateway.

  1. On your GitLab instance, in /etc/gitlab/gitlab.rb, in production mode, your gitlab_rails['env'] configuration should look like: 

    gitlab_rails['env'] = {
  "AI_GATEWAY_URL" => "https://ai-gateway-panda.runway.gitlab.net"
}

    Be sure that GITLAB_LICENSE_MODE, CUSTOMER_PORTAL_URL, and CLOUD_CONNECTOR_SELF_SIGN_TOKENS are NOT set.

    For staging, your /etc/gitlab/gitlab.rb should have: 

    gitlab_rails['env'] = {
  "GITLAB_LICENSE_MODE" => "test",
  "CUSTOMER_PORTAL_URL" => "https://customers.staging.gitlab.com",
  "AI_GATEWAY_URL" => "https://ai-gateway-panda.staging.runway.gitlab.net"
}

  2. Run gitlab-ctl reconfigure for these changes to take effect.

Turn off GitLab Duo with Amazon Q

You can turn off GitLab Duo with Amazon Q for the instance, group, or project.

Turn off for the instance

Prerequisites:

  • You must be an administrator.

To turn off GitLab Duo with Amazon Q for the instance:

  1. On the left sidebar, at the bottom, select Admin.
  2. Select Settings > General.
  3. Expand Amazon Q.
  4. Select View configuration setup.
  5. Select Always off.
  6. Select Save changes.

Turn off for a group

Prerequisites:

  • You must have the Owner role for a group.

To turn off GitLab Duo with Amazon Q for a group:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Settings > General.
  3. Expand Amazon Q.
  4. Choose an option:
    • To turn it off for the group, but let other groups or projects turn it on, select Off by default.
    • To turn if off for the group, and to prevent other groups or projects from turning it on, select Always off.
  5. Select Save changes.

Turn off for a project

Prerequisites:

  • You must have the Owner role for a project.

To turn off GitLab Duo with Amazon Q for a project:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Settings > General.
  3. Under Amazon Q, turn the toggle off.
  4. Select Save changes.