GitLab API & CLI - Documentación Completa

Guía exhaustiva y operativa para trabajar con GitLab API REST, GraphQL y CLI (glab)

Fecha de recopilación: 18 de febrero de 2026
Fuentes: Documentación oficial de GitLab Docs
Enfoque: Ejemplos prácticos sin UI web

📚 Documentos Disponibles

1. GITLAB_API_COMPREHENSIVE_GUIDE.md

Guía completa y detallada con toda la información recopilada:

• ✅ Resumen detallado de 7 URLs oficiales de GitLab Docs
• ✅ Patrones de uso recomendados (autenticación, paginación, errores, rate limits)
• ✅ 25+ ejemplos concretos distribuidos por features:
  • Projects, Groups, Issues, Merge Requests
  • Pipelines, Jobs, Repository, Files
  • Releases, Webhooks, Variables CI/CD
  • Users, Labels, Milestones, Runners
  • Container Registry, Deployments, Environments
  • GraphQL queries y mutations avanzadas
  • glab CLI comandos directos
• ✅ Troubleshooting exhaustivo con códigos HTTP y resoluciones
• ✅ Estructura modular recomendada para skills operativas

Ideal para: Referencia completa, aprendizaje profundo, documentación de equipo

2. QUICK_REFERENCE.md

Cheatsheet de acceso rápido con comandos más comunes:

• Top 10 operaciones REST API
• Top 10 operaciones GraphQL
• Top 10 comandos glab CLI
• Paginación rápida (offset y keyset)
• Manejo de errores con scripts
• Códigos HTTP comunes
• Filtros más usados
• Variables de entorno
• Scopes de tokens
• URL encoding
• Límites importantes
• Scripts útiles de una línea

Ideal para: Consulta rápida, copy-paste, uso diario

3. PRACTICAL_SCRIPTS.md

Colección de scripts completos listos para usar:

Configuración

• setup-gitlab-env.sh - Configurar entorno

Proyectos

• list-all-projects.sh - Listar con paginación automática
• create-project.sh - Crear con configuración completa
• clone-project-settings.sh - Clonar configuración entre proyectos

Issues

• create-issue-from-template.sh - Crear desde CSV
• export-issues.sh - Exportar a JSON/CSV
• bulk-close-issues.sh - Cerrar en bulk por filtro

Merge Requests

• create-mr-from-branch.sh - Crear desde branch actual
• auto-approve-mrs.sh - Aprobar automáticamente

Pipelines

• monitor-pipeline.sh - Monitoreo en tiempo real
• trigger-pipeline-with-vars.sh - Ejecutar con variables
• retry-failed-jobs.sh - Reintentar jobs fallidos

Repository

• backup-repository.sh - Backup completo
• sync-files-to-repo.sh - Sincronizar archivos locales

Monitoreo

• monitor-ci-status.sh - Dashboard de CI/CD
• check-pipeline-health.sh - Análisis de salud

Automatización

• auto-merge-approved-mrs.sh - Merge automático
• cleanup-old-branches.sh - Limpieza de branches

Ideal para: Automatización, CI/CD, operaciones diarias

🚀 Inicio Rápido

Configuración Inicial

# 1. Clonar o descargar esta documentación
cd gitlab-docs-api

# 2. Configurar entorno (si usas scripts)
export GITLAB_TOKEN="tu-personal-access-token"
export GITLAB_HOST="https://gitlab.example.com"

# 3. Verificar acceso
curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --url "$GITLAB_HOST/api/v4/user"

Ejemplos Básicos

REST API

# Listar proyectos
curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --url "https://gitlab.example.com/api/v4/projects"

# Crear issue
curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"title": "Bug en login"}' \
  --url "https://gitlab.example.com/api/v4/projects/123/issues"

GraphQL API

# Query usuario actual
curl --request POST \
  --header "Authorization: Bearer $GITLAB_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"query": "query {currentUser {name username}}"}' \
  --url "https://gitlab.com/api/graphql"

glab CLI

# Autenticación
glab auth login

# Listar issues
glab issue list

# Crear merge request
glab mr create --title "Feature" --source-branch feature --target-branch main

📖 Contenido Detallado

URLs Oficiales Analizadas

1. GraphQL API (/api/graphql/)

   • Endpoint único versionless
   • Autenticación con tokens (OAuth, Personal, Project, Group)
   • Límites: complejidad 250, query size 10K chars, timeout 30s
   • Multiplex queries, introspección, Global IDs

