히스토리

• 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. GitLab의 Amazon Q Developer를 선택합니다.
3. 시작하기를 선택합니다.
4. 프로필 이름에 해당 지역의 고유한 프로필 이름을 입력합니다. 예: QDevProfile-us-east-1.
5. 선택 사항. 프로필 설명 - 선택 사항에 설명을 입력합니다.
6. 생성을 선택합니다.

IAM ID 공급자 생성#

다음으로 IAM ID 공급자를 생성합니다.

먼저 GitLab에서 일부 값이 필요합니다:

사전 조건:

• 관리자여야 합니다.

1. GitLab에 로그인합니다.
2. 오른쪽 상단 모서리에서 관리자를 선택합니다.
3. 설정 > 일반을 선택합니다.
4. GitLab Duo with Amazon Q를 확장합니다.
5. 구성 설정 보기를 선택합니다.
6. 1단계에서 공급자 URL과 대상을 복사합니다. 다음 단계에서 필요합니다.

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

1. AWS IAM 콘솔에 로그인합니다.
2. 액세스 관리 > ID 공급자를 선택합니다.
3. 공급자 추가를 선택합니다.
4. 공급자 유형에서 OpenID Connect를 선택합니다.
5. 공급자 URL에 GitLab의 값을 입력합니다.
6. 대상에 GitLab의 값을 입력합니다.
7. 공급자 추가를 선택합니다.

IAM 역할 생성#

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

1. AWS IAM 콘솔에서 액세스 관리 > 역할 > 역할 생성을 선택합니다.

2. 웹 ID를 선택합니다.

3. 웹 ID에서 이전에 입력한 공급자 URL을 선택합니다.

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

5. 다음을 선택합니다.

6. 권한 추가 페이지에서:

   • 관리형 정책을 사용하려면 권한 정책에서 GitLabDuoWithAmazonQPermissionsPolicy를 검색하고 선택합니다.
   • 인라인 정책을 생성하려면 다음을 선택하여 권한 정책을 건너뜁니다. 나중에 정책을 생성합니다.

7. 다음을 선택합니다.

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. 역할 생성을 선택합니다.

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

관리형 정책 대신 인라인 정책을 생성하려면:

1. 권한 > 권한 추가 > 인라인 정책 생성을 선택합니다.

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. 작업 > 가독성 최적화를 선택하여 AWS가 JSON을 형식화하고 파싱합니다.

4. 다음을 선택합니다.

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

역할 편집#

이제 역할을 편집합니다:

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

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

   1. 역할 검색 필드에 IAM 역할 이름을 입력한 다음 역할 이름을 선택합니다.
   2. 요약에서 편집을 선택하여 세션 기간을 편집합니다.
   3. 최대 세션 기간 드롭다운 목록을 선택한 다음 12시간을 선택합니다.
   4. 변경 사항 저장을 선택합니다.

3. 페이지에 나열된 ARN을 복사합니다. 다음과 유사합니다:

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

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

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

사전 조건:

• GitLab 관리자여야 합니다.

GitLab Duo with Amazon Q 설정을 완료하려면:

1. GitLab에 로그인합니다.

2. 오른쪽 상단 모서리에서 관리자를 선택합니다.

3. 설정 > 일반을 선택합니다.

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

5. 구성 설정 보기를 선택합니다.

6. IAM 역할의 ARN 아래에 ARN을 붙여넣습니다.

7. GitLab Duo with Amazon Q를 사용할 수 있는 그룹과 프로젝트를 결정하려면 옵션을 선택합니다:

   • 인스턴스에서 켜되 그룹과 프로젝트가 끌 수 있도록 하려면 기본적으로 켜짐을 선택합니다.
     • 선택 사항. Amazon Q가 머지 리퀘스트의 코드를 자동으로 검토하도록 구성하려면 Amazon Q가 머지 리퀘스트에서 코드를 자동으로 검토하도록을 선택합니다.
   • 인스턴스에서 끄되 그룹과 프로젝트가 켤 수 있도록 하려면 기본적으로 꺼짐을 선택합니다.
   • 인스턴스에서 끄고 그룹이나 프로젝트가 켜는 것을 방지하려면 항상 꺼짐을 선택합니다.

8. 변경 사항 저장을 선택합니다.

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

성공했는지 확인하려면:

• Amazon CloudWatch 콘솔 로그에서 204 상태 코드를 확인합니다. 자세한 내용은 Amazon CloudWatch란 무엇인가를 참조하세요.
• GitLab에서 Amazon Q 설정이 저장되었습니다라는 알림이 표시됩니다.
• GitLab에서 왼쪽 사이드바의 애플리케이션을 선택합니다. 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을 보려면:

   Ai::Setting.instance.ai_gateway_url
   

3. 서비스 URL을 업데이트하려면:

   Ai::Setting.instance.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. 오른쪽 상단 모서리에서 관리자를 선택합니다.
3. 설정 > 일반을 선택합니다.
4. GitLab Duo with Amazon Q를 확장합니다.
5. 구성 설정 보기를 선택합니다.
6. 항상 꺼짐을 선택합니다.
7. 변경 사항 저장을 선택합니다.

그룹에 대해 끄기#

사전 조건:

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

그룹에 대해 GitLab Duo with Amazon Q를 끄려면:

1. 상단 바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
2. 설정 > 일반을 선택합니다.
3. Amazon Q를 확장합니다.
4. 옵션을 선택합니다:
   • 그룹에서 끄되 다른 그룹이나 프로젝트가 켤 수 있도록 하려면 기본적으로 꺼짐을 선택합니다.
   • 그룹에서 끄고 다른 그룹이나 프로젝트가 켜는 것을 방지하려면 항상 꺼짐을 선택합니다.
5. 변경 사항 저장을 선택합니다.

프로젝트에 대해 끄기#

사전 조건:

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

프로젝트에 대해 GitLab Duo with Amazon Q를 끄려면:

1. 상단 바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
2. 설정 > 일반을 선택합니다.
3. 가시성, 프로젝트 기능, 권한을 확장합니다.
4. Amazon Q 아래에서 토글을 끕니다.
5. 변경 사항 저장을 선택합니다.

문제 해결#

GitLab을 Amazon Q에 연결하는 데 문제가 발생하면 GitLab 설치가 모든 사전 조건을 충족하는지 확인하세요.

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

GitLab 인스턴스 UUID 불일치#

Amazon Q 연결을 해제할 때 GitLab instance UUID mismatch 오류가 발생할 수 있습니다. 이 문제는 일반적으로 다음 경우에 발생합니다:

• 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. 잠시 기다린 후 라이선스를 동기화합니다. 이 작업은 클라우드 커넥터 토큰을 강제로 재생성합니다. (이 단계를 수행하지 않으면 헤더 불일치가 발생합니다.)

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

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

   • 새 UUID로 기존 IdP와 IAM 역할을 업데이트하여 기존 설정을 계속 사용하고 GitLab Duo with Amazon Q를 계속 사용합니다.
   • 오프보딩:
     1. GitLab Duo with Amazon Q에서 오프보딩합니다.
     2. 원하는 경우 새 연결을 설정합니다.

완료되면 UUID 불일치 문제가 해결되어야 하며 GitLab Duo with Amazon Q가 새 구성으로 정상적으로 작동해야 합니다.