147 lines
6.2 KiB
Markdown
147 lines
6.2 KiB
Markdown
# 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)
|
|
```json
|
|
{
|
|
"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)
|
|
```json
|
|
{
|
|
"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
|
|
|
|
- Spec oficial: https://docs.gitea.com/api/1.24/
|
|
- Swagger JSON de la instancia: `https://gitea.nucleoriofrio.com/swagger.v1.json`
|
|
(descargá con curl + python para inspeccionar paths nuevos)
|
|
- Cuenta del bot: https://gitea.nucleoriofrio.com/claudecode0
|
|
- Org NucleOS: https://gitea.nucleoriofrio.com/NucleOS
|