gitlab-skill 1.0.0

package/README.md

@@ -0,0 +1,461 @@
+# 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](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](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](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
+
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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](https://gitlab.com/gitlab-org/cli/#installation))
+- 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)
+
+```yaml
+# .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)
+
+```bash
+# /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
+
+```bash
+# 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](https://docs.gitlab.com/api/)
+- [GraphQL API Reference](https://docs.gitlab.com/api/graphql/reference/)
+- [GraphQL Explorer](https://gitlab.com/-/graphql-explorer)
+- [glab CLI Docs](https://docs.gitlab.com/cli/)
+- [REST API Resources](https://docs.gitlab.com/api/api_resources/)
+
+### Herramientas Útiles
+- [GitLab CLI (glab)](https://gitlab.com/gitlab-org/cli)
+- [Postman Collection](https://www.postman.com/gitlab)
+- [Python GitLab](https://python-gitlab.readthedocs.io/)
+- [GitLab Terraform Provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs)
+
+### Comunidad
+- [GitLab Forum](https://forum.gitlab.com/)
+- [GitLab Discord](https://discord.gg/gitlab)
+- [Stack Overflow - GitLab Tag](https://stackoverflow.com/questions/tagged/gitlab)
+
+---
+
+## 📊 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](GITLAB_API_COMPREHENSIVE_GUIDE.md)
+2. **Consultar referencia rápida**: [QUICK_REFERENCE.md](QUICK_REFERENCE.md)
+3. **Usar scripts prácticos**: [PRACTICAL_SCRIPTS.md](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