gitlab-skill 1.0.0

package/SKILL.md

@@ -0,0 +1,789 @@
+---
+name: gitlab-api-operations
+description: Opera GitLab sin UI web usando REST API, GraphQL API y glab CLI. Usar cuando el usuario pida crear, consultar, actualizar o automatizar recursos de GitLab (projects, issues, merge requests, pipelines, repositorio, metadatos) con parametros exactos, tipos de datos y manejo de errores.
+---
+
+# GitLab API Operations Skill
+
+## Contexto de la skill
+
+Esta skill define una forma estandar para operar GitLab sin interfaz web, usando:
+- REST API (`/api/v4/...`)
+- GraphQL API (`/api/graphql`)
+- GitLab CLI `glab`
+
+Objetivo: responder y ejecutar operaciones con precision operativa (endpoint/metodo, parametros, schema de request, schema de response, tipos de datos y codigos HTTP).
+
+Fuente de verdad local para REST: `openapi_v2.yaml`.
+
+## Estructura modular recomendada
+
+Para escalar contexto sin inflar este archivo, usar referencias por feature:
+
+- `skill-features/00-auth-and-bootstrap.md`
+- `skill-features/01-discovery-and-projects.md`
+- `skill-features/02-repository-and-code.md`
+- `skill-features/03-issues-and-merge-requests.md`
+- `skill-features/04-cicd-pipelines-jobs.md`
+- `skill-features/05-security-and-vulnerabilities.md`
+- `skill-features/06-graphql-and-glab-playbook.md`
+
+Regla: cargar primero el archivo del feature solicitado y mantener `SKILL.md` como índice operativo.
+
+## Referencias extendidas (alto detalle)
+
+Para maximizar contexto sin saturar el prompt principal, usar estas guías complementarias:
+
+- `GITLAB_API_COMPREHENSIVE_GUIDE.md` (resumen por URL + 25+ ejemplos multi-feature)
+- `QUICK_REFERENCE.md` (cheatsheet operacional)
+- `PRACTICAL_SCRIPTS.md` (scripts end-to-end listos para ejecución)
+- `README.md` (índice general)
+
+Prioridad de lectura recomendada:
+1. `SKILL.md` (orquestación)
+2. `skill-features/*.md` (feature específico)
+3. `QUICK_REFERENCE.md` (comandos rápidos)
+4. `GITLAB_API_COMPREHENSIVE_GUIDE.md` y `PRACTICAL_SCRIPTS.md` (profundidad y automatización)
+
+## Regla base de exactitud
+
+Para cualquier endpoint REST solicitado:
+1. Ubica el path exacto en `openapi_v2.yaml`.
+2. Usa el metodo correcto (`get`, `post`, `put`, `delete`, etc.).
+3. Lista parametros por ubicacion (`path`, `query`, `body`) con `type`, `required`, `enum`, `format`.
+4. Si hay body, sigue su `$ref` en `definitions`.
+5. Para cada respuesta, reporta codigo y schema (`$ref` o tipo inline).
+6. No inventes campos no presentes en OpenAPI.
+
+## 1) Autenticacion (siempre primero)
+
+### 1.1 REST API
+
+Base: `https://<gitlab-host>/api/v4`
+
+Metodos soportados por doc:
+- Header: `PRIVATE-TOKEN: <token>`
+- Query: `private_token=<token>`
+
+Ejemplo:
+```bash
+curl --request GET \
+  --header "PRIVATE-TOKEN: <token>" \
+  --url "https://gitlab.example.com/api/v4/projects"
+```
+
+### 1.2 GraphQL API
+
+Endpoint: `https://<gitlab-host>/api/graphql`
+
+Autenticacion soportada:
+- `Authorization: Bearer <token>`
+- `access_token=<oauth_token>` o `private_token=<access_token>` en query string
+
+Scopes:
+- `read_api`: consultas (queries)
+- `api`: mutaciones (mutations) y escritura
+
+Ejemplo:
+```bash
+curl --request POST \
+  --url "https://gitlab.com/api/graphql" \
+  --header "Authorization: Bearer <token>" \
+  --header "Content-Type: application/json" \
+  --data "{\"query\":\"query { currentUser { name } }\"}"
+```
+
+### 1.3 CLI (`glab`)
+
+Login interactivo:
+```bash
+glab auth login
+```
+
+Variables utiles:
+- `GITLAB_HOST` o `GL_HOST`
+- `GITLAB_TOKEN`
+- `NO_PROMPT=true` para ejecucion no interactiva
+
+Regla: si `glab` no esta autenticado, autenticar antes de cualquier comando operativo.
+
+## 2) Convenciones operativas globales
+
+- `id` vs `iid`: en REST, muchos recursos se consultan por `iid` dentro del proyecto (issues, merge requests).
+- Paths namespaced deben ir URL-encoded (`group/project` -> `group%2Fproject`).
+- Para fechas ISO con `+`, codificar `%2B`.
+- Paginacion:
+  - Offset: `page`, `per_page`
+  - Keyset: `pagination=keyset&order_by=...&sort=...` y seguir header `Link`.
+- Troubleshooting: reportar siempre codigo HTTP + mensaje + headers relevantes.
+
+## 3) Mapa de capacidades por dominio
+
+### A. Instancia y metadatos
+
+#### `GET /api/v4/metadata`
+- Path/query params: ninguno.
+- Response:
+  - `200` -> `API_Entities_Metadata`
+  - `401` -> Unauthorized
+- Tipo `API_Entities_Metadata`:
+  - `version: string`
+  - `revision: string`
+  - `kas: object { enabled: boolean, externalUrl: string, externalK8sProxyUrl: string, version: string }`
+  - `enterprise: boolean`
+
+#### `GET /api/v4/version` (deprecado)
+- Response:
+  - `200` -> `API_Entities_Metadata`
+  - `401` -> Unauthorized
+- Nota: preferir `GET /api/v4/metadata`.
+
+### B. Proyectos
+
+#### `GET /api/v4/projects`
+- Query params clave:
+  - `order_by: string` enum `id|name|path|created_at|updated_at|last_activity_at|similarity|star_count|storage_size|repository_size|wiki_size|packages_size`
+  - `sort: string` enum `asc|desc`
+  - `visibility: string` enum `private|internal|public`
+  - `search: string`
+  - `min_access_level: integer`
+  - `topic: array[string]`
+  - `page: integer`, `per_page: integer`
+- Response:
+  - `200` -> `array[API_Entities_BasicProjectDetails]`
+  - `400` -> Bad request
+- Tipo `API_Entities_BasicProjectDetails` (campos relevantes):
+  - `id: integer`
+  - `name: string`
+  - `path_with_namespace: string`
+  - `default_branch: string`
+  - `topics: array[string]`
+  - `web_url: string`
+  - `visibility: string`
+  - `created_at: string(date-time)`
+
+#### `POST /api/v4/projects`
+- Body schema: `postApiV4Projects`
+- Campos base recomendados:
+  - `name: string` (recomendado)
+  - `path: string`
+  - `default_branch: string`
+  - `description: string`
+  - `visibility/accesos`: varios enums (`issues_access_level`, `repository_access_level`, etc.)
+- Response:
+  - `201` -> `API_Entities_Project`
+  - `400|403|404`
+
+#### `GET /api/v4/projects/{id}`
+- Path params:
+  - `id: string` (ID o path URL-encoded)
+- Query opcionales:
+  - `statistics: boolean`
+  - `with_custom_attributes: boolean`
+  - `license: boolean`
+- Response:
+  - `200` -> `API_Entities_ProjectWithAccess`
+
+### C. Issues de proyecto
+
+#### `GET /api/v4/projects/{id}/issues`
+- Path params:
+  - `id: string` requerido
+- Query comunes:
+  - `state: string` enum `opened|closed|all`
+  - `order_by: string` enum incluye `created_at|updated_at|due_date|priority|weight|title|...`
+  - `sort: string` enum `asc|desc`
+  - `labels: array[string]`
+  - `iids: array[integer]`
+  - `author_id: integer`, `assignee_id: integer`
+  - `created_after|created_before|updated_after|updated_before: string(date-time)`
+  - `page`, `per_page`, `cursor`
+- Response:
+  - `200` -> `API_Entities_Issue`
+
+#### `POST /api/v4/projects/{id}/issues`
+- Path params:
+  - `id: string`
+- Body schema: `postApiV4ProjectsIdIssues`
+- Campos:
+  - Requerido: `title: string`
+  - Opcionales: `description: string`, `assignee_ids: array[integer]`, `milestone_id: integer`, `labels: array[string]`, `confidential: boolean`, `due_date: string`, `issue_type: string enum (issue|incident|test_case|requirement|task|ticket)`, `weight: integer`
+- Response:
+  - `201` -> `API_Entities_Issue`
+
+Tipo `API_Entities_Issue` (campos relevantes):
+- `id: integer`, `iid: integer`, `project_id: integer`
+- `title: string`, `description: string`, `state: string`
+- `created_at|updated_at|closed_at: string(date-time)`
+- `labels: array[string]`
+- `web_url: string`
+- `issue_type: string`
+
+### D. Merge Requests
+
+#### `GET /api/v4/projects/{id}/merge_requests`
+- Path params:
+  - `id: string`
+- Query comunes:
+  - `state: string` enum `opened|closed|locked|merged|all`
+  - `author_id: integer` / `author_username: string`
+  - `assignee_id: integer` / `assignee_username: array[string]`
+  - `reviewer_id: integer` / `reviewer_username: string`
+  - `source_branch: string`, `target_branch: string`
+  - `order_by: string`, `sort: string`
+  - `search: string`, `iids: array[integer]`
+  - `page`, `per_page`
+- Response:
+  - `200` -> `array[API_Entities_MergeRequestBasic]`
+  - `401|404|422`
+
+#### `POST /api/v4/projects/{id}/merge_requests`
+- Body schema: `postApiV4ProjectsIdMergeRequests`
+- Requeridos:
+  - `title: string`
+  - `source_branch: string`
+  - `target_branch: string`
+- Opcionales:
+  - `target_project_id: integer`
+  - `assignee_ids: array[integer]`
+  - `reviewer_ids: array[integer]`
+  - `description: string`
+  - `labels/add_labels/remove_labels: array[string]`
+  - `remove_source_branch: boolean`
+  - `allow_collaboration: boolean`
+  - `squash: boolean`
+  - `merge_after: string`
+- Response:
+  - `201` -> `API_Entities_MergeRequest`
+  - `400|401|404|409|422`
+
+Tipo `API_Entities_MergeRequestBasic` (campos relevantes):
+- `id: integer`, `iid: integer`, `project_id: integer`
+- `title: string`, `description: string`, `state: string`
+- `source_branch: string`, `target_branch: string`
+- `author: object`, `assignees: object`, `reviewers: object`
+- `web_url: string`, `merge_status: string`, `detailed_merge_status: string`
+
+### E. Pipelines y Jobs (CI/CD)
+
+#### `GET /api/v4/projects/{id}/pipelines`
+- Path params:
+  - `id: string`
+- Query comunes:
+  - `scope: string` enum `running|pending|finished|branches|tags`
+  - `status: string` enum incluye `created|running|success|failed|canceled|...`
+  - `ref: string`, `sha: string`, `username: string`
+  - `updated_before/after`, `created_before/after: string(date-time)`
+  - `order_by: string` enum `id|status|ref|updated_at|user_id`
+  - `sort: string` enum `asc|desc`
+  - `source: string` enum (`push|web|trigger|schedule|api|...`)
+  - `page`, `per_page`
+- Response:
+  - `200` -> `array[API_Entities_Ci_PipelineBasic]`
+  - `401|403`
+
+#### `POST /api/v4/projects/{id}/pipeline`
+- Body schema: `postApiV4ProjectsIdPipeline`
+- Requerido:
+  - `ref: string`
+- Opcionales:
+  - `variables: array[object { key: string, value: string, variable_type: enum(env_var|file) }]`
+  - `inputs: object`
+- Response:
+  - `201` -> `API_Entities_Ci_Pipeline`
+  - `400|401|403|404`
+
+#### `GET /api/v4/projects/{id}/jobs`
+- Query:
+  - `scope: array[string]` enum estados de job
+  - `ref: string`
+  - `page`, `per_page`
+- Response:
+  - `200` -> `array[API_Entities_Ci_Job]`
+  - `401|403|404`
+
+Tipo `API_Entities_Ci_PipelineBasic`:
+- `id: integer`, `iid: integer`, `project_id: integer`
+- `sha: string`, `ref: string`, `status: string`, `source: string`
+- `created_at|updated_at: string(date-time)`
+- `web_url: string`
+
+Tipo `API_Entities_Ci_Job`:
+- `id: integer`, `status: string`, `stage: string`, `name: string`, `ref: string`
+- `tag: boolean`, `coverage: number(float)`, `allow_failure: boolean`
+- `created_at|started_at|finished_at: string(date-time)`
+- `duration|queued_duration: number(float)`
+- `pipeline: API_Entities_Ci_PipelineBasic`
+- `web_url: string`
+
+### F. Repositorio y archivos
+
+#### `GET /api/v4/projects/{id}/repository/tree`
+- Path params:
+  - `id: string`
+- Query:
+  - `ref: string`
+  - `path: string`
+  - `recursive: boolean`
+  - `pagination: string enum legacy|keyset|none`
+  - `page_token: string` (keyset)
+  - `page`, `per_page`
+- Response:
+  - `200` -> `API_Entities_TreeObject`
+
+Tipo `API_Entities_TreeObject`:
+- `id: string`, `name: string`, `type: string`, `path: string`, `mode: string`
+
+#### `GET|HEAD|POST|PUT|DELETE /api/v4/projects/{id}/repository/files/{file_path}`
+- Path params:
+  - `id: string`
+  - `file_path: string` URL-encoded
+- `GET/HEAD`:
+  - Query: `ref: string` (requerido)
+- `POST`:
+  - Body schema: `postApiV4ProjectsIdRepositoryFilesFilePath`
+  - Response `201`
+- `PUT`:
+  - Body schema: `putApiV4ProjectsIdRepositoryFilesFilePath`
+  - Response `200`
+- `DELETE`:
+  - Query requeridos: `branch: string`, `commit_message: string`
+  - Query opcionales: `start_branch`, `author_email`, `author_name`, `last_commit_id`
+  - Response `204`
+
+## 4) GraphQL operativo
+
+### Endpoint y forma de uso
+- Endpoint: `/api/graphql`
+- Metodo: `POST`
+- Payload:
+  - `query: string`
+  - `variables: object` (recomendado para evitar limite de tamano)
+
+### Identificadores y tipos
+- `id` en GraphQL normalmente es Global ID (`gid://gitlab/...`)
+- Para project/group/namespace suele usarse `fullPath`
+- Para recursos con IID, usar `projectPath + iid`
+
+### Limites relevantes
+- Complejidad maxima: 200 no autenticado, 250 autenticado
+- Tamano maximo de query/mutation: 10,000 caracteres
+- Timeout de request: 30s
+
+### Patrones minimos
+
+Query por proyecto:
+```graphql
+query($fullPath: ID!) {
+  project(fullPath: $fullPath) {
+    id
+    fullPath
+  }
+}
+```
+
+Mutation por IID:
+```graphql
+mutation($projectPath: ID!, $iid: String!, $locked: Boolean!) {
+  issueSetLocked(input: { projectPath: $projectPath, iid: $iid, locked: $locked }) {
+    issue { id iid }
+    errors
+  }
+}
+```
+
+## 5) CLI (`glab`) operativo
+
+Usar `glab` para flujos de terminal sin UI web.
+
+### Comandos base
+- Login: `glab auth login`
+- Estado auth: `glab auth status`
+- REST genrico: `glab api /projects`
+- REST con paginacion: `glab api /projects --paginate`
+- GraphQL: `glab api graphql -f query='query { currentUser { username } }'`
+
+### Comandos funcionales por dominio
+- Issues: `glab issue ...`
+- Merge Requests: `glab mr ...`
+- Pipelines/Jobs CI: `glab ci ...`, `glab job ...`
+- Releases: `glab release ...`
+- Variables: `glab variable ...`
+
+Regla: preferir comandos de alto nivel (`glab mr`, `glab issue`) y usar `glab api` cuando se necesite control exacto de endpoint/payload.
+
+## 6) Manejo de errores y troubleshooting
+
+Siempre reportar:
+1. Metodo + endpoint exacto
+2. Payload enviado (sin secretos)
+3. Codigo HTTP
+4. Mensaje de error parseado
+5. Siguiente accion sugerida
+
+Codigos clave: `400`, `401`, `403`, `404`, `409`, `412`, `422`, `429`, `500`, `503`.
+
+Buenas practicas de depuracion:
+- Usar `--include` para headers.
+- Usar `--fail` para detectar error por exit code en curl.
+- Si hay reverse proxy y 404 con paths codificados, validar configuracion para no decodificar `%2F`.
+
+## 7) Fuentes de referencia
+
+- REST API: https://docs.gitlab.com/api/rest/
+- REST troubleshooting: https://docs.gitlab.com/api/rest/troubleshooting/
+- OpenAPI interactivo: https://docs.gitlab.com/api/openapi/openapi_interactive/
+- GraphQL API: https://docs.gitlab.com/api/graphql/
+- GraphQL examples: https://docs.gitlab.com/api/graphql/examples/
+- GraphQL reference: https://docs.gitlab.com/api/graphql/reference/
+- GitLab CLI: https://docs.gitlab.com/cli/
+- Especificacion local REST: `openapi_v2.yaml`
+
+## 8) Portabilidad de la skill (sin subir OpenAPI al repo)
+
+Esta skill debe funcionar en dos modos:
+
+### Modo A: con `openapi_v2.yaml` local
+- Usar `openapi_v2.yaml` como fuente exacta para endpoint, parametros, tipos y respuestas.
+- No es obligatorio versionarlo en Git.
+
+### Modo B: sin `openapi_v2.yaml` en el repo
+- Operar con:
+  - este catalogo embebido de endpoints por feature
+  - REST docs oficiales
+  - GraphQL reference + introspeccion
+  - `glab api` para validacion rapida
+- Regla: cuando falte schema exacto, reportar explicitamente `schema no verificado en OpenAPI local` y continuar con endpoint + parametros documentados.
+
+### Estructura de distribucion (ambos enfoques)
+- En carpeta compartida: `.cursor/skills/gitlab-api-operations/SKILL.md`
+- En paquete Node: incluir `SKILL.md` en el paquete y copiarlo en postinstall al directorio de skills del usuario/proyecto.
+
+## 9) Variables runtime minimas para agentes
+
+Definir estas variables antes de operar:
+
+```bash
+export GITLAB_HOST="https://gitlab.com"
+export GITLAB_TOKEN="<personal_access_token>"
+export GITLAB_USER="<username>"
+export TARGET_PROJECT_PATH="grupo/proyecto"
+export TARGET_GROUP_PATH="grupo"
+```
+
+Helpers:
+```bash
+export PROJECT_ENC="$(python - <<'PY'
+import os, urllib.parse
+print(urllib.parse.quote(os.environ['TARGET_PROJECT_PATH'], safe=''))
+PY
+)"
+export GROUP_ENC="$(python - <<'PY'
+import os, urllib.parse
+print(urllib.parse.quote(os.environ['TARGET_GROUP_PATH'], safe=''))
+PY
+)"
+```
+
+## 10) Catalogo ampliado de endpoints por features (ejemplos listos)
+
+Nota: todos los ejemplos usan header `PRIVATE-TOKEN`.
+
+### 10.1 Descubrimiento y alcance
+
+```bash
+# Proyectos visibles
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects?membership=true&per_page=100"
+
+# Proyecto por path
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC?statistics=true"
+
+# Proyectos de un grupo
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/groups/$GROUP_ENC/projects?include_subgroups=true&per_page=100"
+
+# Issues globales accesibles por el usuario autenticado
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/issues?scope=all&state=opened&per_page=100"
+
+# Merge requests globales
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/merge_requests?scope=all&state=opened&per_page=100"
+```
+
+### 10.2 Repositorio y codigo
+
+```bash
+# Tree de repositorio
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/tree?ref=main&recursive=true&pagination=keyset&per_page=100"
+
+# Listar ramas
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/branches?search=feature&per_page=100"
+
+# Detalle de rama
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/branches/main"
+
+# Proteger/desproteger rama
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/branches/main/protect"
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/branches/main/unprotect"
+
+# Commits
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/commits?ref_name=main&per_page=100"
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/commits/<sha>"
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/commits/<sha>/diff"
+
+# Comparar ramas
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/compare?from=main&to=develop&straight=false"
+```
+
+### 10.3 Archivos en repositorio
+
+```bash
+export FILE_PATH_ENC="src%2FREADME.md"
+
+# Metadata (HEAD)
+curl --head --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/files/$FILE_PATH_ENC?ref=main"
+
+# Obtener archivo (base64 en response)
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/files/$FILE_PATH_ENC?ref=main"
+
+# Raw
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/files/$FILE_PATH_ENC/raw?ref=main"
+
+# Crear archivo
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{"branch":"main","commit_message":"create file","content":"hola","encoding":"text"}' \
+  "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/files/new%2Ffile.txt"
+
+# Actualizar archivo
+curl --request PUT --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{"branch":"main","commit_message":"update file","content":"nuevo contenido","encoding":"text"}' \
+  "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/files/new%2Ffile.txt"
+
+# Eliminar archivo
+curl --request DELETE --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/repository/files/new%2Ffile.txt?branch=main&commit_message=delete"
+```
+
+### 10.4 Issues y merge requests
+
+```bash
+# Issues de proyecto
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/issues?state=opened&order_by=updated_at&sort=desc&per_page=100"
+
+# Crear issue
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{"title":"Bug movil","description":"Detalle tecnico","labels":["bug","mobile"],"issue_type":"issue"}' \
+  "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/issues"
+
+# MRs de proyecto
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/merge_requests?state=opened&scope=all&per_page=100"
+
+# Crear MR
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{"title":"feat: harden auth","source_branch":"feature/auth","target_branch":"main","remove_source_branch":true,"squash":true}' \
+  "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/merge_requests"
+
+# Issues/MRs a nivel grupo
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/groups/$GROUP_ENC/issues?state=opened&per_page=100"
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/groups/$GROUP_ENC/merge_requests?state=opened&per_page=100"
+```
+
+### 10.5 Miembros, acceso y gobernanza
+
+```bash
+# Miembros del proyecto
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/members?per_page=100"
+
+# Miembros del grupo
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/groups/$GROUP_ENC/members?per_page=100"
+
+# Access requests del proyecto
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/access_requests"
+```
+
+### 10.6 CI/CD, pipelines, jobs y variables
+
+```bash
+# Pipelines del proyecto
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/pipelines?status=failed&per_page=100"
+
+# Crear pipeline
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{"ref":"main","variables":[{"key":"SCAN","value":"true","variable_type":"env_var"}]}' \
+  "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/pipeline"
+
+# Pipeline detalle + jobs + variables
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/pipelines/<pipeline_id>"
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/pipelines/<pipeline_id>/jobs?per_page=100"
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/pipelines/<pipeline_id>/variables"
+
+# Retry/cancel pipeline
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/pipelines/<pipeline_id>/retry"
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/pipelines/<pipeline_id>/cancel"
+
+# Jobs y trace
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/jobs?scope[]=failed&scope[]=success&per_page=100"
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/jobs/<job_id>/trace"
+
+# Variables de proyecto
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/variables"
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{"key":"SEC_SCAN_MODE","value":"strict","masked":false,"protected":false}' \
+  "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/variables"
+```
+
+### 10.7 Artifacts, releases y webhooks
+
+```bash
+# Artifacts por job o por ref
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/jobs/<job_id>/artifacts"
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/jobs/artifacts/main/download?job=<job_name>"
+
+# Releases
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/releases?per_page=100"
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/releases/<tag_name>"
+
+# Hooks
+curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --url "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/hooks"
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{"url":"https://example.com/webhook","push_events":true,"merge_requests_events":true}' \
+  "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/hooks"
+```
+
+### 10.8 Seguridad y vulnerabilidades (flujo autonomo)
+
+#### A) Endpoints REST de seguridad disponibles en OpenAPI
+
+```bash
+# NPM advisory bulk (proyecto)
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{"name":"mobilcash-web","version":"1.0.0","requires":{},"dependencies":{}}' \
+  "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/packages/npm/-/npm/v1/security/advisories/bulk"
+
+# NPM quick audit (proyecto)
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{"name":"mobilcash-web","version":"1.0.0","requires":{},"dependencies":{}}' \
+  "$GITLAB_HOST/api/v4/projects/$PROJECT_ENC/packages/npm/-/npm/v1/security/audits/quick"
+
+# NPM advisory bulk (grupo)
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{"name":"mobilcash-web","version":"1.0.0","requires":{},"dependencies":{}}' \
+  "$GITLAB_HOST/api/v4/groups/$GROUP_ENC/-/packages/npm/-/npm/v1/security/advisories/bulk"
+```
+
+#### B) GraphQL para vulnerabilidades de proyecto (recomendado)
+
+1) Introspeccion minima para descubrir campos reales del schema:
+```bash
+curl --request POST \
+  --url "$GITLAB_HOST/api/graphql" \
+  --header "Authorization: Bearer $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{"query":"query { __type(name:\"Project\") { fields { name } } }"}'
+```
+
+2) Query plantilla para listado de vulnerabilidades (ajustar a schema real):
+```graphql
+query($fullPath: ID!, $first: Int!, $after: String) {
+  project(fullPath: $fullPath) {
+    vulnerabilities(first: $first, after: $after) {
+      nodes {
+        id
+        title
+        severity
+        state
+        reportType
+        confidence
+        description
+      }
+      pageInfo { endCursor hasNextPage }
+    }
+  }
+}
+```
+
+3) Regla de paginacion GraphQL:
+- Iterar mientras `hasNextPage=true`, reenviando `after=endCursor`.
+- Consolidar resultados en JSON unico.
+
+#### C) Consolidacion automatica para "lista vulnerabilidades"
+
+Flujo sugerido para agentes:
+1. Resolver `project_id` y `project_path`.
+2. Extraer vulnerabilidades via GraphQL (paginado).
+3. En paralelo, obtener:
+   - ultimos pipelines fallidos
+   - jobs de seguridad (por nombre/etiquetas/artefactos)
+   - quick audits/advisories npm si aplica
+4. Normalizar en objeto unico:
+   - `summary` (totales por severidad/estado)
+   - `findings` (lista detallada)
+   - `evidence` (pipeline/job/url/source)
+5. Devolver recomendaciones accionables.
+
+## 11) Equivalentes con `glab` para operacion diaria
+
+```bash
+# REST
+glab api "/projects/$PROJECT_ENC"
+glab api "/projects/$PROJECT_ENC/issues?state=opened&per_page=100" --paginate
+glab api "/projects/$PROJECT_ENC/merge_requests?state=opened&scope=all&per_page=100" --paginate
+glab api "/projects/$PROJECT_ENC/pipelines?per_page=100" --paginate
+
+# GraphQL: introspeccion Project
+glab api graphql -f query='query { __type(name:"Project") { fields { name } } }'
+
+# GraphQL: currentUser
+glab api graphql -f query='query { currentUser { id username name } }'
+```
+
+Regla operativa:
+- Si existe comando nativo (`glab issue`, `glab mr`, `glab ci`), se puede usar.
+- Para control fino de payload/headers/paginacion, preferir `glab api`.
+