Claude Code GitLab CI/CD

Claude Code GitLab CI/CD

GitLab CI/CD와 함께 Claude Code를 개발 워크플로우에 통합하는 방법을 다루는 페이지예요. 이슈 설명이나 댓글만으로 머지 리퀘스트(MR)를 만들 수 있고, 선택한 트리거(예: @claude 멘션이 달린 댓글)에 맞춰 GitLab이 이벤트를 감지해 AI 작업을 격리된 잡으로 실행하고 결과를 MR로 커밋해 줍니다.

출처: 공식문서

본문

GitLab CI/CD용 Claude Code는 현재 베타입니다. 기능과 동작은 경험을 다듬으면서 진화할 수 있습니다.

이 통합은 GitLab이 유지보수합니다. 지원은 다음 GitLab 이슈를 참고하세요.

이 통합은 [Claude Code CLI와 Agent SDK](/docs/en/agent-sdk/overview) 위에 구축되어 CI/CD 잡과 커스텀 자동화 워크플로우에서 Claude를 프로그래매틱하게 사용할 수 있게 합니다.

왜 GitLab과 함께 Claude Code를 쓰나요?

  • 즉시 MR 생성: 필요한 것을 설명하면 Claude가 변경과 설명이 담긴 완전한 MR을 제안
  • 자동화된 구현: 한 번의 명령이나 멘션으로 이슈를 동작하는 코드로 전환
  • 프로젝트 인지: Claude가 CLAUDE.md 가이드라인과 기존 코드 패턴을 따름
  • 간단한 설정: .gitlab-ci.yml에 잡 하나와 마스킹 CI/CD 변수 하나를 추가
  • 엔터프라이즈 준비: Claude API, Amazon Bedrock, Google Cloud's Agent Platform 중 골라 데이터 레지던시와 조달 요구를 충족
  • 기본적으로 안전: 브랜치 보호와 승인 규칙이 있는 GitLab 러너에서 실행

작동 방식 (How it works)

Claude Code는 GitLab CI/CD를 사용해 AI 작업을 격리된 잡에서 실행하고 결과를 MR로 커밋합니다.

  1. 이벤트 주도 조율: GitLab이 선택한 트리거(예: 이슈, MR, 리뷰 스레드에서 @claude를 멘션한 댓글)를 감지합니다. 잡이 스레드와 리포지토리에서 컨텍스트를 수집하고 그 입력으로 프롬프트를 만들어 Claude Code를 실행합니다.
  2. 제공자 추상화: 환경에 맞는 제공자를 쓰세요.
    • Claude API (SaaS)
    • Amazon Bedrock (IAM 기반 접근, 교차 리전 옵션)
    • Google Cloud's Agent Platform (GCP 네이티브, Workload Identity Federation)
  3. 샌드박스 실행: 각 상호작용이 엄격한 네트워크·파일시스템 규칙이 있는 컨테이너에서 실행됩니다. Claude Code가 워크스페이스 범위 권한을 적용해 쓰기를 제한합니다. 모든 변경이 MR을 거치므로 리뷰어가 diff를 보고 승인 규칙도 그대로 적용됩니다.

기존 클라우드 계약을 쓰면서 지역 엔드포인트를 골라 대기 시간을 줄이고 데이터 주권(sovereignty) 요구를 충족할 수 있습니다.

Claude가 무엇을 할 수 있나요?

GitLab 파이프라인에서 Claude Code는 다음을 할 수 있습니다.

  • 이슈 설명이나 댓글에서 MR 생성·업데이트
  • 성능 회귀 분석과 최적화 제안
  • 브랜치에서 직접 기능을 구현한 뒤 MR 열기
  • 테스트나 댓글로 발견된 버그·회귀 수정
  • 후속 댓글에 응답해 요청된 변경을 반복

설정 (Setup)

빠른 설정 (Quick setup)

