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 |