히스토리

• GitLab 17.7에서 amazon_q_integration 기능 플래그와 함께 실험 기능으로 도입. 기본적으로 비활성화.
• GitLab 17.8에서 기능 플래그 amazon_q_integration 제거.
• GitLab 17.11에서 일반 공개.

GitLab Duo with Amazon Q 구독을 신청하려면 담당 Account Executive에게 문의합니다.

평가판을 요청하려면 이 양식을 작성합니다.

GitLab Self-Managed에서 GitLab Duo with Amazon Q를 설정하려면 다음 단계를 완료합니다.

GitLab Duo with Amazon Q 설정#

GitLab Duo with Amazon Q를 설정하려면 다음을 수행해야 합니다.

• 사전 요구 사항 완료
• Amazon Q Developer 콘솔에서 프로필 생성
• ID 공급자 생성
• IAM 역할 생성
• 역할 편집
• GitLab에 ARN 입력 후 Amazon Q 활성화
• 관리자의 고객 관리 키 사용 허용

사전 요구 사항#

• GitLab Self-Managed가 다음 조건을 충족해야 합니다.
  • GitLab 17.11 이상입니다.
  • Amazon Q는 요청한 동작을 수행할 때 GitLab 인스턴스의 REST API로 데이터를 읽고 쓰므로 해당 인스턴스의 HTTPS URL에 접근할 수 있어야 합니다(SSL 인증서는 자체 서명된 것이 아니어야 합니다).
  • 인스턴스는 다음 IP 주소에서 시작되는 Amazon Q 서비스의 인바운드 네트워크 접근을, 인스턴스에 설정된 포트에서 TCP/TLS로 허용해야 합니다. 기본값은 포트 443 입니다.
    • 34.228.181.128
    • 44.219.176.187
    • 54.226.244.221
  • GitLab과 동기화된 Ultimate 구독과 GitLab Duo with Amazon Q 애드온이 있어야 합니다.

Amazon Q Developer 콘솔에서 프로필 생성#

Amazon Q Developer 프로필을 생성합니다.

1. Amazon Q Developer 콘솔을 엽니다.
2. Amazon Q Developer in GitLab을 선택합니다.
3. Get Started를 선택합니다.
4. Profile name에 해당 리전에서 고유한 프로필 이름을 입력합니다. 예를 들면 QDevProfile-us-east-1 입니다.
5. 선택 사항입니다. Profile description - optional에 설명을 입력합니다.
6. Create를 선택합니다.

IAM ID 공급자 생성#

IAM ID 공급자를 생성합니다. 먼저 GitLab에서 몇 가지 값을 가져옵니다.

사전 요구 사항:

• 관리자여야 합니다.

1. GitLab에 로그인합니다.
2. 오른쪽 위 모서리에서 Admin을 선택합니다.
3. 왼쪽 사이드바에서 Settings > General을 선택합니다.
4. GitLab Duo with Amazon Q를 확장합니다.
5. View configuration setup을 선택합니다.
6. 1단계 아래에서 공급자 URL과 대상(audience)을 복사합니다. 다음 단계에서 필요합니다.

이제 AWS ID 공급자를 생성합니다.

1. AWS IAM 콘솔에 로그인합니다.
2. Access Management > Identity providers를 선택합니다.
3. Add provider를 선택합니다.
4. Provider type에서 OpenID Connect를 선택합니다.
5. Provider URL에 GitLab에서 가져온 값을 입력합니다.
6. Audience에 GitLab에서 가져온 값을 입력합니다.
7. Add provider를 선택합니다.

IAM 역할 생성#

다음으로 IAM ID 공급자를 신뢰하고 Amazon Q에 접근할 수 있는 IAM 역할을 생성해야 합니다.

1. AWS IAM 콘솔에서 Access Management > Roles > Create role을 선택합니다.

2. Web identity를 선택합니다.

3. Web identity에서 앞서 입력한 공급자 URL을 선택합니다.

4. Audience에서 앞서 입력한 대상 값을 선택합니다.

5. Next를 선택합니다.

6. Add permissions 페이지에서 다음을 수행합니다.

   • 관리형 정책을 사용하려면 Permissions policies에서 GitLabDuoWithAmazonQPermissionsPolicy를 검색해 선택합니다.
   • 인라인 정책을 생성하려면 Next를 선택해 Permissions policies를 건너뜁니다. 정책은 나중에 생성합니다.

7. Next를 선택합니다.

8. 역할 이름을 지정합니다. 예를 들면 QDeveloperAccess 입니다.

9. 신뢰 정책이 올바른지 확인합니다. 다음과 같아야 합니다.

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

10. Create role을 선택합니다.

인라인 정책 생성(선택 사항)#

관리형 정책을 사용하는 대신 인라인 정책을 생성하려면 다음을 수행합니다.

1. Permissions > Add permissions > Create inline policy를 선택합니다.

