doc/user/duo_amazon_q/setup.md
{{< details >}}
{{< /details >}}
{{< history >}}
amazon_q_integration. Disabled by default.amazon_q_integration removed in GitLab 17.8.{{< /history >}}
[!note] GitLab Duo with Amazon Q cannot be combined with other GitLab Duo add-ons.
To get a subscription for GitLab Duo with Amazon Q, contact your Account Executive.
To request a trial, fill out this form.
To set up GitLab Duo with Amazon Q on GitLab Self-Managed, complete the following steps.
To set up GitLab Duo with Amazon Q, you must:
34.228.181.12844.219.176.18754.226.244.221Create an Amazon Q Developer profile.
QDevProfile-us-east-1.Next, create an IAM identity provider.
First, you need the some values from GitLab:
Prerequisites:
Now, create an AWS identity provider:
Next, you must create an IAM role that trusts the IAM identity provider and can access Amazon Q.
[!note] After you set up the IAM role, you cannot change the AWS account that's associated with the role.
In the AWS IAM console, select Access Management > Roles > Create role.
Select Web identity.
For Web identity, select the provider URL you entered earlier.
For Audience, select the audience value you entered earlier.
Select Next.
On the Add permissions page:
GitLabDuoWithAmazonQPermissionsPolicy.Select Next.
Name the role, for example QDeveloperAccess.
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>:aud": "gitlab-cc-<Instance_ID>"
},
}
}
]
}
Select Create role.
To create an inline policy, rather than using a managed policy:
Select Permissions > Add permissions > Create inline policy.
Select JSON and paste the following in the editor:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "GitLabDuoUsagePermissions",
"Effect": "Allow",
"Action": [
"q:SendEvent",
"q:CreateAuthGrant",
"q:UpdateAuthGrant",
"q:GenerateCodeRecommendations",
"q:SendMessage",
"q:ListPlugins",
"q:VerifyOAuthAppConnection"
],
"Resource": "*"
},
{
"Sid": "GitLabDuoManagementPermissions",
"Effect": "Allow",
"Action": [
"q:CreateOAuthAppConnection",
"q:DeleteOAuthAppConnection"
],
"Resource": "*"
},
{
"Sid": "GitLabDuoPluginPermissions",
"Effect": "Allow",
"Action": [
"q:CreatePlugin",
"q:DeletePlugin",
"q:GetPlugin"
],
"Resource": "arn:aws:qdeveloper:*:*:plugin/GitLabDuoWithAmazonQ/*"
}
]
}
Select Actions > Optimize for readability to make AWS format and parse the JSON.
Select Next.
Name the policy gitlab-duo-amazon-q-policy and select Create policy.
Now edit the role:
Find the role that you just created and select it.
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.
Copy the ARN listed on the page. It will look similar to this:
arn:aws:iam::123456789:role/QDeveloperAccess
Now, enter the ARN into GitLab and determine which groups and projects can access the feature.
Prerequisites:
To finish setting up GitLab Duo with Amazon Q:
Sign in to GitLab.
In the upper-right corner, select Admin.
Select Settings > General.
Expand GitLab Duo with Amazon Q.
Select View configuration setup.
Under IAM role's ARN, paste the ARN.
To determine which groups and projects can use GitLab Duo with Amazon Q, choose an option:
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:
204 status code. For more information, see
What is Amazon CloudWatch?Amazon Q settings have been saved is displayed.If you are an administrator, you can use AWS Key Management Service (AWS KMS) customer managed keys (CMKs) to encrypt customer data.
Update the role policy to grant permission to use CMKs when you create your key policy on a configured role in the KMS console.
The kms:ViaService condition key limits the use of a KMS key to requests from specified AWS services.
Additionally, it's used to deny permission to use a KMS key when the request comes from particular services.
With the condition key, you can limit who can use CMK for encrypting or decrypting content.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Sid0",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::<awsAccountId>:role/<rolename>"
},
"Action": [
"kms:Decrypt",
"kms:DescribeKey",
"kms:Encrypt",
"kms:GenerateDataKey",
"kms:GenerateDataKeyWithoutPlaintext",
"kms:ReEncryptFrom",
"kms:ReEncryptTo"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": [
"q.<region>.amazonaws.com"
]
}
}
}
]
}
For more information, see
kms:ViaService in the AWS KMS Developer Guide.
You can configure GitLab to use the hosted AI Gateway on AWS.
Start a Rails console session. For example, for installations that use the Linux package, run:
sudo gitlab-rails console
To view the currently assigned service URL, run:
Ai::Setting.instance.ai_gateway_url
To update the service URL, run:
Ai::Setting.instance.update!(ai_gateway_url: "https://cloud.gitlab.com/aws/ai")
You can turn off GitLab Duo with Amazon Q for the instance, group, or project.
Prerequisites:
To turn off GitLab Duo with Amazon Q for the instance:
Prerequisites:
To turn off GitLab Duo with Amazon Q for a group:
Prerequisites:
To turn off GitLab Duo with Amazon Q for a project:
If you experience issues connecting GitLab to Amazon Q, ensure your GitLab installation meets all the prerequisites.
You might also encounter the following issue.
You might encounter a GitLab instance UUID mismatch error when disconnecting Amazon Q. This issue typically occurs when:
To confirm that a mismatched UUID is the root cause, proceed with the following validation steps.
Sign in to the EC2 instance where GitLab is hosted.
Access the Rails console.
Get the current UUID: Gitlab::CurrentSettings.current_application_settings.uuid
Get the JWT token:
token = CloudConnector::Tokens.get(unit_primitive: :agent_quick_actions, resource: :instance)
JWT.decode(token, false, nil)
The issue is apparent when a mismatch in the UUID exists between the sub field in step 3 and the gitlab_instance_uuid from step 4.
To resolve this issue, complete the following steps.
Remove all active licenses.
Delete all subscription add-on purchases:
Open the Rails console and execute:
GitlabSubscriptions::AddOnPurchase.all.destroy_all
Execute instance UUID reset. In the Rails console, execute:
ApplicationSetting.update!(uuid: SecureRandom.uuid)
Apply the active license.
Wait a minute or so and synchronize the license. This action forces the cloud connector token to regenerate. (Without this step, a header mismatch occurs.)
Update the IdP and IAM role with the new UUID.
Choose a next step:
When you are done, the UUID mismatch issue should be resolved and GitLab Duo with Amazon Q should function properly with the new configuration.