Claude Code GitLab CI/CD

​

¿Por qué usar Claude Code con GitLab?

• Creación instantánea de MR: Describe lo que necesitas y Claude propone un MR completo con cambios y explicación
• Implementación automatizada: Convierte problemas en código funcional con un único comando o mención
• Consciente del proyecto: Claude sigue tus directrices de CLAUDE.md y patrones de código existentes
• Configuración simple: Agrega un trabajo a .gitlab-ci.yml y una variable de CI/CD enmascarada
• Listo para empresas: Elige Claude API, AWS Bedrock o Google Vertex AI para cumplir con requisitos de residencia de datos y adquisición
• Seguro por defecto: Se ejecuta en tus ejecutores de GitLab con tu protección de rama y aprobaciones

​

Cómo funciona

1. Orquestación impulsada por eventos: GitLab escucha los disparadores que elijas (por ejemplo, un comentario que menciona @claude en un problema, MR o hilo de revisión). El trabajo recopila contexto del hilo y repositorio, construye indicaciones a partir de esa entrada y ejecuta Claude Code.
2. Abstracción de proveedores: Utiliza el proveedor que se ajuste a tu entorno:
   • Claude API (SaaS)
   • AWS Bedrock (acceso basado en IAM, opciones entre regiones)
   • Google Vertex AI (nativo de GCP, Federación de Identidad de Carga de Trabajo)
3. Ejecución en sandbox: Cada interacción se ejecuta en un contenedor con reglas estrictas de red y sistema de archivos. Claude Code aplica permisos de ámbito de espacio de trabajo para restringir escrituras. Cada cambio fluye a través de un MR para que los revisores vean el diff y las aprobaciones sigan siendo aplicables.

​

¿Qué puede hacer Claude?

• Crear y actualizar MRs a partir de descripciones de problemas o comentarios
• Analizar regresiones de rendimiento y proponer optimizaciones
• Implementar características directamente en una rama, luego abrir un MR
• Corregir errores y regresiones identificados por pruebas o comentarios
• Responder a comentarios de seguimiento para iterar sobre cambios solicitados

​

Configuración

​

Configuración rápida

1. Agrega una variable de CI/CD enmascarada
   • Ve a Configuración → CI/CD → Variables
   • Agrega ANTHROPIC_API_KEY (enmascarada, protegida según sea necesario)
2. Agrega un trabajo de Claude a .gitlab-ci.yml

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # Ajusta las reglas para que se adapten a cómo deseas disparar el trabajo:
  # - ejecuciones manuales
  # - eventos de solicitud de fusión
  # - disparadores web/API cuando un comentario contiene '@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:
    # Opcional: inicia un servidor GitLab MCP si tu configuración proporciona uno
    - /bin/gitlab-mcp-server || true
    # Utiliza variables AI_FLOW_* cuando se invoca a través de disparadores web/API con cargas de contexto
    - 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

​

Configuración manual (recomendada para producción)

1. Configura el acceso del proveedor:
   • Claude API: Crea y almacena ANTHROPIC_API_KEY como una variable de CI/CD enmascarada
   • AWS Bedrock: Configura GitLab → AWS OIDC y crea un rol de IAM para Bedrock
   • Google Vertex AI: Configura Federación de Identidad de Carga de Trabajo para GitLab → GCP
2. Agrega credenciales de proyecto para operaciones de API de GitLab:
   • Utiliza CI_JOB_TOKEN por defecto, o crea un Token de Acceso de Proyecto con alcance api
   • Almacena como GITLAB_ACCESS_TOKEN (enmascarado) si utilizas un PAT
3. Agrega el trabajo de Claude a .gitlab-ci.yml (consulta los ejemplos a continuación)
4. (Opcional) Habilita disparadores impulsados por menciones:
   • Agrega un webhook de proyecto para “Comentarios (notas)” a tu escuchador de eventos (si utilizas uno)
   • Haz que el escuchador llame a la API de disparo de pipeline con variables como AI_FLOW_INPUT y AI_FLOW_CONTEXT cuando un comentario contiene @claude

​

Casos de uso de ejemplo

​

Convierte problemas en MRs

@claude implement this feature based on the issue description

​

Obtén ayuda de implementación

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

​

Corrige errores rápidamente

@claude fix the TypeError in the user dashboard component

​

Usar con AWS Bedrock y Google Vertex AI

# Para AWS Bedrock:
- AWS_ROLE_TO_ASSUME
- AWS_REGION

​

Ejemplos de configuración

​