가장 빠른 시작 방법은 .gitlab-ci.yml에 최소 잡을 추가하고 API 키를 마스킹 변수로 설정하는 것입니다.

  1. 마스킹 CI/CD 변수 추가

    • Settings → CI/CD → Variables로 이동
    • ANTHROPIC_API_KEY 추가 (마스킹, 필요 시 protected)

  2. .gitlab-ci.yml에 Claude 잡 추가

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # Adjust rules to fit how you want to trigger the job:
  # - manual runs
  # - merge request events
  # - web/API triggers when a comment contains '@claude'
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  variables:
    GIT_STRATEGY: fetch
  before_script:
    - apk update
    - apk add --no-cache git curl bash
    - curl -fsSL https://claude.ai/install.sh | bash
    # The installer places claude in ~/.local/bin, which isn't on PATH in this image
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    # Optional: start a GitLab MCP server if your setup provides one
    - /bin/gitlab-mcp-server || true
    # Use AI_FLOW_* variables when invoking via web/API triggers with context payloads
    - echo "$AI_FLOW_INPUT for $AI_FLOW_CONTEXT on $AI_FLOW_EVENT"
    - >
      claude
      -p "${AI_FLOW_INPUT:-'Review this MR and implement the requested changes'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug

잡과 ANTHROPIC_API_KEY 변수를 추가한 뒤, CI/CD → Pipelines에서 잡을 수동으로 실행하거나, MR에서 트리거해 Claude가 브랜치에 업데이트를 제안하고 필요하면 MR을 열게 해 테스트하세요.

Claude API 대신 Amazon Bedrock이나 Google Cloud's Agent Platform에서 실행하려면 인증·환경 설정은 아래 [Amazon Bedrock 및 Google Cloud와 함께 사용](#using-with-amazon-bedrock-and-google-cloud) 섹션을 참고하세요.

수동 설정 (Manual setup, 프로덕션 권장)

더 제어된 설정이나 엔터프라이즈 제공자가 필요하다면:

  1. 제공자 접근 구성:
    • Claude API: ANTHROPIC_API_KEY를 생성해 마스킹 CI/CD 변수로 저장
    • Amazon Bedrock: Configure GitLab → AWS OIDC를 구성하고 Amazon Bedrock용 IAM 역할 생성
    • Google Cloud's Agent Platform: Configure Workload Identity Federation for GitLab → GCP 구성
  2. GitLab API 작업용 프로젝트 자격 증명 추가:
    • 기본적으로 CI_JOB_TOKEN을 사용하거나 api 스코프의 Project Access Token 생성
    • PAT를 쓰면 GITLAB_ACCESS_TOKEN으로 저장 (마스킹)
  3. .gitlab-ci.yml에 Claude 잡 추가: Claude API에는 빠른 설정 잡을, 제공자 잡은 구성 예시에서 사용
  4. (선택) 멘션 기반 트리거 활성화:
    • (쓰고 있다면) 이벤트 리스너에 "Comments (notes)" 프로젝트 웹훅 추가
    • 댓글에 @claude가 포함되면 리스너가 AI_FLOW_INPUT, AI_FLOW_CONTEXT 같은 변수로 파이프라인 트리거 API를 호출하게 함

예시 사용 사례 (Example use cases)

이슈를 MR로 만들기 (Turn issues into MRs)

이슈 댓글에서:

@claude implement this feature based on the issue description

Claude가 이슈와 코드베이스를 분석하고 브랜치에 변경을 작성한 뒤 리뷰용 MR을 엽니다.

구현 도움 받기 (Get implementation help)

MR 토론에서:

@claude suggest a concrete approach to cache the results of this API call

Claude가 변경을 제안하고, 적절한 캐싱 코드를 추가하며 MR을 업데이트합니다.

버그 빠르게 고치기 (Fix bugs quickly)

이슈나 MR 댓글에서:

@claude fix the TypeError in the user dashboard component

Claude가 버그를 찾아 수정을 구현하고 브랜치를 업데이트하거나 새 MR을 엽니다.

Amazon Bedrock 및 Google Cloud와 함께 사용

엔터프라이즈 환경에서는 동일한 개발자 경험으로 클라우드 인프라에서 Claude Code를 완전히 실행할 수 있습니다.

Amazon Bedrock — 사전 요구사항:

  1. 원하는 Claude 모델에 대한 Amazon Bedrock 접근이 있는 AWS 계정
  2. AWS IAM에서 GitLab을 OIDC 아이덴티티 제공자로 구성
  3. Amazon Bedrock 권한이 있고 신뢰 정책이 GitLab 프로젝트/ref로 제한된 IAM 역할
  4. 역할 가정(role assumption)용 GitLab CI/CD 변수:
    • AWS_ROLE_TO_ASSUME (역할 ARN)
    • AWS_REGION (Amazon Bedrock 리전)

