Claude Code GitLab CI/CD

​

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

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

​

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

Claude Code использует GitLab CI/CD для выполнения задач ИИ в изолированных заданиях и фиксации результатов обратно через MR:

1. Оркестрация на основе событий: GitLab прослушивает выбранные вами триггеры (например, комментарий, который упоминает @claude в проблеме, MR или потоке обзора). Задание собирает контекст из потока и репозитория, создает подсказки из этого ввода и запускает Claude Code.

2. Абстракция провайдера: Используйте провайдера, который подходит вашей среде:

   • Anthropic API (SaaS)
   • AWS Bedrock (доступ на основе IAM, межрегиональные опции)
   • Google Vertex AI (нативный GCP, Workload Identity Federation)

3. Изолированное выполнение: Каждое взаимодействие выполняется в контейнере со строгими правилами сети и файловой системы. Claude Code обеспечивает разрешения с областью действия рабочего пространства для ограничения записей. Каждое изменение проходит через MR, чтобы рецензенты видели различия, и утверждения по-прежнему применяются.

Выберите региональные конечные точки для уменьшения задержки и соответствия требованиям суверенитета данных при использовании существующих облачных соглашений.

​

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

Claude Code обеспечивает мощные рабочие процессы CI/CD, которые трансформируют то, как вы работаете с кодом:

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

​

Настройка

​

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

Самый быстрый способ начать - добавить минимальное задание в ваш .gitlab-ci.yml и установить ваш API-ключ как замаскированную переменную.

1. Добавьте замаскированную переменную CI/CD

   • Перейдите в Настройки → CI/CD → Переменные
   • Добавьте ANTHROPIC_API_KEY (замаскированную, защищенную по необходимости)

2. Добавьте задание Claude в .gitlab-ci.yml

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # Настройте правила в соответствии с тем, как вы хотите запускать задание:
  # - ручные запуски
  # - события merge request
  # - веб/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

После добавления задания и вашей переменной ANTHROPIC_API_KEY, протестируйте, запустив задание вручную из CI/CD → Пайплайны, или запустите его из MR, чтобы позволить Claude предложить обновления в ветке и открыть MR при необходимости.

​

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

Если вы предпочитаете более контролируемую настройку или нуждаетесь в корпоративных провайдерах:

1. Настройте доступ к провайдеру:

   • Anthropic API: Создайте и сохраните ANTHROPIC_API_KEY как замаскированную переменную CI/CD
   • AWS Bedrock: Настройте GitLab → AWS OIDC и создайте IAM роль для Bedrock
   • Google Vertex AI: Настройте Workload Identity Federation для GitLab → GCP

2. Добавьте учетные данные проекта для операций GitLab API:

   • Используйте CI_JOB_TOKEN по умолчанию, или создайте Project Access Token с областью api
   • Сохраните как GITLAB_ACCESS_TOKEN (замаскированный), если используете PAT

3. Добавьте задание Claude в .gitlab-ci.yml (см. примеры ниже)

4. (Опционально) Включите триггеры на основе упоминаний:

   • Добавьте проектный webhook для “Комментариев (заметок)” к вашему слушателю событий (если вы его используете)
   • Пусть слушатель вызывает API триггера пайплайна с переменными типа AI_FLOW_INPUT и AI_FLOW_CONTEXT, когда комментарий содержит @claude

​

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

​

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

В комментарии к проблеме:

@claude implement this feature based on the issue description

Claude анализирует проблему и кодовую базу, записывает изменения в ветку и открывает MR для обзора.

​

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

В обсуждении MR:

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

Claude предлагает изменения, добавляет код с соответствующим кэшированием и обновляет MR.

​

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

В комментарии к проблеме или MR:

@claude fix the TypeError in the user dashboard component

Claude находит ошибку, реализует исправление и обновляет ветку или открывает новый MR.

​

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

Для корпоративных сред вы можете запускать Claude Code полностью на вашей облачной инфраструктуре с тем же опытом разработчика.

# Для AWS Bedrock:
- AWS_ROLE_TO_ASSUME
- AWS_REGION

# Для AWS Bedrock:
- AWS_ROLE_TO_ASSUME
- AWS_REGION

# Для Google Vertex AI:
- GCP_WORKLOAD_IDENTITY_PROVIDER
- GCP_SERVICE_ACCOUNT
- CLOUD_ML_REGION (например, us-east5)

​

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

Ниже приведены готовые к использованию фрагменты, которые вы можете адаптировать к вашему пайплайну.

​

Базовый .gitlab-ci.yml (Anthropic 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 (рекомендуются минимальные привилегии)

Требуемые переменные CI/CD:

• 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 (Workload Identity Federation)

Предварительные требования:

• API Vertex AI включен в вашем проекте GCP
• Workload Identity Federation настроен для доверия GitLab OIDC
• Сервисный аккаунт с разрешениями Vertex AI

Требуемые переменные CI/CD:

• GCP_WORKLOAD_IDENTITY_PROVIDER: полное имя ресурса провайдера
• GCP_SERVICE_ACCOUNT: email сервисного аккаунта
• 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

Создайте файл CLAUDE.md в корне репозитория для определения стандартов кодирования, критериев обзора и правил, специфичных для проекта. Claude читает этот файл во время выполнения и следует вашим соглашениям при предложении изменений.

​

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

Никогда не фиксируйте API-ключи или облачные учетные данные в вашем репозитории! Всегда используйте переменные GitLab CI/CD:

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

​

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

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

ируемых запусков

• Кэшируйте npm и установки пакетов в runners, где это возможно

​

Затраты CI

При использовании Claude Code с GitLab CI/CD учитывайте связанные затраты:

• Время GitLab Runner:

  • Claude работает на ваших GitLab runners и потребляет вычислительные минуты
  • См. биллинг runner вашего плана GitLab для деталей

• Затраты API:

  • Каждое взаимодействие Claude потребляет токены на основе размера подсказки и ответа
  • Использование токенов варьируется в зависимости от сложности задачи и размера кодовой базы
  • См. ценообразование Anthropic для деталей

• Советы по оптимизации затрат:

  • Используйте специфичные команды @claude для уменьшения ненужных оборотов
  • Установите соответствующие значения max_turns и тайм-аута задания
  • Ограничьте параллелизм для контроля параллельных запусков

​

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

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

​

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

​

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

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

​

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

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

​

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

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

​

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

​

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

Claude Code поддерживает эти часто используемые входные данные:

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

​

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

Вы можете направлять Claude двумя основными способами:

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