Claude Code GitLab CI/CD

​

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

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

​

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

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

​

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

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

​

Настройка

​

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

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

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # Отрегулируйте правила в соответствии с тем, как вы хотите запустить задание:
  # - ручные запуски
  # - события запроса слияния
  # - веб/API триггеры, когда комментарий содержит '@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
    - npm install -g @anthropic-ai/claude-code
  script:
    # Опционально: запустите сервер GitLab MCP, если ваша настройка его предоставляет
    - /bin/gitlab-mcp-server || true
    # Используйте переменные AI_FLOW_* при вызове через веб/API триггеры с полезными нагрузками контекста
    - 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

​

Ручная настройка (рекомендуется для производства)

1. Настройте доступ поставщика:
   • Claude API: Создайте и сохраните ANTHROPIC_API_KEY как замаскированную переменную CI/CD
   • AWS Bedrock: Настройте GitLab → AWS OIDC и создайте роль IAM для Bedrock
   • Google Vertex AI: Настройте Федерацию удостоверений рабочей нагрузки для GitLab → GCP
2. Добавьте учетные данные проекта для операций GitLab API:
   • Используйте CI_JOB_TOKEN по умолчанию или создайте Project Access Token с областью api
   • Сохраните как GITLAB_ACCESS_TOKEN (замаскирована), если используете PAT
3. Добавьте задание Claude в .gitlab-ci.yml (см. примеры ниже)
4. (Опционально) Включите триггеры, управляемые упоминаниями:
   • Добавьте вебхук проекта для “Comments (notes)” к вашему прослушивателю событий (если вы его используете)
   • Попросите прослушиватель вызвать API триггера конвейера с переменными, такими как 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

​

Использование с AWS Bedrock и Google Vertex AI

# Для AWS Bedrock:
- AWS_ROLE_TO_ASSUME
- AWS_REGION

​

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

​

Базовый .gitlab-ci.yml (Claude API)

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  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
    - npm install -g @anthropic-ai/claude-code
  script:
    - /bin/gitlab-mcp-server || true
    - >
      claude
      -p "${AI_FLOW_INPUT:-'Summarize recent changes and suggest improvements'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug
  # Claude Code будет использовать ANTHROPIC_API_KEY из переменных CI/CD

​

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

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

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

claude-bedrock:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  before_script:
    - apk add --no-cache bash curl jq git python3 py3-pip
    - pip install --no-cache-dir awscli
    - npm install -g @anthropic-ai/claude-code
    # Обменяйте токен GitLab OIDC на учетные данные AWS
    - export AWS_WEB_IDENTITY_TOKEN_FILE="${CI_JOB_JWT_FILE:-/tmp/oidc_token}"
    - if [ -n "${CI_JOB_JWT_V2}" ]; then printf "%s" "$CI_JOB_JWT_V2" > "$AWS_WEB_IDENTITY_TOKEN_FILE"; fi
    - >
      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"

​

Пример задания Google Vertex AI (Федерация удостоверений рабочей нагрузки)

• API Vertex AI включен в вашем проекте GCP
• Федерация удостоверений рабочей нагрузки настроена для доверия GitLab OIDC
• Учетная запись службы с разрешениями Vertex AI

• GCP_WORKLOAD_IDENTITY_PROVIDER: Полное имя ресурса поставщика
• GCP_SERVICE_ACCOUNT: Адрес электронной почты учетной записи службы
• CLOUD_ML_REGION: Регион Vertex (например, us-east5)

claude-vertex:
  stage: ai
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  before_script:
    - apt-get update && apt-get install -y git nodejs npm && apt-get clean
    - npm install -g @anthropic-ai/claude-code
    # Аутентифицируйтесь в Google Cloud через WIF (без загруженных ключей)
    - >
      gcloud auth login --cred-file=<(cat <<EOF
      {
        "type": "external_account",
        "audience": "${GCP_WORKLOAD_IDENTITY_PROVIDER}",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${GCP_SERVICE_ACCOUNT}:generateAccessToken",
        "token_url": "https://sts.googleapis.com/v1/token"
      }
      EOF
      )
    - gcloud config set project "$(gcloud projects list --format='value(projectId)' --filter="name:${CI_PROJECT_NAMESPACE}" | head -n1)" || true
  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.md

​

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

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

​

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

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

​

Затраты на CI

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

​

Безопасность и управление

• Каждое задание выполняется в изолированном контейнере с ограниченным доступом в сеть
• Изменения Claude проходят через MR, чтобы рецензенты видели каждый diff
• Защита ветвей и правила одобрения применяются к коду, созданному ИИ
• Claude Code использует разрешения с областью действия рабочего пространства для ограничения записей
• Затраты остаются под вашим контролем, потому что вы приносите свои собственные учетные данные поставщика

​

Устранение неполадок

​

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

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

​

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

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

​

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

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

​

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

​

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

• prompt / prompt_file: Предоставьте инструкции встроенно (-p) или через файл
• max_turns: Ограничьте количество туров туда-сюда
• timeout_minutes: Ограничьте общее время выполнения
• ANTHROPIC_API_KEY: Требуется для Claude API (не используется для Bedrock/Vertex)
• Окружение, специфичное для поставщика: AWS_REGION, переменные проекта/региона для Vertex

​

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

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