.gitlab-ci.yml básico (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 utilizará ANTHROPIC_API_KEY de las variables de CI/CD

​

Ejemplo de trabajo de AWS Bedrock (OIDC)

• Amazon Bedrock habilitado con acceso a tus modelos Claude elegidos
• OIDC de GitLab configurado en AWS con un rol que confía en tu proyecto y refs de GitLab
• Rol de IAM con permisos de Bedrock (se recomienda menor privilegio)

• AWS_ROLE_TO_ASSUME: ARN del rol de IAM para acceso a Bedrock
• AWS_REGION: Región de Bedrock (por ejemplo, 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
    # Intercambia el token OIDC de GitLab por credenciales de 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"

​

Ejemplo de trabajo de Google Vertex AI (Federación de Identidad de Carga de Trabajo)

• API de Vertex AI habilitada en tu proyecto de GCP
• Federación de Identidad de Carga de Trabajo configurada para confiar en OIDC de GitLab
• Una cuenta de servicio con permisos de Vertex AI

• GCP_WORKLOAD_IDENTITY_PROVIDER: Nombre de recurso completo del proveedor
• GCP_SERVICE_ACCOUNT: Correo electrónico de la cuenta de servicio
• CLOUD_ML_REGION: Región de Vertex (por ejemplo, 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
    # Autentica en Google Cloud a través de WIF (sin claves descargadas)
    - >
      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"

​

Mejores prácticas

​

Configuración de CLAUDE.md

​

Consideraciones de seguridad

• Agrega ANTHROPIC_API_KEY como una variable enmascarada (y protégela si es necesario)
• Utiliza OIDC específico del proveedor donde sea posible (sin claves de larga duración)
• Limita los permisos del trabajo y la salida de red
• Revisa los MRs de Claude como cualquier otro colaborador

​

Optimización del rendimiento

• Mantén CLAUDE.md enfocado y conciso
• Proporciona descripciones claras de problemas/MR para reducir iteraciones
• Configura tiempos de espera de trabajo sensatos para evitar ejecuciones descontroladas
• Almacena en caché las instalaciones de npm y paquetes en ejecutores donde sea posible

​

Costos de CI

• Tiempo del ejecutor de GitLab:
  • Claude se ejecuta en tus ejecutores de GitLab y consume minutos de computación
  • Consulta la facturación del ejecutor de tu plan de GitLab para obtener detalles
• Costos de API:
  • Cada interacción de Claude consume tokens basados en el tamaño de la indicación y respuesta
  • El uso de tokens varía según la complejidad de la tarea y el tamaño de la base de código
  • Consulta Precios de Anthropic para obtener detalles
• Consejos de optimización de costos:
  • Utiliza comandos específicos de @claude para reducir turnos innecesarios
  • Establece valores apropiados de max_turns y tiempo de espera del trabajo
  • Limita la concurrencia para controlar ejecuciones paralelas

​

Seguridad y gobernanza

• Cada trabajo se ejecuta en un contenedor aislado con acceso de red restringido
• Los cambios de Claude fluyen a través de MRs para que los revisores vean cada diff
• Las reglas de protección de rama y aprobación se aplican al código generado por IA
• Claude Code utiliza permisos de ámbito de espacio de trabajo para restringir escrituras
• Los costos permanecen bajo tu control porque traes tus propias credenciales de proveedor

​

Solución de problemas

​

Claude no responde a comandos @claude

• Verifica que tu pipeline se esté disparando (manualmente, evento de MR o a través de un escuchador de eventos de nota/webhook)
• Asegúrate de que las variables de CI/CD (ANTHROPIC_API_KEY o configuración del proveedor de nube) estén presentes y sin enmascarar
• Comprueba que el comentario contiene @claude (no /claude) y que tu disparador de mención está configurado

​

El trabajo no puede escribir comentarios o abrir MRs

• Asegúrate de que CI_JOB_TOKEN tenga permisos suficientes para el proyecto, o utiliza un Token de Acceso de Proyecto con alcance api
• Comprueba que la herramienta mcp__gitlab esté habilitada en --allowedTools
• Confirma que el trabajo se ejecuta en el contexto del MR o tiene suficiente contexto a través de variables AI_FLOW_*

​

Errores de autenticación

• Para Claude API: Confirma que ANTHROPIC_API_KEY sea válida y no haya expirado
• Para Bedrock/Vertex: Verifica la configuración de OIDC/WIF, suplantación de rol y nombres de secretos; confirma la disponibilidad de región y modelo

​

Configuración avanzada

​

Parámetros y variables comunes

• prompt / prompt_file: Proporciona instrucciones en línea (-p) o a través de un archivo
• max_turns: Limita el número de iteraciones de ida y vuelta
• timeout_minutes: Limita el tiempo total de ejecución
• ANTHROPIC_API_KEY: Requerido para Claude API (no se utiliza para Bedrock/Vertex)
• Entorno específico del proveedor: AWS_REGION, variables de proyecto/región para Vertex

​

Personalización del comportamiento de Claude

1. CLAUDE.md: Define estándares de codificación, requisitos de seguridad y convenciones del proyecto. Claude lee esto durante las ejecuciones y sigue tus reglas.
2. Indicaciones personalizadas: Pasa instrucciones específicas de la tarea a través de prompt/prompt_file en el trabajo. Utiliza diferentes indicaciones para diferentes trabajos (por ejemplo, revisión, implementación, refactorización).