gitlab-skill 1.0.0

package/QUICK_REFERENCE.md

@@ -0,0 +1,682 @@
+# GitLab API - Referencia Rápida
+
+> Cheatsheet para acceso rápido a comandos y patrones más comunes
+
+---
+
+## Autenticación Rápida
+
+```bash
+# REST API
+export GITLAB_TOKEN="tu-token-aqui"
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "https://gitlab.example.com/api/v4/user"
+
+# GraphQL API
+curl --request POST \
+  --header "Authorization: Bearer $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{"query": "query {currentUser {name}}"}' \
+  --url "https://gitlab.com/api/graphql"
+
+# glab CLI
+glab auth login
+# o
+export GITLAB_TOKEN="tu-token-aqui"
+glab api user
+```
+
+---
+
+## Top 10 Operaciones REST API
+
+### 1. Listar proyectos
+```bash
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "https://gitlab.example.com/api/v4/projects?per_page=50"
+```
+
+### 2. Crear issue
+```bash
+curl --request POST \
+  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{"title": "Bug en login", "labels": "bug,high-priority"}' \
+  --url "https://gitlab.example.com/api/v4/projects/123/issues"
+```
+
+### 3. Crear merge request
+```bash
+curl --request POST \
+  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "source_branch": "feature-branch",
+    "target_branch": "main",
+    "title": "Add new feature"
+  }' \
+  --url "https://gitlab.example.com/api/v4/projects/123/merge_requests"
+```
+
+### 4. Ejecutar pipeline
+```bash
+curl --request POST \
+  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "https://gitlab.example.com/api/v4/projects/123/pipeline?ref=main"
+```
+
+### 5. Obtener archivo
+```bash
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "https://gitlab.example.com/api/v4/projects/123/repository/files/README.md/raw?ref=main"
+```
+
+### 6. Crear archivo
+```bash
+curl --request POST \
+  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "branch": "main",
+    "commit_message": "Add file",
+    "content": "File content"
+  }' \
+  --url "https://gitlab.example.com/api/v4/projects/123/repository/files/new-file.txt"
+```
+
+### 7. Listar pipelines
+```bash
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "https://gitlab.example.com/api/v4/projects/123/pipelines?status=running"
+```
+
+### 8. Obtener jobs de pipeline
+```bash
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "https://gitlab.example.com/api/v4/projects/123/pipelines/456/jobs"
+```
+
+### 9. Crear release
+```bash
+curl --request POST \
+  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "tag_name": "v1.0.0",
+    "name": "Release 1.0.0",
+    "description": "Release notes"
+  }' \
+  --url "https://gitlab.example.com/api/v4/projects/123/releases"
+```
+
+### 10. Crear variable CI/CD
+```bash
+curl --request POST \
+  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "key": "DEPLOY_KEY",
+    "value": "secret-value",
+    "protected": true,
+    "masked": true
+  }' \
+  --url "https://gitlab.example.com/api/v4/projects/123/variables"
+```
+
+---
+
+## Top 10 Operaciones GraphQL
+
+### 1. Query usuario actual
+```graphql
+query {
+  currentUser {
+    id
+    username
+    name
+    email
+  }
+}
+```
+
+### 2. Query proyecto con issues
+```graphql
+query {
+  project(fullPath: "grupo/proyecto") {
+    id
+    name
+    issues(first: 10, state: OPENED) {
+      nodes {
+        iid
+        title
+        state
+      }
+    }
+  }
+}
+```
+
+### 3. Query merge requests
+```graphql
+query {
+  project(fullPath: "grupo/proyecto") {
+    mergeRequests(first: 10, state: OPENED) {
+      nodes {
+        iid
+        title
+        sourceBranch
+        targetBranch
+      }
+    }
+  }
+}
+```
+
+### 4. Mutation: Crear issue
+```graphql
+mutation {
+  createIssue(input: {
+    projectPath: "grupo/proyecto",
+    title: "Bug en login"
+  }) {
+    issue {
+      iid
+      title
+    }
+    errors
+  }
+}
+```
+
+### 5. Mutation: Crear MR
+```graphql
+mutation {
+  mergeRequestCreate(input: {
+    projectPath: "grupo/proyecto",
+    sourceBranch: "feature",
+    targetBranch: "main",
+    title: "Add feature"
+  }) {
+    mergeRequest {
+      iid
+      title
+    }
+    errors
+  }
+}
+```
+
+### 6. Mutation: Cerrar issue
+```graphql
+mutation {
+  updateIssue(input: {
+    projectPath: "grupo/proyecto",
+    iid: "42",
+    stateEvent: CLOSE
+  }) {
+    issue {
+      iid
+      state
+    }
+    errors
+  }
+}
+```
+
+### 7. Mutation: Agregar comentario
+```graphql
+mutation {
+  createNote(input: {
+    noteableId: "gid://gitlab/Issue/123",
+    body: "Comentario"
+  }) {
+    note {
+      id
+      body
+    }
+    errors
+  }
+}
+```
+
+### 8. Query pipelines
+```graphql
+query {
+  project(fullPath: "grupo/proyecto") {
+    pipelines(first: 10, status: RUNNING) {
+      nodes {
+        id
+        iid
+        status
+        ref
+      }
+    }
+  }
+}
+```
+
+### 9. Mutation: Crear pipeline
+```graphql
+mutation {
+  pipelineCreate(input: {
+    projectPath: "grupo/proyecto",
+    ref: "main"
+  }) {
+    pipeline {
+      id
+      iid
+    }
+    errors
+  }
+}
+```
+
+### 10. Query con paginación
+```graphql
+query($cursor: String) {
+  project(fullPath: "grupo/proyecto") {
+    issues(first: 20, after: $cursor) {
+      edges {
+        node {
+          iid
+          title
+        }
+        cursor
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+    }
+  }
+}
+```
+
+---
+
+## Top 10 Comandos glab CLI
+
+### 1. Autenticación
+```bash
+glab auth login
+```
+
+### 2. Listar issues
+```bash
+glab issue list --state opened --label bug
+```
+
+### 3. Crear issue
+```bash
+glab issue create --title "Bug" --description "Descripción" --label bug
+```
+
+### 4. Listar merge requests
+```bash
+glab mr list --state opened
+```
+
+### 5. Crear merge request
+```bash
+glab mr create --source-branch feature --target-branch main --title "Feature"
+```
+
+### 6. Ver pipeline
+```bash
+glab ci status
+glab ci view
+```
+
+### 7. Ver trace de job
+```bash
+glab ci trace
+glab ci trace <job-id>
+```
+
+### 8. Clonar proyecto
+```bash
+glab repo clone grupo/proyecto
+```
+
+### 9. Llamada directa a API
+```bash
+glab api projects/123
+glab api --method POST projects/123/issues --field title="Issue"
+```
+
+### 10. Listar releases
+```bash
+glab release list
+```
+
+---
+
+## Paginación Rápida
+
+### REST - Offset
+```bash
+# Página 2, 50 items
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "https://gitlab.example.com/api/v4/projects?page=2&per_page=50"
+```
+
+### REST - Keyset (más eficiente)
+```bash
+# Primera página
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc"
+
+# Siguiente (usar id_after del último item)
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42"
+```
+
+### GraphQL
+```graphql
+# Primera página
+query {
+  project(fullPath: "grupo/proyecto") {
+    issues(first: 20) {
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      nodes { iid title }
+    }
+  }
+}
+
+# Siguiente (usar endCursor)
+query {
+  project(fullPath: "grupo/proyecto") {
+    issues(first: 20, after: "cursor-value") {
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      nodes { iid title }
+    }
+  }
+}
+```
+
+---
+
+## Manejo de Errores
+
+### Verificar código HTTP
+```bash
+HTTP_CODE=$(curl --write-out '%{http_code}' --silent --output /dev/null \
+  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "https://gitlab.example.com/api/v4/projects/123")
+
+echo "HTTP Code: $HTTP_CODE"
+```
+
+### Retry con backoff
+```bash
+retry_api_call() {
+  local url="$1"
+  local max_attempts=5
+  local timeout=1
+  
+  for attempt in $(seq 1 $max_attempts); do
+    HTTP_CODE=$(curl --write-out '%{http_code}' --silent --output response.json \
+      --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "$url")
+    
+    if [ "$HTTP_CODE" -eq 429 ]; then
+      echo "Rate limited, waiting ${timeout}s..."
+      sleep $timeout
+      timeout=$((timeout * 2))
+    elif [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
+      cat response.json
+      return 0
+    else
+      echo "Error: HTTP $HTTP_CODE"
+      return 1
+    fi
+  done
+}
+```
+
+### Verificar errores GraphQL
+```bash
+RESPONSE=$(curl --request POST --silent \
+  --header "Authorization: Bearer $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{"query": "query {currentUser {name}}"}' \
+  --url "https://gitlab.com/api/graphql")
+
+if echo "$RESPONSE" | jq -e '.errors' > /dev/null; then
+  echo "Errors found:"
+  echo "$RESPONSE" | jq '.errors'
+else
+  echo "$RESPONSE" | jq '.data'
+fi
+```
+
+---
+
+## Códigos HTTP Comunes
+
+| Código | Significado | Acción |
+|--------|-------------|--------|
+| 200 | OK | Procesar respuesta |
+| 201 | Created | Recurso creado |
+| 204 | No Content | Éxito sin datos |
+| 400 | Bad Request | Verificar parámetros |
+| 401 | Unauthorized | Verificar token |
+| 403 | Forbidden | Verificar permisos |
+| 404 | Not Found | Verificar ID/path |
+| 409 | Conflict | Recurso ya existe |
+| 422 | Unprocessable | Validación falló |
+| 429 | Too Many Requests | Rate limit - esperar |
+| 500 | Server Error | Reintentar más tarde |
+| 503 | Service Unavailable | Servidor sobrecargado |
+
+---
+
+## Filtros Comunes
+
+### Issues
+```bash
+# Por estado
+?state=opened
+?state=closed
+
+# Por labels
+?labels=bug,critical
+
+# Por assignee
+?assignee_id=5
+
+# Por milestone
+?milestone=v1.0
+
+# Por búsqueda
+?search=login
+```
+
+### Merge Requests
+```bash
+# Por estado
+?state=opened
+?state=merged
+
+# Por autor
+?author_id=5
+
+# Por reviewer
+?reviewer_id=10
+
+# Por source branch
+?source_branch=feature-branch
+
+# Por target branch
+?target_branch=main
+```
+
+### Pipelines
+```bash
+# Por estado
+?status=running
+?status=success
+?status=failed
+
+# Por ref
+?ref=main
+
+# Por SHA
+?sha=abc123
+
+# Por fecha
+?updated_after=2026-01-01T00:00:00Z
+?updated_before=2026-12-31T23:59:59Z
+```
+
+---
+
+## Variables de Entorno glab
+
+```bash
+# Token de autenticación
+export GITLAB_TOKEN="tu-token"
+
+# Host de GitLab
+export GITLAB_HOST="https://gitlab.example.com"
+export GL_HOST="https://gitlab.example.com"
+
+# Deshabilitar prompts
+export NO_PROMPT=true
+
+# Debug
+export DEBUG=true
+
+# Config directory
+export GLAB_CONFIG_DIR="$HOME/.config/glab"
+```
+
+---
+
+## Scopes de Tokens
+
+| Scope | Descripción |
+|-------|-------------|
+| `api` | Read-write completo (REST + GraphQL) |
+| `read_api` | Read-only (REST + GraphQL) |
+| `read_repository` | Read-only repositorio |
+| `write_repository` | Write repositorio |
+| `sudo` | Actuar como otro usuario (admin) |
+
+---
+
+## URL Encoding
+
+```bash
+# Caracteres especiales
+/ → %2F
+? → %3F
+@ → %40
++ → %2B
+= → %3D
+& → %26
+
+# Ejemplos
+grupo/proyecto → grupo%2Fproyecto
+src/app.js → src%2Fapp.js
+feature/new-feature → feature%2Fnew-feature
+```
+
+---
+
+## Límites Importantes
+
+| Límite | Valor |
+|--------|-------|
+| REST - Per page (max) | 100 |
+| REST - Per page (default) | 20 |
+| GraphQL - Complejidad (no auth) | 200 |
+| GraphQL - Complejidad (auth) | 250 |
+| GraphQL - Query size | 10,000 caracteres |
+| GraphQL - Page size (max) | 100 |
+| Request timeout | 30 segundos |
+| Blob size (multiple) | 20 MB |
+
+---
+
+## Scripts Útiles
+
+### Listar todos los proyectos (con paginación)
+```bash
+#!/bin/bash
+page=1
+while true; do
+  response=$(curl --silent \
+    --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+    --url "https://gitlab.example.com/api/v4/projects?page=$page&per_page=100")
+  
+  if [ "$(echo "$response" | jq '. | length')" -eq 0 ]; then
+    break
+  fi
+  
+  echo "$response" | jq -r '.[] | "\(.id) - \(.name)"'
+  page=$((page + 1))
+done
+```
+
+### Monitorear pipeline
+```bash
+#!/bin/bash
+PROJECT_ID="123"
+PIPELINE_ID="456"
+
+while true; do
+  status=$(curl --silent \
+    --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+    --url "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID" \
+    | jq -r '.status')
+  
+  echo "Pipeline status: $status"
+  
+  if [[ "$status" == "success" || "$status" == "failed" || "$status" == "canceled" ]]; then
+    break
+  fi
+  
+  sleep 10
+done
+```
+
+### Crear issue en bulk
+```bash
+#!/bin/bash
+PROJECT_ID="123"
+
+while IFS=',' read -r title description labels; do
+  curl --request POST \
+    --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+    --header "Content-Type: application/json" \
+    --data "{
+      \"title\": \"$title\",
+      \"description\": \"$description\",
+      \"labels\": \"$labels\"
+    }" \
+    --url "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/issues"
+  
+  sleep 1  # Rate limiting
+done < issues.csv
+```
+
+---
+
+## Recursos Rápidos
+
+- **Docs REST**: https://docs.gitlab.com/api/rest/
+- **Docs GraphQL**: https://docs.gitlab.com/api/graphql/
+- **GraphQL Reference**: https://docs.gitlab.com/api/graphql/reference/
+- **GraphQL Explorer**: https://gitlab.com/-/graphql-explorer
+- **glab Docs**: https://docs.gitlab.com/cli/
+- **Status Codes**: https://docs.gitlab.com/api/rest/troubleshooting/#status-codes
+
+---
+
+**Última actualización**: 18 de febrero de 2026