GitLab CI/CD용 Claude Code는 현재 베타 버전입니다. 경험을 개선하면서 기능과 기능성이 진화할 수 있습니다.이 통합은 GitLab에서 유지 관리합니다. 지원을 받으려면 다음 GitLab 이슈를 참조하세요.
이 통합은 Claude Code CLI 및 SDK를 기반으로 구축되어 CI/CD 작업 및 사용자 정의 자동화 워크플로우에서 Claude를 프로그래밍 방식으로 사용할 수 있습니다.
GitLab에서 Claude Code를 사용하는 이유는 무엇입니까?
- 즉시 MR 생성: 필요한 사항을 설명하면 Claude가 변경 사항 및 설명이 포함된 완전한 MR을 제안합니다
- 자동화된 구현: 단일 명령 또는 언급으로 문제를 작동하는 코드로 변환합니다
- 프로젝트 인식: Claude는
CLAUDE.md지침 및 기존 코드 패턴을 따릅니다 - 간단한 설정:
.gitlab-ci.yml에 하나의 작업과 마스킹된 CI/CD 변수를 추가합니다 - 엔터프라이즈 준비: Claude API, AWS Bedrock 또는 Google Vertex AI를 선택하여 데이터 상주 및 조달 요구 사항을 충족합니다
- 기본적으로 안전: GitLab 러너에서 분기 보호 및 승인과 함께 실행됩니다
작동 방식
Claude Code는 GitLab CI/CD를 사용하여 격리된 작업에서 AI 작업을 실행하고 MR을 통해 결과를 다시 커밋합니다:-
이벤트 기반 오케스트레이션: GitLab은 선택한 트리거(예: 이슈, MR 또는 검토 스레드에서
@claude를 언급하는 댓글)를 수신합니다. 작업은 스레드 및 저장소에서 컨텍스트를 수집하고, 해당 입력에서 프롬프트를 작성하고, Claude Code를 실행합니다. -
공급자 추상화: 환경에 맞는 공급자를 사용합니다:
- Claude API (SaaS)
- AWS Bedrock (IAM 기반 액세스, 교차 지역 옵션)
- Google Vertex AI (GCP 네이티브, Workload Identity Federation)
- 샌드박스 실행: 각 상호 작용은 엄격한 네트워크 및 파일 시스템 규칙이 있는 컨테이너에서 실행됩니다. Claude Code는 쓰기를 제한하기 위해 작업 공간 범위 권한을 적용합니다. 모든 변경 사항은 MR을 통해 흐르므로 검토자가 diff를 보고 승인이 여전히 적용됩니다.
Claude가 할 수 있는 것은 무엇입니까?
Claude Code는 코드 작업 방식을 변환하는 강력한 CI/CD 워크플로우를 활성화합니다:- 이슈 설명 또는 댓글에서 MR 생성 및 업데이트
- 성능 회귀 분석 및 최적화 제안
- 분기에서 직접 기능 구현, 그 다음 MR 열기
- 테스트 또는 댓글로 식별된 버그 및 회귀 수정
- 후속 댓글에 응답하여 요청된 변경 사항에 대해 반복
설정
빠른 설정
가장 빠른 시작 방법은.gitlab-ci.yml에 최소 작업을 추가하고 API 키를 마스킹된 변수로 설정하는 것입니다.
-
마스킹된 CI/CD 변수 추가
- 설정 → CI/CD → 변수로 이동합니다
ANTHROPIC_API_KEY추가(마스킹됨, 필요에 따라 보호됨)
-
.gitlab-ci.yml에 Claude 작업 추가
ANTHROPIC_API_KEY 변수를 추가한 후 CI/CD → 파이프라인에서 작업을 수동으로 실행하여 테스트하거나, MR에서 트리거하여 Claude가 분기에서 업데이트를 제안하고 필요한 경우 MR을 열 수 있습니다.
Claude API 대신 AWS Bedrock 또는 Google Vertex AI에서 실행하려면 아래의 AWS Bedrock 및 Google Vertex AI와 함께 사용 섹션을 참조하여 인증 및 환경 설정을 확인하세요.
수동 설정(프로덕션에 권장)
더 제어된 설정을 선호하거나 엔터프라이즈 공급자가 필요한 경우:-
공급자 액세스 구성:
- Claude API:
ANTHROPIC_API_KEY를 생성하고 마스킹된 CI/CD 변수로 저장합니다 - AWS Bedrock: GitLab 구성 → AWS OIDC를 구성하고 Bedrock용 IAM 역할을 생성합니다
- Google Vertex AI: GitLab용 Workload Identity Federation 구성 → GCP
- Claude API:
-
GitLab API 작업을 위한 프로젝트 자격 증명 추가:
- 기본적으로
CI_JOB_TOKEN을 사용하거나api범위가 있는 프로젝트 액세스 토큰을 생성합니다 - PAT를 사용하는 경우
GITLAB_ACCESS_TOKEN(마스킹됨)으로 저장합니다
- 기본적으로
-
.gitlab-ci.yml에 Claude 작업 추가(아래 예제 참조) -
(선택 사항) 언급 기반 트리거 활성화:
- 이벤트 리스너에 “댓글(노트)“에 대한 프로젝트 웹훅 추가(사용하는 경우)
- 댓글에
@claude가 포함될 때AI_FLOW_INPUT및AI_FLOW_CONTEXT와 같은 변수를 사용하여 파이프라인 트리거 API를 호출하도록 리스너를 설정합니다
예제 사용 사례
이슈를 MR로 변환
이슈 댓글에서:구현 도움 받기
MR 토론에서:버그 빠르게 수정
이슈 또는 MR 댓글에서:AWS Bedrock 및 Google Vertex AI와 함께 사용
엔터프라이즈 환경의 경우 동일한 개발자 경험으로 클라우드 인프라에서 완전히 Claude Code를 실행할 수 있습니다.필수 조건
AWS Bedrock으로 Claude Code를 설정하기 전에 다음이 필요합니다:- 원하는 Claude 모델에 대한 Amazon Bedrock 액세스가 있는 AWS 계정
- AWS IAM에서 OIDC 자격 증명 공급자로 구성된 GitLab
- Bedrock 권한이 있는 IAM 역할 및 GitLab 프로젝트/참조로 제한된 신뢰 정책
- 역할 가정을 위한 GitLab CI/CD 변수:
AWS_ROLE_TO_ASSUME(역할 ARN)AWS_REGION(Bedrock 지역)
설정 지침
OIDC를 통해 GitLab CI 작업이 IAM 역할을 가정하도록 AWS를 구성합니다(정적 키 없음).필수 설정:- Amazon Bedrock을 활성화하고 대상 Claude 모델에 대한 액세스를 요청합니다
- 아직 없는 경우 GitLab용 IAM OIDC 공급자를 생성합니다
- GitLab OIDC 공급자를 신뢰하고 프로젝트 및 보호된 참조로 제한되는 IAM 역할을 생성합니다
- Bedrock 호출 API에 대한 최소 권한 권한을 연결합니다
AWS_ROLE_TO_ASSUMEAWS_REGION
구성 예제
파이프라인에 맞게 조정할 수 있는 즉시 사용 가능한 스니펫입니다.기본 .gitlab-ci.yml (Claude API)
AWS Bedrock 작업 예제 (OIDC)
필수 조건:- Amazon Bedrock이 활성화되고 선택한 Claude 모델에 액세스할 수 있음
- AWS에서 GitLab OIDC가 구성되고 GitLab 프로젝트 및 참조를 신뢰하는 역할
- Bedrock 권한이 있는 IAM 역할(최소 권한 권장)
AWS_ROLE_TO_ASSUME: Bedrock 액세스를 위한 IAM 역할의 ARNAWS_REGION: Bedrock 지역 (예:us-west-2)
Bedrock의 모델 ID에는 지역별 접두사 및 버전 접미사가 포함됩니다(예:
us.anthropic.claude-sonnet-4-5-20250929-v1:0). 워크플로우에서 지원하는 경우 작업 구성 또는 프롬프트를 통해 원하는 모델을 전달합니다.Google Vertex AI 작업 예제 (Workload Identity Federation)
필수 조건:- GCP 프로젝트에서 Vertex AI API 활성화됨
- GitLab OIDC를 신뢰하도록 구성된 Workload Identity Federation
- Vertex AI 권한이 있는 서비스 계정
GCP_WORKLOAD_IDENTITY_PROVIDER: 전체 공급자 리소스 이름GCP_SERVICE_ACCOUNT: 서비스 계정 이메일CLOUD_ML_REGION: Vertex 지역 (예:us-east5)
Workload Identity Federation을 사용하면 서비스 계정 키를 저장할 필요가 없습니다. 저장소별 신뢰 조건 및 최소 권한 서비스 계정을 사용합니다.
모범 사례
CLAUDE.md 구성
저장소 루트에CLAUDE.md 파일을 생성하여 코딩 표준, 검토 기준 및 프로젝트별 규칙을 정의합니다. Claude는 실행 중에 이 파일을 읽고 변경 사항을 제안할 때 규칙을 따릅니다.
보안 고려 사항
API 키 또는 클라우드 자격 증명을 저장소에 커밋하지 마세요! 항상 GitLab CI/CD 변수를 사용합니다:ANTHROPIC_API_KEY를 마스킹된 변수로 추가합니다(필요한 경우 보호함)- 가능한 경우 공급자별 OIDC 사용(장기 키 없음)
- 작업 권한 및 네트워크 송신 제한
- 다른 기여자처럼 Claude의 MR 검토
성능 최적화
CLAUDE.md를 집중적이고 간결하게 유지합니다- 명확한 이슈/MR 설명을 제공하여 반복을 줄입니다
- 작업 시간 초과를 구성하여 폭주 실행을 방지합니다
- 가능한 경우 러너에서 npm 및 패키지 설치를 캐시합니다
CI 비용
GitLab CI/CD와 함께 Claude Code를 사용할 때 관련 비용을 인식합니다:-
GitLab Runner 시간:
- Claude는 GitLab 러너에서 실행되고 컴퓨팅 분을 소비합니다
- GitLab 플랜의 러너 청구 세부 정보를 참조하세요
-
API 비용:
- 각 Claude 상호 작용은 프롬프트 및 응답 크기에 따라 토큰을 소비합니다
- 토큰 사용량은 작업 복잡도 및 코드베이스 크기에 따라 다릅니다
- Anthropic 가격을 참조하세요
-
비용 최적화 팁:
- 특정
@claude명령을 사용하여 불필요한 턴을 줄입니다 - 적절한
max_turns및 작업 시간 초과 값을 설정합니다 - 동시성을 제한하여 병렬 실행을 제어합니다
- 특정
보안 및 거버넌스
- 각 작업은 제한된 네트워크 액세스가 있는 격리된 컨테이너에서 실행됩니다
- Claude의 변경 사항은 MR을 통해 흐르므로 검토자가 모든 diff를 봅니다
- 분기 보호 및 승인 규칙이 AI 생성 코드에 적용됩니다
- Claude Code는 쓰기를 제한하기 위해 작업 공간 범위 권한을 사용합니다
- 자신의 공급자 자격 증명을 가져오기 때문에 비용이 제어됩니다
문제 해결
Claude가 @claude 명령에 응답하지 않음
- 파이프라인이 트리거되고 있는지 확인합니다(수동, MR 이벤트 또는 노트 이벤트 리스너/웹훅을 통해)
- CI/CD 변수(
ANTHROPIC_API_KEY또는 클라우드 공급자 설정)가 있고 마스킹 해제되어 있는지 확인합니다 - 댓글에
@claude가 포함되어 있는지 확인합니다(/claude아님) 그리고 언급 트리거가 구성되어 있는지 확인합니다
작업이 댓글을 쓰거나 MR을 열 수 없음
CI_JOB_TOKEN이 프로젝트에 충분한 권한이 있는지 확인하거나api범위가 있는 프로젝트 액세스 토큰을 사용합니다mcp__gitlab도구가--allowedTools에서 활성화되어 있는지 확인합니다- 작업이 MR의 컨텍스트에서 실행되거나
AI_FLOW_*변수를 통해 충분한 컨텍스트가 있는지 확인합니다
인증 오류
- Claude API의 경우:
ANTHROPIC_API_KEY가 유효하고 만료되지 않았는지 확인합니다 - Bedrock/Vertex의 경우: OIDC/WIF 구성, 역할 가장 및 비밀 이름을 확인합니다. 지역 및 모델 가용성을 확인합니다
고급 구성
일반적인 매개변수 및 변수
Claude Code는 다음과 같이 일반적으로 사용되는 입력을 지원합니다:prompt/prompt_file: 인라인(-p) 또는 파일을 통해 지침을 제공합니다max_turns: 왕복 반복 횟수를 제한합니다timeout_minutes: 총 실행 시간을 제한합니다ANTHROPIC_API_KEY: Claude API에 필수(Bedrock/Vertex에는 사용되지 않음)- 공급자별 환경:
AWS_REGION, Vertex용 프로젝트/지역 변수
정확한 플래그 및 매개변수는
@anthropic-ai/claude-code 버전에 따라 다를 수 있습니다. 작업에서 claude --help를 실행하여 지원되는 옵션을 확인합니다.Claude의 동작 사용자 정의
두 가지 주요 방법으로 Claude를 안내할 수 있습니다:- CLAUDE.md: 코딩 표준, 보안 요구 사항 및 프로젝트 규칙을 정의합니다. Claude는 실행 중에 이를 읽고 규칙을 따릅니다.
- 사용자 정의 프롬프트: 작업에서
prompt/prompt_file을 통해 작업별 지침을 전달합니다. 다양한 작업에 다양한 프롬프트를 사용합니다(예: 검토, 구현, 리팩터).