Uso en CI/CD

Documentación para desarrolladores

Para la referencia técnica completa, consulta docs/ci-cd.md en el repositorio.

gitlab-mcp-server puede ejecutarse dentro de jobs CI/CD como cualquier otra herramienta CLI. Hay dos modos de uso disponibles:

Modo	LLM Necesario	Caso de uso	Determinismo
Determinista (JSON-RPC)	No	Operaciones scriptadas: listar issues, publicar comentarios, crear releases	✅ Totalmente determinista
Con LLM (cliente MCP headless)	Sí	Flujos inteligentes: revisión de código, triaje de issues, análisis de MRs	❌ No determinista

Ambos modos se autentican con un Personal Access Token (PAT) o Project Access Token. Los despliegues Enterprise/Premium con un token de scope api tienen acceso a toda la superficie de herramientas. Los despliegues GitLab.com tienen acceso al conjunto principal de herramientas más las herramientas adicionales específicas de Orbit.

sequenceDiagram
    participant CI as Job CI/CD
    participant MCP as MCP Server (stdio)
    participant GL as API de GitLab

    CI->>MCP: initialize (JSON-RPC vía stdin)
    MCP-->>CI: capabilities (vía stdout)
    CI->>MCP: notifications/initialized
    CI->>MCP: tools/call {tool, arguments}
    MCP->>GL: REST API v4 / GraphQL
    GL-->>MCP: Respuesta JSON
    MCP-->>CI: CallToolResult (vía stdout)
    CI->>CI: Parsear resultado con jq

Requisitos previos

1. Descarga el binario desde GitHub Releases:

   curl -sSL "https://github.com/jmrplens/gitlab-mcp-server/releases/latest/download/gitlab-mcp-server-linux-amd64" \
     -o gitlab-mcp-server
   chmod +x gitlab-mcp-server

2. Crea un Project Access Token con scope api (recomendado sobre PATs personales para CI).

3. Almacena el token como variable CI/CD enmascarada llamada MCP_PAT.

Modo 1: Determinista (Sin LLM)

Envía mensajes JSON-RPC directamente al servidor a través de stdio. Totalmente determinista — sin LLM ni API externa necesaria.

Cómo funciona

El servidor se comunica a través del protocolo MCP sobre stdin/stdout usando JSON-RPC 2.0. Cada interacción requiere un handshake initialize, una notificación initialized, y luego una o más solicitudes tools/call.

Ejemplo en GitLab CI

.gitlab-ci.yml

mcp-list-issues:
  stage: test
  image: alpine:latest
  variables:
    GITLAB_URL: ${CI_SERVER_URL}
    GITLAB_TOKEN: ${MCP_PAT}
  before_script:
    - apk add --no-cache curl jq
    - curl -sSL "https://github.com/jmrplens/gitlab-mcp-server/releases/latest/download/gitlab-mcp-server-linux-amd64"
      -o gitlab-mcp-server
    - chmod +x gitlab-mcp-server
  script:
    - |
      RESULT=$({
        echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"ci","version":"1.0"}},"id":1}'
        echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
        echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"gitlab_list_issues","arguments":{"project_id":"'"${CI_PROJECT_ID}"'","state":"opened","per_page":5}},"id":2}'
      } | ./gitlab-mcp-server 2>/dev/null | jq -s '.[1].result.content[0].text')
    - echo "${RESULT}"

Función auxiliar

Para pipelines con muchas llamadas, envuelve el protocolo en una función reutilizable:

mcp_call() {
  local tool="$1"
  local args="$2"
  {
    echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"ci","version":"1.0"}},"id":1}'
    echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
    echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"'"${tool}"'","arguments":'"${args}"'},"id":2}'
  } | ./gitlab-mcp-server 2>/dev/null | jq -s '.[1].result.content[0].text' -r
}

# Uso
ISSUES=$(mcp_call "gitlab_list_issues" '{"project_id":"'"${CI_PROJECT_ID}"'","state":"opened"}')

Modo 2: Con LLM (Cliente MCP headless)

Usa un cliente MCP headless para que un LLM seleccione y orqueste las herramientas. Ideal para flujos inteligentes como revisión de código, triaje de issues y generación de notas de release.

Cliente recomendado: IBM mcp-cli

IBM mcp-cli soporta modo comando para flujos automatizados con LLM, con proveedores OpenAI, Anthropic, Azure, Gemini, Groq y Ollama local.

GitLab CI: revisión automática de MRs

.gitlab-ci.yml

