claudeCode0/skill-gitea
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
skill-gitea/endpoints.md

6.2 KiB
Raw Permalink Blame History

Gitea 1.24 — endpoint cheat sheet

Base URL: https://gitea.nucleoriofrio.com/api/v1 (la skill prefija /api/v1 si el path no empieza con /api/).

Auth: Authorization: token <PAT>. Todas las queries pasan por scripts/query.sh salvo que digamos lo contrario.

Health

Endpoint Notas
GET /version Health check. Devuelve {"version":"1.24.7"}
GET /user El usuario detrás del PAT actual

Repos

Endpoint Notas
POST /user/repos Crear repo bajo el user autenticado (claudeCode0). Body: ver schema abajo. La skill bloquea private:true acá (regla dura)
POST /orgs/{org}/repos Crear repo bajo una org (NucleOS). Mismo body
GET /users/{user}/repos Listar repos. Si el caller es ese user, devuelve todos (incluyendo privados); si es otro, solo públicos. Querystring: page, limit, sort (updated/oldest/alphabetically/size). Helper: repo-list.sh
GET /orgs/{org}/repos Listar repos de la org según permisos del PAT. Mismo querystring que el de user. Helper: repo-list.sh --owner <org>
GET /repos/{o}/{r} Detalle de un repo
DELETE /repos/{o}/{r} Borrar repo (requiere PAT con delete_repo o admin)

Schema de creación (POST body)

{
  "name": "skill-foo",                 // required
  "description": "...",                // opcional
  "private": false,                    // default false
  "auto_init": true,                   // crear con README inicial
  "default_branch": "main",
  "license": "MIT",                    // opcional, template name
  "gitignores": "Node",                // opcional, template name (case-sensitive)
  "readme": "Default",                 // opcional, README template
  "template": false                    // marcar como template repo
}

Listas de templates válidos: ver https://gitea.nucleoriofrio.com/api/v1/repos/issue/templates no aplica; los template names son los mismos que GitHub usa para gitignore (Node, Python, Go, etc.) y para licenses (MIT, Apache-2.0, GPL-3.0). Para gitignores no comunes (ej. "Bash"), Gitea responde 400 silencioso — omitir el campo y crear un .gitignore manualmente después.

Pull Requests

Endpoint Filtros / body
GET /repos/{o}/{r}/pulls ?state=open|closed|all, ?limit=N, ?page=N, ?sort=...
GET /repos/{o}/{r}/pulls/{number} Detalle completo
POST /repos/{o}/{r}/pulls Body: {title, body, head, base}. head = branch (mismo repo) o user:branch (fork)
GET /repos/{o}/{r}/issues/{n}/comments PRs son issues; este es el endpoint de comments. Requiere PAT con read:issue
POST /repos/{o}/{r}/issues/{n}/comments Crear comment (out of scope en MVP)
POST /repos/{o}/{r}/pulls/{n}/merge Mergear (out of scope — disruptive)

Schema mínimo PR create (POST body)

{
  "title": "fix(scope): short imperative",
  "body": "## Context\n...",
  "head": "feature-branch",
  "base": "main"
}

Gitea Actions

Discovery / metadata

Endpoint Notas
GET /repos/{o}/{r}/actions/workflows Lista workflows. id = filename (ej. deploy-infra.yml)
GET /repos/{o}/{r}/actions/workflows/{wf_id} Single workflow
GET /repos/{o}/{r}/actions/workflows/{wf_id}/timing Tiempos del workflow

Runs (Gitea los llama "tasks")

Endpoint Notas
GET /repos/{o}/{r}/actions/tasks Lista todos los runs (filtros server-side: solo page+limit). Devuelve {workflow_runs: [{id, run_number, status, event, head_branch, head_sha, workflow_id, display_title, created_at, updated_at, run_started_at, url, name}], total_count}
GET /repos/{o}/{r}/actions/runs/{run}/artifacts Artifacts de un run

No existen estos endpoints en Gitea 1.24 (sí en GitHub):

  • GET /actions/runs (sin scope a workflow)
  • GET /actions/runs/{id} (single run plano)
  • GET /actions/runs/{id}/jobs
  • GET /actions/runs/{id}/logs plano (existe pero devuelve zip — no usable)

Jobs

Endpoint Notas
GET /repos/{o}/{r}/actions/jobs/{job_id}/logs Texto plano del log de un job. Único path para leer logs desde la skill

No existe GET /actions/jobs/{job_id} (single job detail). Para saber qué job_id corresponde a un task_id, la skill hace probe (rango task_id ± 10, match por primera línea received task <task_id> ).

Artifacts

Endpoint Notas
GET /repos/{o}/{r}/actions/artifacts Lista artifacts del repo
GET /repos/{o}/{r}/actions/artifacts/{id} Single artifact metadata
GET /repos/{o}/{r}/actions/artifacts/{id}/zip Download artifact

Bloqueado por la skill (admin guard)

Estos endpoints requieren PAT admin del org. La skill aborta con exit 3 si los llamás (override: export GITEA_USER_PAT=<temporal>):

Endpoint Verbo
/admin/* cualquiera
/orgs/{org}/actions/secrets/* GET/PUT/DELETE
/orgs/{org}/actions/variables/* GET/POST/PUT/DELETE
/repos/{o}/{r}/actions/secrets/* GET/PUT/DELETE
/repos/{o}/{r}/actions/variables/* GET/POST/PUT/DELETE

Códigos de error comunes

HTTP Causa Qué hacer
401 PAT inválido / revocado Re-correr setup.sh (puede haber agarrado el duplicado equivocado en bitwarden)
403 Scope insuficiente del PAT (típico: read:issue faltante) Regenerar PAT con scopes correctos, re-correr setup.sh, o pedir PAT admin temporal
404 Repo/PR/run no existe (o no tenés acceso) Verificar el path y los args
422 Body POST inválido (ej. PR sin head/base) Revisar schema
404 page not found (texto crudo) Endpoint no existe en Gitea 1.24 (ej. /actions/runs/{id}/jobs) Usar el endpoint alternativo (/actions/tasks, probe de job_id)

Querystring params típicos

  • Paginación: ?page=N&limit=N. Default page=1, limit=10 (varía por endpoint).
  • Sort (en algunos endpoints): ?sort=newest|oldest|...
  • State: ?state=open|closed|all (PRs, issues)

Referencias