2. JSON을 선택하고 편집기에 다음을 붙여넣습니다.

   {
     "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/*"
       }
     ]
   }
   

3. Actions > Optimize for readability를 선택해 AWS가 JSON을 서식에 맞게 정리하고 파싱하도록 합니다.

4. Next를 선택합니다.

5. 정책 이름을 gitlab-duo-amazon-q-policy로 지정하고 Create policy를 선택합니다.

역할 편집#

이제 역할을 편집합니다.

1. 방금 생성한 역할을 찾아 선택합니다.

2. 세션 시간을 12시간으로 변경합니다. 세션이 12시간 이상으로 설정되지 않으면 AI Gateway에서 AssumeRoleWithWebIdentity가 실패합니다.

   1. Roles search 필드에 IAM 역할 이름을 입력한 다음 역할 이름을 선택합니다.
   2. Summary에서 Edit를 선택해 세션 기간을 편집합니다.
   3. Maximum session duration 드롭다운 목록을 선택한 다음 12 hours를 선택합니다.
   4. Save changes를 선택합니다.

3. 페이지에 표시된 ARN을 복사합니다. 다음과 비슷한 형태입니다.

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

GitLab에 ARN 입력 후 Amazon Q 활성화#

이제 ARN을 GitLab에 입력하고 어떤 그룹과 프로젝트가 이 기능을 사용할 수 있는지 지정합니다.

사전 요구 사항:

• GitLab 관리자여야 합니다.

GitLab Duo with Amazon Q 설정을 마치려면 다음을 수행합니다.

1. GitLab에 로그인합니다.

2. 오른쪽 위 모서리에서 Admin을 선택합니다.

3. 왼쪽 사이드바에서 Settings > General을 선택합니다.

4. GitLab Duo with Amazon Q를 확장합니다.

5. View configuration setup을 선택합니다.

6. IAM role's ARN 아래에 ARN을 붙여넣습니다.

7. GitLab Duo with Amazon Q를 사용할 수 있는 그룹과 프로젝트를 지정하려면 다음 중 하나를 선택합니다.

   • 인스턴스에서는 켜되 그룹과 프로젝트가 끌 수 있도록 하려면 On by default를 선택합니다.
     • 선택 사항입니다. Amazon Q가 머지 리퀘스트의 코드를 자동으로 검토하도록 설정하려면 Have Amazon Q review code in merge requests automatically를 선택합니다.
   • 인스턴스에서는 끄되 그룹과 프로젝트가 켤 수 있도록 하려면 Off by default를 선택합니다.
   • 인스턴스에서 끄고 그룹이나 프로젝트가 켜지 못하도록 하려면 Always off를 선택합니다.

8. Save changes를 선택합니다.

저장하면 API가 AI Gateway에 연결해 Amazon Q에 OAuth 애플리케이션을 생성합니다.

성공 여부는 다음으로 확인합니다.

• Amazon CloudWatch 콘솔 로그에서 204 상태 코드를 확인합니다. 자세한 내용은 Amazon CloudWatch 개요를 참고합니다.
• GitLab에 Amazon Q settings have been saved라는 알림이 표시됩니다.
• GitLab의 왼쪽 사이드바에서 Applications를 선택합니다. Amazon Q OAuth 애플리케이션이 표시됩니다.

관리자의 고객 관리 키 사용 허용#

관리자는 AWS Key Management Service(AWS KMS) 고객 관리 키(CMK)를 사용해 고객 데이터를 암호화할 수 있습니다.

KMS 콘솔에서 설정된 역할에 키 정책을 생성할 때, CMK 사용 권한을 부여하도록 역할 정책을 업데이트합니다.

kms:ViaService 조건 키는 KMS 키 사용을 지정한 AWS 서비스의 요청으로 제한합니다. 또한 특정 서비스에서 요청이 들어올 때 KMS 키 사용을 거부하는 데도 사용합니다. 이 조건 키로 콘텐츠를 암호화하거나 복호화할 때 CMK를 사용할 수 있는 대상을 제한할 수 있습니다.

{
   "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"
                ]
            }
        }
      }
   ]
}

자세한 내용은 AWS KMS 개발자 가이드의 kms:ViaService를 참고합니다.

AWS 호스팅 AI Gateway를 사용하도록 GitLab 설정#

AWS에서 호스팅되는 AI Gateway를 사용하도록 GitLab을 설정할 수 있습니다.

1. Rails 콘솔 세션을 시작합니다. 예를 들어 Linux 패키지를 사용하는 설치에서는 다음을 실행합니다.

   sudo gitlab-rails console
   

2. 현재 지정된 서비스 URL을 확인하려면 다음을 실행합니다.

   ApplicationSetting.current.ai_gateway_url
   

3. 서비스 URL을 업데이트하려면 다음을 실행합니다.

   ApplicationSetting.current.update!(ai_gateway_url: "https://cloud.gitlab.com/aws/ai")
   

