Claude Code GitLab CI/CD

​

Почему использовать Claude Code с GitLab?

• Мгновенное создание MR: Опишите, что вам нужно, и Claude предложит полный MR с изменениями и объяснением
• Автоматизированная реализация: Превратите проблемы в рабочий код с помощью одной команды или упоминания
• Осведомленность о проекте: Claude следует вашим рекомендациям CLAUDE.md и существующим шаблонам кода
• Простая настройка: Добавьте одно задание в .gitlab-ci.yml и замаскированную переменную CI/CD
• Готово для предприятия: Выберите Claude API, Amazon Bedrock или Google Cloud’s Agent Platform для соответствия требованиям к месторасположению данных и закупкам
• Безопасно по умолчанию: Работает на ваших GitLab runners с вашей защитой ветвей и утверждениями

​

Как это работает

1. Оркестровка, управляемая событиями: GitLab прослушивает выбранные вами триггеры (например, комментарий, упоминающий @claude в проблеме, MR или потоке рецензирования). Задание собирает контекст из потока и репозитория, создает подсказки из этого ввода и запускает Claude Code.
2. Абстракция поставщика: Используйте поставщика, который подходит для вашей среды:
   • Claude API (SaaS)
   • Amazon Bedrock (доступ на основе IAM, опции между регионами)
   • Google Cloud’s Agent Platform (собственный GCP, Workload Identity Federation)
3. Изолированное выполнение: Каждое взаимодействие выполняется в контейнере со строгими правилами сети и файловой системы. Claude Code обеспечивает разрешения с областью действия рабочего пространства для ограничения записей. Каждое изменение проходит через MR, чтобы рецензенты видели diff и применялись утверждения.

​

Что может делать Claude?

• Создавать и обновлять MR на основе описаний проблем или комментариев
• Анализировать регрессии производительности и предлагать оптимизации
• Реализовывать функции непосредственно в ветке, а затем открывать MR
• Исправлять ошибки и регрессии, выявленные тестами или комментариями
• Отвечать на последующие комментарии для итерации по запрошенным изменениям

​

Настройка

​

Быстрая настройка

1. Добавьте замаскированную переменную CI/CD
   • Перейдите в Settings → CI/CD → Variables
   • Добавьте ANTHROPIC_API_KEY (замаскирована, защищена при необходимости)
2. Добавьте задание Claude в .gitlab-ci.yml

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

​

Ручная настройка (рекомендуется для production)

1. Настройте доступ к поставщику услуг:
   • Claude API: Создайте и сохраните ANTHROPIC_API_KEY как замаскированную переменную CI/CD
   • Amazon Bedrock: Configure GitLab → AWS OIDC и создайте роль IAM для Amazon Bedrock
   • Google Cloud’s Agent Platform: Configure Workload Identity Federation for GitLab → GCP
2. Добавьте учетные данные проекта для операций GitLab API:
   • Используйте CI_JOB_TOKEN по умолчанию или создайте Project Access Token с областью api
   • Сохраните как GITLAB_ACCESS_TOKEN (замаскирована), если используете PAT
3. Добавьте задание Claude в .gitlab-ci.yml: используйте задание Quick setup для Claude API или задание поставщика услуг из Configuration examples
4. (Опционально) Включите триггеры, управляемые упоминаниями:
   • Добавьте webhook проекта для “Comments (notes)” к вашему обработчику событий (если вы его используете)
   • Пусть обработчик вызывает API триггера pipeline с переменными, такими как AI_FLOW_INPUT и AI_FLOW_CONTEXT, когда комментарий содержит @claude

​

Примеры использования

​

Преобразование проблем в MR

@claude implement this feature based on the issue description

​

Получение помощи с реализацией

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

​

Быстрое исправление ошибок

@claude fix the TypeError in the user dashboard component

​

Использование с Amazon Bedrock и Google Cloud

​

Примеры конфигурации

​

Пример задания Amazon Bedrock (OIDC)

