Claude Code GitLab CI/CD

Aprenda a integrar Claude Code en su flujo de trabajo de desarrollo con GitLab CI/CD

¿Por qué usar Claude Code con GitLab?

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

Cómo funciona

Claude Code utiliza GitLab CI/CD para ejecutar tareas de IA en trabajos aislados y confirmar resultados a través de MRs:

Orquestación impulsada por eventos: GitLab escucha los desencadenantes elegidos (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.
Abstracción de proveedores: Utilice el proveedor que se ajuste a su entorno:
- Claude API (SaaS)
- Amazon Bedrock (acceso basado en IAM, opciones entre regiones)
- Google Vertex AI (nativo de GCP, Federación de Identidad de Carga de Trabajo)
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 con alcance 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.

Elija puntos finales regionales para reducir la latencia y cumplir con los requisitos de soberanía de datos mientras utiliza acuerdos en la nube existentes.

¿Qué puede hacer Claude?

Claude Code habilita flujos de trabajo de CI/CD poderosos que transforman la forma en que trabaja con código:

Crear y actualizar MRs a partir de descripciones o comentarios de problemas
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

La forma más rápida de comenzar es agregar un trabajo mínimo a su .gitlab-ci.yml y establecer su clave de API como una variable enmascarada.

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

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # Ajuste las reglas para que se adapten a cómo desea desencadenar el trabajo:
  # - ejecuciones manuales
  # - eventos de solicitud de fusión
  # - desencadenadores 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
    - curl -fsSL https://claude.ai/install.sh | bash
  script:
    # Opcional: inicie un servidor MCP de GitLab si su configuración proporciona uno
    - /bin/gitlab-mcp-server || true
    # Utilice variables AI_FLOW_* cuando invoque a través de desencadenadores 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

Después de agregar el trabajo y su variable ANTHROPIC_API_KEY, pruebe ejecutando el trabajo manualmente desde CI/CD → Pipelines, o desencadénelo desde un MR para permitir que Claude proponga actualizaciones en una rama y abra un MR si es necesario.

Configuración manual (recomendada para producción)

Si prefiere una configuración más controlada o necesita proveedores empresariales:

Configure el acceso del proveedor:
- Claude API: Cree y almacene ANTHROPIC_API_KEY como una variable de CI/CD enmascarada
- Amazon Bedrock: Configure GitLab → AWS OIDC y cree un rol de IAM para Bedrock
- Google Vertex AI: Configure la Federación de Identidad de Carga de Trabajo para GitLab → GCP
Agregue credenciales de proyecto para operaciones de API de GitLab:
- Utilice CI_JOB_TOKEN de forma predeterminada, o cree un Token de Acceso de Proyecto con alcance api
- Almacene como GITLAB_ACCESS_TOKEN (enmascarado) si utiliza un PAT
Agregue el trabajo de Claude a .gitlab-ci.yml (consulte los ejemplos a continuación)
(Opcional) Habilite desencadenadores impulsados por menciones:
- Agregue un webhook de proyecto para "Comentarios (notas)" a su escucha de eventos (si utiliza uno)
- Haga que el escucha llame a la API de desencadenador de canalización con variables como AI_FLOW_INPUT y AI_FLOW_CONTEXT cuando un comentario contiene @claude

Casos de uso de ejemplo

Convertir problemas en MRs

En un comentario de problema:

@claude implement this feature based on the issue description

Claude analiza el problema y la base de código, escribe cambios en una rama y abre un MR para revisión.

Obtener ayuda de implementación

En una discusión de MR:

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

Claude propone cambios, agrega código con almacenamiento en caché apropiado y actualiza el MR.

Corregir errores rápidamente

En un comentario de problema o MR:

@claude fix the TypeError in the user dashboard component

Claude localiza el error, implementa una corrección y actualiza la rama o abre un nuevo MR.

Usar con Amazon Bedrock y Google Vertex AI

Para entornos empresariales, puede ejecutar Claude Code completamente en su infraestructura en la nube con la misma experiencia de desarrollador.

Requisitos previos

Antes de configurar Claude Code con Amazon Bedrock, necesita:

Una cuenta de AWS con acceso a Amazon Bedrock para los modelos Claude deseados
GitLab configurado como proveedor de identidad OIDC en AWS IAM
Un rol de IAM con permisos de Bedrock y una política de confianza restringida a su proyecto/referencias de GitLab
Variables de CI/CD de GitLab para asumir el rol:

AWS_ROLE_TO_ASSUME (ARN del rol)
AWS_REGION (región de Bedrock)

Instrucciones de configuración

Configure AWS para permitir que los trabajos de CI de GitLab asuman un rol de IAM a través de OIDC (sin claves estáticas).

Configuración requerida:

Habilite Amazon Bedrock y solicite acceso a sus modelos Claude objetivo
Cree un proveedor OIDC de IAM para GitLab si aún no está presente
Cree un rol de IAM confiado por el proveedor OIDC de GitLab, restringido a su proyecto y referencias protegidas
Adjunte permisos de menor privilegio para las API de invocación de Bedrock

Valores requeridos para almacenar en variables de CI/CD:

AWS_ROLE_TO_ASSUME
AWS_REGION

Agregue variables en Configuración → CI/CD → Variables:

# Para Amazon Bedrock:
- AWS_ROLE_TO_ASSUME
- AWS_REGION

Utilice el ejemplo de trabajo de Amazon Bedrock anterior para intercambiar el token de trabajo de GitLab por credenciales temporales de AWS en tiempo de ejecución.

Requisitos previos

Antes de configurar Claude Code con Google Vertex AI, necesita:

Un proyecto de Google Cloud con:

API de Vertex AI habilitada
Federación de Identidad de Carga de Trabajo configurada para confiar en OIDC de GitLab

Una cuenta de servicio dedicada con solo los roles de Vertex AI requeridos
Variables de CI/CD de GitLab para WIF:

GCP_WORKLOAD_IDENTITY_PROVIDER (nombre de recurso completo)
GCP_SERVICE_ACCOUNT (correo electrónico de la cuenta de servicio)

Instrucciones de configuración

Configure Google Cloud para permitir que los trabajos de CI de GitLab suplanten una cuenta de servicio a través de la Federación de Identidad de Carga de Trabajo.

Configuración requerida:

Habilite la API de Credenciales de IAM, la API de STS y la API de Vertex AI
Cree un Grupo de Identidad de Carga de Trabajo y un proveedor para OIDC de GitLab
Cree una cuenta de servicio dedicada con roles de Vertex AI
Otorgue al principal de WIF permiso para suplantar la cuenta de servicio

Valores requeridos para almacenar en variables de CI/CD:

GCP_WORKLOAD_IDENTITY_PROVIDER
GCP_SERVICE_ACCOUNT

Agregue variables en Configuración → CI/CD → Variables:

# Para Google Vertex AI:
- GCP_WORKLOAD_IDENTITY_PROVIDER
- GCP_SERVICE_ACCOUNT
- CLOUD_ML_REGION (por ejemplo, us-east5)

Utilice el ejemplo de trabajo de Google Vertex AI anterior para autenticarse sin almacenar claves.

Ejemplos de configuración

A continuación se muestran fragmentos listos para usar que puede adaptar a su canalizació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
    - curl -fsSL https://claude.ai/install.sh | bash
  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 Amazon Bedrock (OIDC)

Requisitos previos:

Amazon Bedrock habilitado con acceso a su modelo Claude elegido
OIDC de GitLab configurado en AWS con un rol que confía en su proyecto y referencias de GitLab
Rol de IAM con permisos de Bedrock (se recomienda menor privilegio)

Variables de CI/CD requeridas:

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
    - curl -fsSL https://claude.ai/install.sh | bash
    # Intercambie 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)

Requisitos previos:

API de Vertex AI habilitada en su 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

Variables de CI/CD requeridas:

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 && apt-get clean
    - curl -fsSL https://claude.ai/install.sh | bash
    # Autentíquese 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

Cree un archivo CLAUDE.md en la raíz del repositorio para definir estándares de codificación, criterios de revisión y reglas específicas del proyecto. Claude lee este archivo durante las ejecuciones y sigue sus convenciones al proponer cambios.

Consideraciones de seguridad

Nunca confirme claves de API o credenciales en la nube en su repositorio. Siempre utilice variables de CI/CD de GitLab:

Agregue ANTHROPIC_API_KEY como una variable enmascarada (y protéjala si es necesario)
Utilice OIDC específico del proveedor donde sea posible (sin claves de larga duración)
Limite los permisos de trabajo y la salida de red
Revise los MRs de Claude como cualquier otro colaborador

Optimización del rendimiento

Mantenga CLAUDE.md enfocado y conciso
Proporcione descripciones claras de problemas/MR para reducir iteraciones
Configure tiempos de espera de trabajo sensatos para evitar ejecuciones descontroladas
Almacene en caché npm e instalaciones de paquetes en ejecutores donde sea posible

Costos de CI

Cuando utiliza Claude Code con GitLab CI/CD, tenga en cuenta los costos asociados:

Tiempo de ejecución de GitLab:
- Claude se ejecuta en sus ejecutores de GitLab y consume minutos de cálculo
- Consulte la facturación de ejecutores de su plan de GitLab para obtener detalles
Costos de API:
- Cada interacción de Claude consume tokens según el tamaño de la indicación y la respuesta
- El uso de tokens varía según la complejidad de la tarea y el tamaño de la base de código
- Consulte Precios de Anthropic para obtener detalles
Consejos de optimización de costos:
- Utilice comandos específicos de @claude para reducir turnos innecesarios
- Establezca valores apropiados de max_turns y tiempo de espera de trabajo
- Limite 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 con alcance de espacio de trabajo para restringir escrituras
Los costos permanecen bajo su control porque usted proporciona sus propias credenciales de proveedor

Solución de problemas

Claude no responde a comandos @claude

Verifique que su canalización se esté desencadenando (manualmente, evento de MR o a través de un escucha de eventos de nota/webhook)
Asegúrese de que las variables de CI/CD (ANTHROPIC_API_KEY o configuración del proveedor en la nube) estén presentes y no enmascaradas
Compruebe que el comentario contiene @claude (no /claude) y que su desencadenador de mención está configurado

El trabajo no puede escribir comentarios ni abrir MRs

Asegúrese de que CI_JOB_TOKEN tenga permisos suficientes para el proyecto, o utilice un Token de Acceso de Proyecto con alcance api
Compruebe que la herramienta mcp__gitlab esté habilitada en --allowedTools
Confirme 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: Confirme que ANTHROPIC_API_KEY es válida y no ha expirado
Para Bedrock/Vertex: Verifique la configuración de OIDC/WIF, la suplantación de rol y los nombres secretos; confirme la disponibilidad de región y modelo

Configuración avanzada

Parámetros y variables comunes

Claude Code admite estas entradas comúnmente utilizadas:

prompt / prompt_file: Proporcione instrucciones en línea (-p) o a través de un archivo
max_turns: Limite el número de iteraciones de ida y vuelta
timeout_minutes: Limite 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

Puede guiar a Claude de dos formas principales:

CLAUDE.md: Defina estándares de codificación, requisitos de seguridad y convenciones de proyecto. Claude lee esto durante las ejecuciones y sigue sus reglas.
Indicaciones personalizadas: Pase instrucciones específicas de tareas a través de prompt/prompt_file en el trabajo. Utilice diferentes indicaciones para diferentes trabajos (por ejemplo, revisión, implementación, refactorización).

gitlab-ci-cd.md +85 −29

16 Esta integración se basa en el [Claude Code CLI y Agent SDK](/es/agent-sdk/overview), lo que permite el uso programático de Claude en sus trabajos de CI/CD y flujos de trabajo de automatización personalizados.16 Esta integración se basa en el [Claude Code CLI y Agent SDK](/es/agent-sdk/overview), lo que permite el uso programático de Claude en sus trabajos de CI/CD y flujos de trabajo de automatización personalizados.

17</Note>17</Note>

18 18

~~19## ¿Por qué usar Claude Code con GitLab?~~19<h2 id="why-use-claude-code-with-gitlab">

20 ¿Por qué usar Claude Code con GitLab?

21</h2>

20 22

21* **Creación instantánea de MR**: Describa lo que necesita, y Claude propone un MR completo con cambios y explicación23* **Creación instantánea de MR**: Describa lo que necesita, y Claude propone un MR completo con cambios y explicación

22* **Implementación automatizada**: Convierta problemas en código funcional con un único comando o mención24* **Implementación automatizada**: Convierta problemas en código funcional con un único comando o mención

25* **Listo para empresas**: Elija Claude API, Amazon Bedrock o Google Vertex AI para cumplir con los requisitos de residencia de datos y adquisición27* **Listo para empresas**: Elija Claude API, Amazon Bedrock o Google Vertex AI para cumplir con los requisitos de residencia de datos y adquisición

26* **Seguro por defecto**: Se ejecuta en sus ejecutores de GitLab con su protección de rama y aprobaciones28* **Seguro por defecto**: Se ejecuta en sus ejecutores de GitLab con su protección de rama y aprobaciones

27 29

~~28## Cómo funciona~~30<h2 id="how-it-works">

31 Cómo funciona

32</h2>

29 33

30Claude Code utiliza GitLab CI/CD para ejecutar tareas de IA en trabajos aislados y confirmar resultados a través de MRs:34Claude Code utiliza GitLab CI/CD para ejecutar tareas de IA en trabajos aislados y confirmar resultados a través de MRs:

31 35

40 44

41Elija puntos finales regionales para reducir la latencia y cumplir con los requisitos de soberanía de datos mientras utiliza acuerdos en la nube existentes.45Elija puntos finales regionales para reducir la latencia y cumplir con los requisitos de soberanía de datos mientras utiliza acuerdos en la nube existentes.

42 46

~~43## ¿Qué puede hacer Claude?~~47<h2 id="what-can-claude-do">

48 ¿Qué puede hacer Claude?

49</h2>

44 50

45Claude Code habilita flujos de trabajo de CI/CD poderosos que transforman la forma en que trabaja con código:51Claude Code habilita flujos de trabajo de CI/CD poderosos que transforman la forma en que trabaja con código:

46 52

50* Corregir errores y regresiones identificados por pruebas o comentarios56* Corregir errores y regresiones identificados por pruebas o comentarios

51* Responder a comentarios de seguimiento para iterar sobre cambios solicitados57* Responder a comentarios de seguimiento para iterar sobre cambios solicitados

52 58

~~53## Configuración~~59<h2 id="setup">

60 Configuración

61</h2>

54 62

~~55### Configuración rápida~~63<h3 id="quick-setup">

64 Configuración rápida

65</h3>

56 66

57La forma más rápida de comenzar es agregar un trabajo mínimo a su `.gitlab-ci.yml` y establecer su clave de API como una variable enmascarada.67La forma más rápida de comenzar es agregar un trabajo mínimo a su `.gitlab-ci.yml` y establecer su clave de API como una variable enmascarada.

58 68

98Después de agregar el trabajo y su variable `ANTHROPIC_API_KEY`, pruebe ejecutando el trabajo manualmente desde **CI/CD** → **Pipelines**, o desencadénelo desde un MR para permitir que Claude proponga actualizaciones en una rama y abra un MR si es necesario.108Después de agregar el trabajo y su variable `ANTHROPIC_API_KEY`, pruebe ejecutando el trabajo manualmente desde **CI/CD** → **Pipelines**, o desencadénelo desde un MR para permitir que Claude proponga actualizaciones en una rama y abra un MR si es necesario.

99 109

100<Note>110<Note>

101 Para ejecutar en Amazon Bedrock o Google Vertex AI en lugar de Claude API, consulte la sección [Usar con Amazon Bedrock y Google Vertex AI](#using-with-amazon-bedrock--google-vertex-ai) a continuación para obtener instrucciones de autenticación y configuración del entorno.111 Para ejecutar en Amazon Bedrock o Google Vertex AI en lugar de Claude API, consulte la sección [Usar con Amazon Bedrock y Google Vertex AI](#using-with-amazon-bedrock-%26-google-vertex-ai) a continuación para obtener instrucciones de autenticación y configuración del entorno.

102</Note>112</Note>

103 113

104### Configuración manual (recomendada para producción)114<h3 id="manual-setup-recommended-for-production">

115 Configuración manual (recomendada para producción)

116</h3>

105 117

106Si prefiere una configuración más controlada o necesita proveedores empresariales:118Si prefiere una configuración más controlada o necesita proveedores empresariales:

107 119

120 * Agregue un webhook de proyecto para "Comentarios (notas)" a su escucha de eventos (si utiliza uno)132 * Agregue un webhook de proyecto para "Comentarios (notas)" a su escucha de eventos (si utiliza uno)

121 * Haga que el escucha llame a la API de desencadenador de canalización con variables como `AI_FLOW_INPUT` y `AI_FLOW_CONTEXT` cuando un comentario contiene `@claude`133 * Haga que el escucha llame a la API de desencadenador de canalización con variables como `AI_FLOW_INPUT` y `AI_FLOW_CONTEXT` cuando un comentario contiene `@claude`

122 134

123## Casos de uso de ejemplo135<h2 id="example-use-cases">

136 Casos de uso de ejemplo

137</h2>

124 138

125### Convertir problemas en MRs139<h3 id="turn-issues-into-mrs">

140 Convertir problemas en MRs

141</h3>

126 142

127En un comentario de problema:143En un comentario de problema:

128 144

132 148

133Claude analiza el problema y la base de código, escribe cambios en una rama y abre un MR para revisión.149Claude analiza el problema y la base de código, escribe cambios en una rama y abre un MR para revisión.

134 150

135### Obtener ayuda de implementación151<h3 id="get-implementation-help">

152 Obtener ayuda de implementación

153</h3>

136 154

137En una discusión de MR:155En una discusión de MR:

138 156

142 160

143Claude propone cambios, agrega código con almacenamiento en caché apropiado y actualiza el MR.161Claude propone cambios, agrega código con almacenamiento en caché apropiado y actualiza el MR.

144 162

145### Corregir errores rápidamente163<h3 id="fix-bugs-quickly">

164 Corregir errores rápidamente

165</h3>

146 166

147En un comentario de problema o MR:167En un comentario de problema o MR:

148 168

152 172

153Claude localiza el error, implementa una corrección y actualiza la rama o abre un nuevo MR.173Claude localiza el error, implementa una corrección y actualiza la rama o abre un nuevo MR.

154 174

155## Usar con Amazon Bedrock y Google Vertex AI175<h2 id="using-with-amazon-bedrock--google-vertex-ai">

176 Usar con Amazon Bedrock y Google Vertex AI

177</h2>

156 178

157Para entornos empresariales, puede ejecutar Claude Code completamente en su infraestructura en la nube con la misma experiencia de desarrollador.179Para entornos empresariales, puede ejecutar Claude Code completamente en su infraestructura en la nube con la misma experiencia de desarrollador.

158 180

238 </Tab>260 </Tab>

239</Tabs>261</Tabs>

240 262

241## Ejemplos de configuración263<h2 id="configuration-examples">

264 Ejemplos de configuración

265</h2>

242 266

243A continuación se muestran fragmentos listos para usar que puede adaptar a su canalización.267A continuación se muestran fragmentos listos para usar que puede adaptar a su canalización.

244 268

245### .gitlab-ci.yml básico (Claude API)269<h3 id="basic-gitlab-ci-yml-claude-api">

270 .gitlab-ci.yml básico (Claude API)

271</h3>

246 272

247```yaml theme={null}273```yaml theme={null}

248stages:274stages:

271 # Claude Code utilizará ANTHROPIC_API_KEY de las variables de CI/CD297 # Claude Code utilizará ANTHROPIC_API_KEY de las variables de CI/CD

272```298```

273 299

274### Ejemplo de trabajo de Amazon Bedrock (OIDC)300<h3 id="amazon-bedrock-job-example-oidc">

301 Ejemplo de trabajo de Amazon Bedrock (OIDC)

302</h3>

275 303

276**Requisitos previos:**304**Requisitos previos:**

277 305

322 Los ID de modelo para Bedrock incluyen prefijos específicos de región (por ejemplo, `us.anthropic.claude-sonnet-4-6`). Pase el modelo deseado a través de su configuración de trabajo o indicación si su flujo de trabajo lo admite.350 Los ID de modelo para Bedrock incluyen prefijos específicos de región (por ejemplo, `us.anthropic.claude-sonnet-4-6`). Pase el modelo deseado a través de su configuración de trabajo o indicación si su flujo de trabajo lo admite.

323</Note>351</Note>

324 352

325### Ejemplo de trabajo de Google Vertex AI (Federación de Identidad de Carga de Trabajo)353<h3 id="google-vertex-ai-job-example-workload-identity-federation">

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

355</h3>

326 356

327**Requisitos previos:**357**Requisitos previos:**

328 358

375 Con la Federación de Identidad de Carga de Trabajo, no necesita almacenar claves de cuenta de servicio. Utilice condiciones de confianza específicas del repositorio y cuentas de servicio con menor privilegio.405 Con la Federación de Identidad de Carga de Trabajo, no necesita almacenar claves de cuenta de servicio. Utilice condiciones de confianza específicas del repositorio y cuentas de servicio con menor privilegio.

376</Note>406</Note>

377 407

378## Mejores prácticas408<h2 id="best-practices">

409 Mejores prácticas

410</h2>

379 411

380### Configuración de CLAUDE.md412<h3 id="claude-md-configuration">

413 Configuración de CLAUDE.md

414</h3>

381 415

382Cree un archivo `CLAUDE.md` en la raíz del repositorio para definir estándares de codificación, criterios de revisión y reglas específicas del proyecto. Claude lee este archivo durante las ejecuciones y sigue sus convenciones al proponer cambios.416Cree un archivo `CLAUDE.md` en la raíz del repositorio para definir estándares de codificación, criterios de revisión y reglas específicas del proyecto. Claude lee este archivo durante las ejecuciones y sigue sus convenciones al proponer cambios.

383 417

384### Consideraciones de seguridad418<h3 id="security-considerations">

419 Consideraciones de seguridad

420</h3>

385 421

386**Nunca confirme claves de API o credenciales en la nube en su repositorio**. Siempre utilice variables de CI/CD de GitLab:422**Nunca confirme claves de API o credenciales en la nube en su repositorio**. Siempre utilice variables de CI/CD de GitLab:

387 423

390* Limite los permisos de trabajo y la salida de red426* Limite los permisos de trabajo y la salida de red

391* Revise los MRs de Claude como cualquier otro colaborador427* Revise los MRs de Claude como cualquier otro colaborador

392 428

393### Optimización del rendimiento429<h3 id="optimizing-performance">

430 Optimización del rendimiento

431</h3>

394 432

395* Mantenga `CLAUDE.md` enfocado y conciso433* Mantenga `CLAUDE.md` enfocado y conciso

396* Proporcione descripciones claras de problemas/MR para reducir iteraciones434* Proporcione descripciones claras de problemas/MR para reducir iteraciones

397* Configure tiempos de espera de trabajo sensatos para evitar ejecuciones descontroladas435* Configure tiempos de espera de trabajo sensatos para evitar ejecuciones descontroladas

398* Almacene en caché npm e instalaciones de paquetes en ejecutores donde sea posible436* Almacene en caché npm e instalaciones de paquetes en ejecutores donde sea posible

399 437

400### Costos de CI438<h3 id="ci-costs">

439 Costos de CI

440</h3>

401 441

402Cuando utiliza Claude Code con GitLab CI/CD, tenga en cuenta los costos asociados:442Cuando utiliza Claude Code con GitLab CI/CD, tenga en cuenta los costos asociados:

403 443

415 * Establezca valores apropiados de `max_turns` y tiempo de espera de trabajo455 * Establezca valores apropiados de `max_turns` y tiempo de espera de trabajo

416 * Limite la concurrencia para controlar ejecuciones paralelas456 * Limite la concurrencia para controlar ejecuciones paralelas

417 457

418## Seguridad y gobernanza458<h2 id="security-and-governance">

459 Seguridad y gobernanza

460</h2>

419 461

420* Cada trabajo se ejecuta en un contenedor aislado con acceso de red restringido462* Cada trabajo se ejecuta en un contenedor aislado con acceso de red restringido

421* Los cambios de Claude fluyen a través de MRs para que los revisores vean cada diff463* Los cambios de Claude fluyen a través de MRs para que los revisores vean cada diff

423* Claude Code utiliza permisos con alcance de espacio de trabajo para restringir escrituras465* Claude Code utiliza permisos con alcance de espacio de trabajo para restringir escrituras

424* Los costos permanecen bajo su control porque usted proporciona sus propias credenciales de proveedor466* Los costos permanecen bajo su control porque usted proporciona sus propias credenciales de proveedor

425 467

426## Solución de problemas468<h2 id="troubleshooting">

469 Solución de problemas

470</h2>

427 471

428### Claude no responde a comandos @claude472<h3 id="claude-not-responding-to-claude-commands">

473 Claude no responde a comandos @claude

474</h3>

429 475

430* Verifique que su canalización se esté desencadenando (manualmente, evento de MR o a través de un escucha de eventos de nota/webhook)476* Verifique que su canalización se esté desencadenando (manualmente, evento de MR o a través de un escucha de eventos de nota/webhook)

431* Asegúrese de que las variables de CI/CD (`ANTHROPIC_API_KEY` o configuración del proveedor en la nube) estén presentes y no enmascaradas477* Asegúrese de que las variables de CI/CD (`ANTHROPIC_API_KEY` o configuración del proveedor en la nube) estén presentes y no enmascaradas

432* Compruebe que el comentario contiene `@claude` (no `/claude`) y que su desencadenador de mención está configurado478* Compruebe que el comentario contiene `@claude` (no `/claude`) y que su desencadenador de mención está configurado

433 479

434### El trabajo no puede escribir comentarios ni abrir MRs480<h3 id="job-can’t-write-comments-or-open-mrs">

481 El trabajo no puede escribir comentarios ni abrir MRs

482</h3>

435 483

436* Asegúrese de que `CI_JOB_TOKEN` tenga permisos suficientes para el proyecto, o utilice un Token de Acceso de Proyecto con alcance `api`484* Asegúrese de que `CI_JOB_TOKEN` tenga permisos suficientes para el proyecto, o utilice un Token de Acceso de Proyecto con alcance `api`

437* Compruebe que la herramienta `mcp__gitlab` esté habilitada en `--allowedTools`485* Compruebe que la herramienta `mcp__gitlab` esté habilitada en `--allowedTools`

438* Confirme que el trabajo se ejecuta en el contexto del MR o tiene suficiente contexto a través de variables `AI_FLOW_*`486* Confirme que el trabajo se ejecuta en el contexto del MR o tiene suficiente contexto a través de variables `AI_FLOW_*`

439 487

440### Errores de autenticación488<h3 id="authentication-errors">

489 Errores de autenticación

490</h3>

441 491

442* **Para Claude API**: Confirme que `ANTHROPIC_API_KEY` es válida y no ha expirado492* **Para Claude API**: Confirme que `ANTHROPIC_API_KEY` es válida y no ha expirado

443* **Para Bedrock/Vertex**: Verifique la configuración de OIDC/WIF, la suplantación de rol y los nombres secretos; confirme la disponibilidad de región y modelo493* **Para Bedrock/Vertex**: Verifique la configuración de OIDC/WIF, la suplantación de rol y los nombres secretos; confirme la disponibilidad de región y modelo

444 494

445## Configuración avanzada495<h2 id="advanced-configuration">

496 Configuración avanzada

497</h2>

446 498

447### Parámetros y variables comunes499<h3 id="common-parameters-and-variables">

500 Parámetros y variables comunes

501</h3>

448 502

449Claude Code admite estas entradas comúnmente utilizadas:503Claude Code admite estas entradas comúnmente utilizadas:

450 504

458 Las banderas y parámetros exactos pueden variar según la versión de `@anthropic-ai/claude-code`. Ejecute `claude --help` en su trabajo para ver las opciones admitidas.512 Las banderas y parámetros exactos pueden variar según la versión de `@anthropic-ai/claude-code`. Ejecute `claude --help` en su trabajo para ver las opciones admitidas.

459</Note>513</Note>

460 514

461### Personalización del comportamiento de Claude515<h3 id="customizing-claude’s-behavior">

516 Personalización del comportamiento de Claude

517</h3>

462 518

463Puede guiar a Claude de dos formas principales:519Puede guiar a Claude de dos formas principales:

464 520

gitlab-ci-cd.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

Claude Code GitLab CI/CD

¿Por qué usar Claude Code con GitLab?

Cómo funciona

¿Qué puede hacer Claude?

Configuración

Configuración rápida

Configuración manual (recomendada para producción)

Casos de uso de ejemplo

Convertir problemas en MRs

Obtener ayuda de implementación

Corregir errores rápidamente

Usar con Amazon Bedrock y Google Vertex AI

Requisitos previos

Instrucciones de configuración

Requisitos previos

Instrucciones de configuración

Ejemplos de configuración

.gitlab-ci.yml básico (Claude API)

Ejemplo de trabajo de Amazon Bedrock (OIDC)

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

Mejores prácticas

Configuración de CLAUDE.md

Consideraciones de seguridad

Optimización del rendimiento

Costos de CI

Seguridad y gobernanza

Solución de problemas

Claude no responde a comandos @claude

El trabajo no puede escribir comentarios ni abrir MRs

Errores de autenticación

Configuración avanzada

Parámetros y variables comunes

Personalización del comportamiento de Claude