설정 지침 — AWS가 GitLab CI 잡이 OIDC를 통해 IAM 역할을 가정하게(정적 키 없이) 구성하세요.

필수 설정:

  1. Amazon Bedrock 활성화 및 대상 Claude 모델 접근 요청
  2. 아직 없으면 GitLab용 IAM OIDC 제공자 생성
  3. GitLab OIDC 제공자가 신뢰하고 프로젝트와 protected ref로 제한된 IAM 역할 생성
  4. Amazon Bedrock invoke API에 대한 최소 권한(least-privilege) 부여

Amazon Bedrock 잡 예시로 잡의 OIDC 토큰을 런타임에 임시 AWS 자격 증명으로 교환하세요.

Google Cloud's Agent Platform — 사전 요구사항:

  1. 다음을 가진 Google Cloud 프로젝트:
    • Google Cloud's Agent Platform API 활성화
    • GitLab OIDC를 신뢰하도록 Workload Identity Federation 구성
  2. 필요한 Google Cloud's Agent Platform 역할만 가진 전용 서비스 계정
  3. GitLab CI/CD 변수:
    • GCP_WORKLOAD_IDENTITY_PROVIDER (//iam.googleapis.com/ 접두사 없는 제공자 리소스 이름. 예: projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider)
    • GCP_SERVICE_ACCOUNT (서비스 계정 이메일)
    • GCP_PROJECT_ID (Google Cloud 프로젝트 ID)

설정 지침 — Google Cloud가 GitLab CI 잡이 Workload Identity Federation으로 서비스 계정을 impersonate하게 구성하세요.

필수 설정:

  1. IAM Credentials API, STS API, Google Cloud's Agent Platform API 활성화
  2. GitLab OIDC용 Workload Identity Pool과 제공자 생성
  3. Google Cloud's Agent Platform 역할을 가진 전용 서비스 계정 생성
  4. WIF 프린시펄에 서비스 계정 impersonate 권한 부여

Agent Platform 잡 예시로 키를 저장하지 않고 인증하세요.

구성 예시 (Configuration examples)

파이프라인에 맞게 조정할 수 있는 바로 쓸 수 있는 스니펫입니다.

Amazon Bedrock 잡 예시 (OIDC)

사전 요구사항:

  • 선택한 Claude 모델에 대한 접근이 활성화된 Amazon Bedrock
  • GitLab 프로젝트와 ref를 신뢰하는 역할로 AWS에 구성된 GitLab OIDC
  • Amazon Bedrock 권한이 있는 IAM 역할 (최소 권한 권장)

필수 CI/CD 변수:

  • AWS_ROLE_TO_ASSUME: Amazon Bedrock 접근용 IAM 역할 ARN
  • AWS_REGION: Amazon Bedrock 리전 (예: us-west-2)

GitLab이 잡의 OIDC 토큰을 id_tokens: 블록에서 발행해 GITLAB_OIDC_TOKEN으로 노출합니다. aud를 AWS의 IAM OIDC 아이덴티티 제공자에서 구성한 수신자 값(예: GitLab 인스턴스 URL)으로 설정하세요.

stages:
  - ai

claude-bedrock:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.example.com
  before_script:
    - apk add --no-cache bash curl jq git aws-cli
    - curl -fsSL https://claude.ai/install.sh | bash
    # The installer places claude in ~/.local/bin, which isn't on PATH in this image
    - export PATH="$HOME/.local/bin:$PATH"
    # Exchange the job's OIDC token for AWS credentials
    - export AWS_WEB_IDENTITY_TOKEN_FILE="/tmp/oidc_token"
    - printf "%s" "$GITLAB_OIDC_TOKEN" > "$AWS_WEB_IDENTITY_TOKEN_FILE"
    - >
      aws sts assume-role-with-web-identity
      --role-arn "$AWS_ROLE_TO_ASSUME"
      --role-session-name "gitlab-claude-$(date +%s)"
      --web-identity-token "file://$AWS_WEB_IDENTITY_TOKEN_FILE"
      --duration-seconds 3600 > /tmp/aws_creds.json
    - export AWS_ACCESS_KEY_ID="$(jq -r .Credentials.AccessKeyId /tmp/aws_creds.json)"
    - export AWS_SECRET_ACCESS_KEY="$(jq -r .Credentials.SecretAccessKey /tmp/aws_creds.json)"
    - export AWS_SESSION_TOKEN="$(jq -r .Credentials.SessionToken /tmp/aws_creds.json)"
  script:
    - /bin/gitlab-mcp-server || true
    - >
      claude
      -p "${AI_FLOW_INPUT:-'Implement the requested changes and open an MR'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug
  variables:
    AWS_REGION: "us-west-2"
    CLAUDE_CODE_USE_BEDROCK: "1"
Amazon Bedrock의 모델 ID에는 리전별 접두사가 포함됩니다(예: `us.anthropic.claude-sonnet-4-6`). 워크플로우가 지원하면 잡 구성이나 프롬프트로 원하는 모델을 전달하세요.

Agent Platform 잡 예시 (Workload Identity Federation)

사전 요구사항:

  • GCP 프로젝트에서 Google Cloud's Agent Platform API 활성화
  • GitLab OIDC를 신뢰하도록 Workload Identity Federation 구성
  • Google Cloud's Agent Platform 권한이 있는 서비스 계정

필수 CI/CD 변수:

  • GCP_WORKLOAD_IDENTITY_PROVIDER: //iam.googleapis.com/ 접두사 없는 제공자 리소스 이름. 예: projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider
  • GCP_SERVICE_ACCOUNT: 서비스 계정 이메일
  • GCP_PROJECT_ID: Google Cloud 프로젝트 ID
  • CLOUD_ML_REGION: Google Cloud's Agent Platform 리전 (예: us-east5)

GitLab이 잡의 OIDC 토큰을 id_tokens: 블록에서 발행해 GITLAB_OIDC_TOKEN으로 노출합니다. aud를 Workload Identity Pool 제공자에서 구성한 수신자 값(예: GitLab 인스턴스 URL)으로 설정하세요. 잡이 토큰을 파일에 쓰고, 자격 증명 구성의 credential_source 항목이 Google 인증 라이브러리가 그 파일에서 읽게 합니다. GOOGLE_APPLICATION_CREDENTIALS를 자격 증명 구성 파일로 설정하면 Application Default Credentials를 통해 Claude Code가 쓸 수 있게 됩니다.

stages:
  - ai

claude-vertex:
  stage: ai
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.example.com
  before_script:
    - apt-get update && apt-get install -y git && apt-get clean
    - curl -fsSL https://claude.ai/install.sh | bash
    # The installer places claude in ~/.local/bin, which isn't on PATH in this image
    - export PATH="$HOME/.local/bin:$PATH"
    # Write the job's OIDC token where credential_source expects it
    - printf "%s" "$GITLAB_OIDC_TOKEN" > /tmp/oidc_token
    # Write the WIF credential configuration to a file (no downloaded keys)
    - |
      cat > /tmp/cred.json <<EOF
      {
        "type": "external_account",
        "audience": "//iam.googleapis.com/${GCP_WORKLOAD_IDENTITY_PROVIDER}",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "token_url": "https://sts.googleapis.com/v1/token",
        "credential_source": {
          "file": "/tmp/oidc_token"
        },
        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${GCP_SERVICE_ACCOUNT}:generateAccessToken"
      }
      EOF
    # Expose the credentials to Claude Code via Application Default Credentials
    - export GOOGLE_APPLICATION_CREDENTIALS=/tmp/cred.json
    # Authenticate the gcloud CLI with the same credential configuration
    - gcloud auth login --cred-file=/tmp/cred.json
    - gcloud config set project "$GCP_PROJECT_ID"
  script:
    - /bin/gitlab-mcp-server || true
    - >
      CLOUD_ML_REGION="${CLOUD_ML_REGION:-us-east5}"
      claude
      -p "${AI_FLOW_INPUT:-'Review and update code as requested'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug
  variables:
    CLOUD_ML_REGION: "us-east5"
    CLAUDE_CODE_USE_VERTEX: "1"
    ANTHROPIC_VERTEX_PROJECT_ID: "$GCP_PROJECT_ID"
Workload Identity Federation을 쓰면 서비스 계정 키를 저장할 필요가 없습니다. 리포지토리별 신뢰 조건과 최소 권한 서비스 계정을 사용하세요.

모범 사례 (Best practices)

CLAUDE.md 구성 (CLAUDE.md configuration)

리포지토리 루트에 CLAUDE.md 파일을 만들어 코딩 표준, 리뷰 기준, 프로젝트별 규칙을 정의하세요. Claude는 실행 중 이 파일을 읽고 변경을 제안할 때 규칙을 따릅니다.

보안 고려 사항 (Security considerations)

API 키나 클라우드 자격 증명을 리포지토리에 커밋하지 마세요. 항상 GitLab CI/CD 변수를 사용하세요.

  • ANTHROPIC_API_KEY를 마스킹 변수로 추가 (필요 시 protect)
  • 가능하면 제공자별 OIDC 사용 (장기 키 없음)
  • 잡 권한과 네트워크 이그레스 제한
  • 다른 기여자처럼 Claude의 MR을 검토

성능 최적화 (Optimizing performance)

  • CLAUDE.md를 집중되고 간결하게 유지
  • 반복을 줄이도록 명확한 이슈·MR 설명 제공
  • 가능하면 러너에서 npm·패키지 설치 캐시

CI 비용 (CI costs)

GitLab CI/CD에서 Claude Code를 쓸 때 관련 비용을 알고 있어야 합니다.

  • GitLab Runner 시간:
    • Claude가 GitLab 러너에서 실행되며 컴퓨팅 분(minutes)을 소비
    • 상세는 GitLab 플랜의 러너 결제 참고
  • API 비용:
    • 각 Claude 상호작용이 프롬프트·응답 크기에 따라 토큰을 소비
    • 토큰 사용량은 작업 복잡도와 코드베이스 크기에 따라 다름
    • 상세는 Anthropic 가격 참고
  • 비용 최적화 팁:
    • 불필요한 턴을 줄이도록 구체적인 @claude 명령 사용
    • 적절한 --max-turns와 잡 timeout 값 설정
    • 병렬 실행 제어를 위해 동시성 제한

문제 해결 (Troubleshooting)

Claude가 @claude 명령에 응답하지 않음

  • 파이프라인이 트리거되고 있는지 확인 (수동, MR 이벤트, 또는 note 이벤트 리스너·웹훅)
  • ANTHROPIC_API_KEY 또는 클라우드 제공자 변수가 있는지 확인
  • 댓글에 @claude(가 아니라 /claude)가 있고 멘션 트리거가 구성됐는지 확인

잡이 댓글을 쓰거나 MR을 열 수 없음

  • CI_JOB_TOKEN이 프로젝트에 충분한 권한이 있는지, 또는 api 스코프의 Project Access Token을 쓰는지 확인
  • --allowedTools에 mcp__gitlab 도구가 활성화됐는지 확인
  • 잡이 MR 컨텍스트에서 실행되는지, 또는 AI_FLOW_* 변수로 충분한 컨텍스트가 있는지 확인

인증 오류 (Authentication errors)

  • Claude API: ANTHROPIC_API_KEY가 유효하고 만료되지 않았는지 확인
  • Amazon Bedrock 또는 Google Cloud's Agent Platform: OIDC/WIF 구성, 역할 impersonation, 시크릿 이름을 확인하고 리전·모델 가용성을 확인

고급 구성 (Advanced configuration)

공통 파라미터와 변수 (Common parameters and variables)

잡에서 Claude Code 실행을 이 CLI 플래그·GitLab 키워드·변수로 제어하세요.

  • -p: 인라인 지시 제공. 예: claude -p "Review this MR"
  • --max-turns: 왕복 반복 횟수 제한
  • timeout: GitLab의 잡 수준 timeout 키워드로 총 잡 실행 시간 제한. 예: timeout: 30m
  • ANTHROPIC_API_KEY: Claude API에 필요 (Amazon Bedrock이나 Google Cloud's Agent Platform에선 사용 안 함)
  • 제공자별 환경: AWS_REGION, Google Cloud's Agent Platform의 프로젝트/리전 변수
정확한 플래그·파라미터는 `@anthropic-ai/claude-code` 버전에 따라 다를 수 있습니다. 잡에서 `claude --help`를 실행해 지원되는 옵션을 확인하세요.

Claude 동작 커스터마이징 (Customizing Claude's behavior)

Claude를 안내하는 두 가지 주요 방법:

  1. CLAUDE.md: 코딩 표준, 보안 요구사항, 프로젝트 규칙 정의. Claude가 실행 중 읽고 규칙을 따릅니다.
  2. 커스텀 프롬프트: 잡에서 -p로 작업별 지시를 전달. 잡마다 다른 프롬프트 사용 (예: 리뷰, 구현, 리팩터링).