auto-review:
  stage: review
  image: python:3.12-slim
  variables:
    GITLAB_URL: ${CI_SERVER_URL}
    GITLAB_TOKEN: ${MCP_PAT}
    OPENAI_API_KEY: ${OPENAI_KEY}
  before_script:
    - apt-get update && apt-get install -y curl
    - curl -sSL "https://github.com/jmrplens/gitlab-mcp-server/releases/latest/download/gitlab-mcp-server-linux-amd64"
      -o gitlab-mcp-server
    - chmod +x gitlab-mcp-server
    - pip install --quiet mcp-cli
  script:
    - |
      cat > server_config.json << 'EOF'
      {
        "mcpServers": {
          "gitlab": {
            "command": "./gitlab-mcp-server",
            "env": {
              "GITLAB_URL": "${GITLAB_URL}",
              "GITLAB_TOKEN": "${GITLAB_TOKEN}"
            }
          }
        }
      }
      EOF
    - |
      mcp-cli cmd \
        --config-file server_config.json \
        --server gitlab \
        --provider openai \
        --model gpt-4o \
        --prompt "Revisa el merge request !${CI_MERGE_REQUEST_IID} en el proyecto ${CI_PROJECT_ID}. Comprueba calidad de código, problemas de seguridad y tests faltantes. Publica tu revisión como nota en el MR." \
        --raw
  rules:
    - if: $CI_MERGE_REQUEST_IID

Usar un LLM local (Ollama)

Para pipelines que no pueden usar APIs de LLM externas, ejecuta Ollama como servicio CI:

local-llm-review:
  stage: review
  image: python:3.12-slim
  services:
    - name: ollama/ollama:latest
      alias: ollama
  variables:
    GITLAB_URL: ${CI_SERVER_URL}
    GITLAB_TOKEN: ${MCP_PAT}
    OLLAMA_HOST: http://ollama:11434
  before_script:
    - apt-get update && apt-get install -y --no-install-recommends curl
    - curl -sSL "https://github.com/jmrplens/gitlab-mcp-server/releases/latest/download/gitlab-mcp-server-linux-amd64"
      -o gitlab-mcp-server
    - chmod +x gitlab-mcp-server
    - pip install --quiet mcp-cli
    - curl -s "${OLLAMA_HOST}/api/pull" -d '{"name":"qwen2.5-coder:7b"}'
  script:
    - |
      cat > server_config.json << 'EOF'
      {
        "mcpServers": {
          "gitlab": {
            "command": "./gitlab-mcp-server",
            "env": {
              "GITLAB_URL": "${GITLAB_URL}",
              "GITLAB_TOKEN": "${GITLAB_TOKEN}"
            }
          }
        }
      }
      EOF
    - |
      mcp-cli cmd \
        --config-file server_config.json \
        --server gitlab \
        --provider ollama \
        --model qwen2.5-coder:7b \
        --prompt "Resume los últimos 5 merge requests del proyecto ${CI_PROJECT_ID}." \
        --raw

Transporte HTTP en CI

Para pipelines con muchas llamadas a herramientas, el transporte HTTP evita la sobrecarga de inicio de proceso por llamada:

http-mode-pipeline:
  script:
    # Iniciar servidor HTTP en segundo plano
    - ./gitlab-mcp-server --http --gitlab-url="${CI_SERVER_URL}" --http-addr=127.0.0.1:8080 &
    - sleep 2
    # Llamar herramientas vía HTTP
    - |
      curl -s -X POST http://127.0.0.1:8080/mcp \
        -H "Content-Type: application/json" \
        -H "PRIVATE-TOKEN: ${MCP_PAT}" \
        -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"gitlab_list_issues","arguments":{"project_id":"'"${CI_PROJECT_ID}"'","state":"opened"}},"id":2}' \
        | jq '.result.content[0].text'

Consulta Servidor HTTP para detalles completos.

Herramientas CI/CD disponibles

Más allá de ejecutar el servidor en pipelines, GitLab MCP Server proporciona herramientas completas de gestión CI/CD que los asistentes de IA pueden usar interactivamente. Están disponibles mediante la superficie dinámica find/execute predeterminada y mediante meta-herramientas explícitas con TOOL_SURFACE=meta.

Pipelines

La meta-herramienta gitlab_pipeline gestiona el ciclo de vida completo de los pipelines:

Acción	Descripción
list	Listar pipelines con filtrado por estado, ref
get	Obtener detalles y estado del pipeline
create	Disparar un nuevo pipeline con variables
cancel	Cancelar un pipeline en ejecución
retry	Reintentar un pipeline fallido
delete	Eliminar un pipeline
variables	Listar variables del pipeline
test_report	Obtener el informe de tests de un pipeline
wait	Esperar a la finalización del pipeline con polling
schedule_*	CRUD de programaciones (list, get, create, edit, delete, run, take_ownership)
schedule_*_variable	CRUD de variables de programación (list_variables, create_variable, edit_variable, delete_variable)
trigger_*	Gestión de tokens de trigger (list, get, create, update, delete)