• Amazon Bedrock включен с доступом к выбранной модели Claude
• GitLab OIDC настроен в AWS с ролью, которая доверяет вашему проекту GitLab и refs
• Роль IAM с разрешениями Amazon Bedrock (рекомендуется принцип наименьших привилегий)

• AWS_ROLE_TO_ASSUME: ARN роли IAM для доступа к Amazon Bedrock
• AWS_REGION: регион Amazon Bedrock (например, us-west-2)

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"

​

Пример задания Agent Platform (Workload Identity Federation)

• API Agent Platform Google Cloud включен в вашем проекте GCP
• Workload Identity Federation настроена для доверия GitLab OIDC
• Учетная запись сервиса с разрешениями Google Cloud Agent Platform

• 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
• CLOUD_ML_REGION: регион Google Cloud Agent Platform (например, us-east5)

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"

​

Лучшие практики

​

Конфигурация CLAUDE.md

​

Соображения безопасности

• Добавьте ANTHROPIC_API_KEY как замаскированную переменную (и защитите её при необходимости)
• Используйте OIDC, специфичный для поставщика, где это возможно (без долгоживущих ключей)
• Ограничьте разрешения заданий и исходящий сетевой трафик
• Проверяйте MR Claude как любого другого участника

​

Оптимизация производительности

• Держите CLAUDE.md сосредоточенным и кратким
• Предоставляйте четкие описания проблем/MR для сокращения итераций
• Кэшируйте установки npm и пакетов в runners где это возможно

​

Затраты на CI

• Время GitLab Runner:
  • Claude работает на ваших GitLab runners и потребляет минуты вычислений
  • Подробнее см. в информации о биллинге runner вашего плана GitLab
• Затраты на API:
  • Каждое взаимодействие Claude потребляет токены на основе размера запроса и ответа
  • Использование токенов варьируется в зависимости от сложности задачи и размера кодовой базы
  • Подробнее см. в ценообразовании Anthropic
• Советы по оптимизации затрат:
  • Используйте специфичные команды @claude для сокращения ненужных ходов
  • Установите подходящие значения --max-turns и timeout задания
  • Ограничьте параллелизм для контроля параллельных запусков

​

Troubleshooting

​

Claude не отвечает на команды @claude

• Убедитесь, что ваш pipeline запускается (вручную, событием MR или через слушатель событий note/webhook)
• Убедитесь, что переменные ANTHROPIC_API_KEY или переменные облачного провайдера присутствуют
• Проверьте, что комментарий содержит @claude (не /claude) и что ваш триггер упоминания настроен

​

Задание не может писать комментарии или открывать MR

• Убедитесь, что CI_JOB_TOKEN имеет достаточные разрешения для проекта, или используйте Project Access Token с областью api
• Проверьте, что инструмент mcp__gitlab включен в --allowedTools
• Подтвердите, что задание выполняется в контексте MR или имеет достаточный контекст через переменные AI_FLOW_*

​

Ошибки аутентификации

• Для Claude API: Подтвердите, что ANTHROPIC_API_KEY действителен и не истек
• Для Amazon Bedrock или Agent Platform Google Cloud: Проверьте конфигурацию OIDC/WIF, олицетворение роли и имена секретов; подтвердите доступность региона и модели

​

Расширенная конфигурация

​

Общие параметры и переменные

• -p: предоставьте инструкции встроенным образом, например claude -p "Review this MR"
• --max-turns: ограничьте количество итераций туда и обратно
• timeout: ограничьте общее время выполнения задания с помощью ключевого слова timeout на уровне задания GitLab, например timeout: 30m
• ANTHROPIC_API_KEY: требуется для Claude API (не используется для Amazon Bedrock или Google Cloud’s Agent Platform)
• Специфичная для провайдера среда: AWS_REGION, переменные проекта/региона для Google Cloud’s Agent Platform

​

Настройка поведения Claude

1. CLAUDE.md: определите стандарты кодирования, требования безопасности и соглашения проекта. Claude читает это во время запусков и следует вашим правилам.
2. Пользовательские подсказки: передайте инструкции, специфичные для задачи, через -p в задании. Используйте разные подсказки для разных заданий (например, review, implement, refactor).