2. GraphQL Reference (/api/graphql/reference/)

   • Schema completo con types, fields, arguments
   • Deprecation markers y alternativas
   • Experiments y feature flags

3. GitLab CLI - glab (/cli/)

   • Instalación multi-plataforma
   • Auto-detección de instancias
   • Comandos: api, mr, issue, ci, repo, release, variable
   • Variables de entorno configurables

4. REST API (/api/rest/)

   • Endpoint base: /api/v4
   • Paginación: offset (default) y keyset (eficiente)
   • Encoding: URL-encoded paths, arrays, hashes
   • Rate limits configurables

5. REST API Troubleshooting (/api/rest/troubleshooting/)

   • Códigos HTTP 2xx, 3xx, 4xx, 5xx
   • Errores de validación estructurados
   • Spam detection con CAPTCHA
   • Reverse proxy issues

6. GraphQL Getting Started (/api/graphql/getting_started/)

   • GraphiQL explorer interactivo
   • Command line con curl
   • Queries, mutations, paginación
   • Sorting, introspección, complejidad

7. REST Authentication (/api/rest/authentication/)

   • Tokens: OAuth 2.0, Personal, Project, Group, Job
   • Headers: PRIVATE-TOKEN, Authorization: Bearer
   • Scopes: api, read_api, sudo
   • Session cookie, impersonation

🎯 Casos de Uso Comunes

1. Automatización de Issues

# Crear issues desde CSV
./scripts/create-issue-from-template.sh 123 issues.csv

# Cerrar issues por label
./scripts/bulk-close-issues.sh 123 label "wontfix"

# Exportar issues a CSV
./scripts/export-issues.sh 123 csv

2. CI/CD Pipeline Management

# Monitorear pipeline en tiempo real
./scripts/monitor-pipeline.sh 123 456

# Ejecutar pipeline con variables
./scripts/trigger-pipeline-with-vars.sh 123 main

# Reintentar jobs fallidos
./scripts/retry-failed-jobs.sh 123 456

3. Merge Request Workflow

# Crear MR desde branch actual
./scripts/create-mr-from-branch.sh

# Auto-aprobar MRs con criterios
./scripts/auto-approve-mrs.sh 123

# Auto-merge MRs aprobados
./scripts/auto-merge-approved-mrs.sh 123 2

4. Repository Management

# Backup completo
./scripts/backup-repository.sh 123 ./backups

# Sincronizar archivos locales
./scripts/sync-files-to-repo.sh 123 ./local-files main

# Limpiar branches antiguos
./scripts/cleanup-old-branches.sh 123 30

5. Monitoreo y Reportes

# Dashboard de CI/CD
./scripts/monitor-ci-status.sh projects.txt

# Análisis de salud de pipelines
./scripts/check-pipeline-health.sh 123 7

# Listar todos los proyectos
./scripts/list-all-projects.sh

🔑 Información Clave

Autenticación

Tokens soportados:

• Personal Access Token (PAT)
• Project Access Token
• Group Access Token
• OAuth 2.0 Token
• CI/CD Job Token

Scopes necesarios:

• api - Read-write completo
• read_api - Read-only
• read_repository - Read repositorio
• write_repository - Write repositorio
• sudo - Actuar como otro usuario (admin)

Límites Importantes

| Límite | REST API | GraphQL API | |--------|----------|-------------| | Page size (default) | 20 | 20 | | Page size (max) | 100 | 100 | | Query complexity | N/A | 250 (auth), 200 (no auth) | | Query size | N/A | 10,000 chars | | Request timeout | 30s | 30s | | Blob size (multiple) | N/A | 20 MB |

Códigos HTTP Críticos

| Código | Significado | Acción Recomendada | |--------|-------------|-------------------| | 200 | OK | Procesar respuesta | | 201 | Created | Recurso creado exitosamente | | 400 | Bad Request | Verificar parámetros requeridos | | 401 | Unauthorized | Verificar token de autenticación | | 403 | Forbidden | Verificar permisos del usuario | | 404 | Not Found | Verificar ID/path del recurso | | 422 | Unprocessable | Validación falló, revisar campos | | 429 | Too Many Requests | Rate limit, implementar retry con backoff | | 500 | Server Error | Reintentar más tarde |

🛠️ Herramientas Requeridas

Para usar REST API y GraphQL:

• curl - Cliente HTTP
• jq - Procesamiento JSON
• Token de acceso válido

Para usar glab CLI:

• glab - GitLab CLI (instalación)
• Token de acceso o autenticación OAuth

Para ejecutar scripts:

• bash 4.0+
• git (para algunos scripts)
• jq 1.5+
• curl 7.0+

📝 Ejemplos de Integración

Script de CI/CD (GitLab CI)

# .gitlab-ci.yml
stages:
  - deploy

deploy:
  stage: deploy
  script:
    # Crear release automáticamente
    - |
      curl --request POST \
        --header "PRIVATE-TOKEN: $CI_JOB_TOKEN" \
        --header "Content-Type: application/json" \
        --data "{
          \"tag_name\": \"$CI_COMMIT_TAG\",
          \"name\": \"Release $CI_COMMIT_TAG\",
          \"description\": \"Automated release\"
        }" \
        --url "$CI_API_V4_URL/projects/$CI_PROJECT_ID/releases"
  only:
    - tags

Script de Monitoreo (Cron)

# /etc/cron.d/gitlab-monitor
# Ejecutar cada 5 minutos
*/5 * * * * user /path/to/monitor-ci-status.sh /path/to/projects.txt >> /var/log/gitlab-monitor.log 2>&1

Integración con Webhook

# webhook-handler.sh
# Recibe webhook de GitLab y ejecuta acciones

#!/bin/bash

# Parsear payload
EVENT_TYPE=$(echo "$1" | jq -r '.object_kind')
PROJECT_ID=$(echo "$1" | jq -r '.project.id')

case "$EVENT_TYPE" in
  "push")
    echo "Push detectado en proyecto $PROJECT_ID"
    # Ejecutar pipeline
    ./trigger-pipeline.sh "$PROJECT_ID" "main"
    ;;
  "merge_request")
    MR_ACTION=$(echo "$1" | jq -r '.object_attributes.action')
    if [ "$MR_ACTION" = "open" ]; then
      echo "Nuevo MR en proyecto $PROJECT_ID"
      # Auto-aprobar si cumple criterios
      ./auto-approve-mrs.sh "$PROJECT_ID"
    fi
    ;;
esac

🔗 Recursos Adicionales

Documentación Oficial

• GitLab API Docs
• GraphQL API Reference
• GraphQL Explorer
• glab CLI Docs
• REST API Resources

Herramientas Útiles

• GitLab CLI (glab)
• Postman Collection
• Python GitLab
• GitLab Terraform Provider

Comunidad

• GitLab Forum
• GitLab Discord
• Stack Overflow - GitLab Tag

📊 Estadísticas de la Documentación

• Total de ejemplos: 25+ distribuidos por features
• Scripts completos: 20+ listos para usar
• URLs analizadas: 7 oficiales de GitLab Docs
• Códigos HTTP documentados: 15+ con resoluciones
• Patrones de uso: Autenticación, paginación, errores, rate limits
• Features cubiertos: Projects, Groups, Issues, MRs, Pipelines, Jobs, Repository, Files, Releases, Webhooks, Variables, Users, Labels, Milestones, Runners, Registry, Deployments, Environments

🤝 Contribuciones

Esta documentación está diseñada para ser:

• ✅ Práctica: Ejemplos operativos y scripts funcionales
• ✅ Completa: Cubre REST, GraphQL y CLI
• ✅ Actualizada: Basada en docs de febrero 2026
• ✅ Modular: Fácil de extender y mantener

Para agregar nuevos ejemplos o scripts:

1. Seguir el formato existente
2. Incluir ejemplos completos y funcionales
3. Documentar parámetros y requisitos
4. Probar antes de agregar

📄 Licencia

Esta documentación está basada en la documentación oficial de GitLab, disponible bajo licencia MIT.

🎓 Próximos Pasos

1. Explorar la guía completa: GITLAB_API_COMPREHENSIVE_GUIDE.md
2. Consultar referencia rápida: QUICK_REFERENCE.md
3. Usar scripts prácticos: PRACTICAL_SCRIPTS.md
4. Configurar entorno: Ejecutar setup-gitlab-env.sh
5. Probar ejemplos: Comenzar con operaciones básicas
6. Automatizar workflows: Adaptar scripts a necesidades específicas

¿Preguntas o sugerencias?
Consulta la documentación oficial de GitLab o abre un issue en tu repositorio.

Última actualización: 18 de febrero de 2026