Esperar pipeline

La acción wait consulta un pipeline hasta que alcanza un estado terminal (success, failed, canceled). Esto es especialmente útil en scripts CI que necesitan bloquearse hasta que un pipeline disparado termine.

Jobs

La meta-herramienta gitlab_job proporciona gestión completa de jobs:

Acción	Descripción
list	Listar jobs de un pipeline
get	Obtener detalles del job
play	Ejecutar un job manual
cancel	Cancelar un job en ejecución
retry	Reintentar un job fallido
trace	Obtener la salida del log del job
artifacts	Listar artefactos del job
download_artifact	Descargar un artefacto específico
delete_artifacts	Eliminar artefactos del job
wait	Esperar a la finalización del job con polling

Configuración CI/CD

Meta-herramienta	Acciones	Descripción
gitlab_template	lint, lint_project	Validar sintaxis de .gitlab-ci.yml
gitlab_ci_variable	list, get, create, update, delete	Gestionar variables CI/CD
gitlab_environment	list, get, create, update, delete, stop, deployment_*	Gestionar entornos y despliegues

Ejemplo: pipeline con variables

Disparar un pipeline con variables personalizadas usando JSON-RPC:

{
  "tool": "gitlab_pipeline",
  "arguments": {
    "action": "create",
    "project": "my-group/my-project",
    "ref": "main",
    "variables": [
      { "key": "DEPLOY_ENV", "value": "staging", "variable_type": "env_var" },
      { "key": "CONFIG", "value": "...", "variable_type": "file" }
    ]
  }
}

Para la referencia completa de herramientas, consulta Resumen de herramientas.

Mejores prácticas de seguridad

Práctica	Recomendación
Tipo de token	Project Access Token — limitado a un proyecto, auditable
Scope	api para acceso completo, read_api para flujos de solo lectura
Expiración	Máximo 90 días, rotar antes de que expire
Almacenamiento	Variable CI/CD enmascarada — nunca commitear al repositorio
Multi-proyecto	Usar Group Access Tokens para flujos entre proyectos

Solución de problemas

Error	Solución
not found / permiso denegado	Verifica que el binario se descargó para la plataforma correcta, ejecuta chmod +x
401 Unauthorized	Comprueba que la variable MCP_PAT está configurada y el token no ha expirado
x509: certificate signed by unknown authority	Configura GITLAB_SKIP_TLS_VERIFY=true
Timeout en respuestas grandes	Añade argumento per_page para limitar resultados
Errores de proveedor en mcp-cli	Verifica las variables de API key, prueba pip install --upgrade mcp-cli

Preguntas frecuentes

¿Puedo usar gitlab-mcp-server en CI/CD sin un LLM?

Sí. El modo determinista envía mensajes JSON-RPC 2.0 directamente al servidor por stdio, sin LLM ni API externa. Cada interacción realiza un handshake initialize, envía un mensaje notifications/initialized y luego emite una o más solicitudes tools/call, y el resultado se parsea con jq. Este modo es totalmente determinista, lo que lo hace ideal para operaciones scriptadas como listar issues, publicar comentarios o crear releases.

¿Qué tipo de token de GitLab debería usar en pipelines CI/CD?

Usa un Project Access Token limitado a un solo proyecto y almacénalo como variable CI/CD enmascarada, nunca commiteada al repositorio. Elige el scope api para acceso completo o read_api para flujos de solo lectura, define una expiración máxima de 90 días y rota el token antes de que expire. Para flujos que abarcan varios proyectos, usa un Group Access Token.

¿Cómo bloqueo un script CI hasta que un pipeline de GitLab termine?

Llama a la meta-herramienta gitlab_pipeline con la acción wait. Consulta el pipeline hasta que alcanza un estado terminal (success, failed o canceled), lo que permite que un script CI se bloquee hasta que un pipeline disparado termine. La meta-herramienta gitlab_job ofrece una acción wait equivalente para jobs individuales.

¿Debería usar transporte stdio o HTTP en CI?

Usa stdio para llamadas ocasionales, porque cada llamada inicia y termina un proceso de servidor. Para pipelines con muchas llamadas a herramientas, arranca el servidor una vez en modo HTTP con --http y llámalo en http://127.0.0.1:8080/mcp para evitar la sobrecarga de inicio de proceso por llamada. Ambos transportes se autentican con un Personal Access Token o un Project Access Token.