GitLab Duo with Amazon Q 끄기#

인스턴스, 그룹 또는 프로젝트 단위로 GitLab Duo with Amazon Q를 끌 수 있습니다.

인스턴스에서 끄기#

사전 요구 사항:

• 관리자여야 합니다.

인스턴스에서 GitLab Duo with Amazon Q를 끄려면 다음을 수행합니다.

1. GitLab에 로그인합니다.
2. 오른쪽 위 모서리에서 Admin을 선택합니다.
3. 왼쪽 사이드바에서 Settings > General을 선택합니다.
4. GitLab Duo with Amazon Q를 확장합니다.
5. View configuration setup을 선택합니다.
6. Always off를 선택합니다.
7. Save changes를 선택합니다.

그룹에서 끄기#

사전 요구 사항:

• 그룹에 대한 Owner 권한이 있어야 합니다.

그룹에서 GitLab Duo with Amazon Q를 끄려면 다음을 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Amazon Q를 확장합니다.
4. 다음 중 하나를 선택합니다.
   • 그룹에서는 끄되 다른 그룹이나 프로젝트가 켤 수 있도록 하려면 Off by default를 선택합니다.
   • 그룹에서 끄고 다른 그룹이나 프로젝트가 켜지 못하도록 하려면 Always off를 선택합니다.
5. Save changes를 선택합니다.

프로젝트에서 끄기#

사전 요구 사항:

• 프로젝트에 대한 Owner 권한이 있어야 합니다.

프로젝트에서 GitLab Duo with Amazon Q를 끄려면 다음을 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Visibility, project features, permissions를 확장합니다.
4. Amazon Q 아래에서 토글을 끕니다.
5. Save changes를 선택합니다.

문제 해결#

GitLab을 Amazon Q에 연결할 때 문제가 발생하면 GitLab 설치가 모든 사전 요구 사항을 충족하는지 확인합니다.

다음 문제가 발생할 수도 있습니다.

GitLab 인스턴스 UUID 불일치#

Amazon Q 연결을 해제할 때 GitLab instance UUID mismatch 오류가 발생하거나, 상태 점검을 실행할 때 Cannot obtain OIDC token 오류가 발생할 수 있습니다. 예를 들면 다음과 같습니다.

Authentication with the AI gateway services failed: AI Gateway returned code 500: {"detail":"Cannot obtain OIDC token"}
Amazon Q connectivity check failed: Cannot obtain OIDC token

이러한 오류는 일반적으로 다음 경우에 발생합니다.

• GitLab 인스턴스를 백업에서 복원한 경우입니다.
• GitLab 인스턴스를 새 인프라로 마이그레이션한 경우입니다.
• 그 밖의 이유로 GitLab 인스턴스 UUID가 변경된 경우입니다.

UUID 불일치가 근본 원인인지 확인하려면 다음 검증 단계를 진행합니다.

검증#

1. GitLab 이 호스팅된 EC2 인스턴스에 로그인합니다.

2. Rails 콘솔에 접속합니다.

3. 현재 UUID를 가져옵니다. Gitlab::CurrentSettings.current_application_settings.uuid

4. JWT 토큰을 가져옵니다.

   token = CloudConnector::Tokens.get(unit_primitive: :agent_quick_actions, resource: :instance)
   JWT.decode(token, false, nil)
   

3단계의 sub 필드와 4단계의 gitlab_instance_uuid 사이에 UUID 불일치가 있으면 이 문제에 해당합니다.

이 문제를 해결하려면 다음 단계를 완료합니다.

1. 활성 라이선스를 모두 제거합니다.

2. 구독 애드온 구매를 모두 삭제합니다.

   Rails 콘솔을 열고 다음을 실행합니다.

   GitlabSubscriptions::AddOnPurchase.all.destroy_all
   

3. 인스턴스 UUID 재설정을 실행합니다. Rails 콘솔에서 다음을 실행합니다.

   ApplicationSetting.update!(uuid: SecureRandom.uuid)
   

4. 활성 라이선스를 적용합니다.

5. 1분 정도 기다린 뒤 라이선스를 동기화합니다. 이 작업은 클라우드 커넥터 토큰을 강제로 재생성합니다. (이 단계를 건너뛰면 헤더 불일치가 발생합니다.)

6. 새 UUID로 IdP와 IAM 역할을 업데이트합니다.

7. 다음 단계를 선택합니다.

   • 기존 IdP와 IAM 역할을 새 UUID로 업데이트해 기존 설정을 그대로 사용하면서 GitLab Duo with Amazon Q를 계속 사용합니다.
   • 오프보딩합니다.
     1. GitLab Duo with Amazon Q에서 오프보딩합니다.
     2. 필요하면 새 연결을 설정합니다.

작업을 마치면 UUID 불일치 문제가 해결되고 GitLab Duo with Amazon Q가 새 설정으로 정상 동작합니다.