← Volver al listado de tecnologías ← Índice de Forgejo

API REST de Forgejo

Por: Artiko
forgejoapirestautomatizacioncurl

API REST de Forgejo

Forgejo expone una API REST completa que permite automatizar cualquier operacion que se puede hacer desde la interfaz web. Es compatible con la API de Gitea, por lo que herramientas y SDKs escritos para Gitea funcionan sin cambios.

Swagger UI integrado

Forgejo incluye documentacion interactiva de la API accesible directamente desde el navegador:

https://tu-forgejo.com/api/swagger

Desde esa interfaz puedes explorar todos los endpoints, ver los parametros requeridos y ejecutar llamadas de prueba autenticandote con tu token. Es el punto de partida recomendado para explorar la API.

La version actual de la API es v1. Todos los endpoints comienzan con /api/v1/.

Autenticacion

Hay tres formas de autenticarse con la API.

Token en header (recomendado)

Genera un token desde tu perfil en Settings > Applications > Access Tokens.

curl -H "Authorization: token TU_TOKEN_AQUI" \
  https://tu-forgejo.com/api/v1/user

Token en query param

Util para integraciones rapidas o pruebas, aunque menos seguro porque el token queda expuesto en logs de servidor:

curl "https://tu-forgejo.com/api/v1/user?token=TU_TOKEN_AQUI"

Basic Auth

curl -u "usuario:contrasena" \
  https://tu-forgejo.com/api/v1/user

No recomendado para automatizacion. Usar tokens es preferible porque se pueden revocar sin cambiar la contrasena.

Endpoints principales

PrefijoDescripcion
/api/v1/reposRepositorios
/api/v1/userUsuario autenticado
/api/v1/users/{username}Usuario especifico
/api/v1/orgsOrganizaciones
/api/v1/adminAdministracion (requiere admin)
/api/v1/issuesIssues globales
/api/v1/repos/{owner}/{repo}/pullsPull Requests

Ejemplos con curl

Listar repositorios del usuario autenticado

TOKEN="tu_token"
BASE="https://tu-forgejo.com/api/v1"

curl -s -H "Authorization: token $TOKEN" \
  "$BASE/repos/search?limit=50&page=1" | jq '.data[].full_name'

Obtener informacion del usuario autenticado

curl -s -H "Authorization: token $TOKEN" "$BASE/user" | jq '{login, email, is_admin}'

Crear un repositorio

curl -s -X POST \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mi-nuevo-repo",
    "description": "Creado via API",
    "private": true,
    "auto_init": true,
    "default_branch": "main"
  }' \
  "$BASE/user/repos" | jq '{full_name, html_url}'

Crear un issue

curl -s -X POST \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Bug encontrado en produccion",
    "body": "Descripcion detallada del problema.",
    "assignees": ["usuario1"]
  }' \
  "$BASE/repos/mi-org/mi-repo/issues" | jq '{number, title, html_url}'

Listar Pull Requests abiertos

curl -s -H "Authorization: token $TOKEN" \
  "$BASE/repos/mi-org/mi-repo/pulls?state=open&limit=20" | \
  jq '.[] | {number, title, user: .user.login}'

Automatizacion: crear repositorios en batch

El siguiente script lee una lista de nombres desde un archivo y crea cada repositorio en una organizacion:

#!/usr/bin/env bash
set -euo pipefail

TOKEN="${FORGEJO_TOKEN:?Variable FORGEJO_TOKEN no definida}"
BASE="${FORGEJO_BASE_URL:?Variable FORGEJO_BASE_URL no definida}/api/v1"
ORG="${1:?Indica el nombre de la organizacion como primer argumento}"
REPOS_FILE="${2:?Indica el archivo con nombres de repos como segundo argumento}"

while IFS= read -r repo_name; do
  [[ -z "$repo_name" || "$repo_name" == \#* ]] && continue

  echo "Creando: $repo_name"

  response=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
    -H "Authorization: token $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{
      \"name\": \"$repo_name\",
      \"private\": true,
      \"auto_init\": true,
      \"default_branch\": \"main\"
    }" \
    "$BASE/orgs/$ORG/repos")

  if [[ "$response" == "201" ]]; then
    echo "  OK: $repo_name creado"
  else
    echo "  ERROR: $repo_name - HTTP $response"
  fi

done < "$REPOS_FILE"

Uso:

# repos.txt contiene un nombre por linea
FORGEJO_TOKEN=xxx FORGEJO_BASE_URL=https://forgejo.ejemplo.com \
  ./crear-repos.sh mi-organizacion repos.txt

Rate Limiting

Por defecto Forgejo no tiene rate limiting habilitado. Para configurarlo, edita app.ini:

[api]
ENABLE_SWAGGER = true
MAX_RESPONSE_ITEMS = 50
DEFAULT_PAGING_NUM = 20

[rate_limit]
ENABLE = true
LIMIT = 300
WINDOW = 60

Cuando se supera el limite, la API responde con HTTP 429. Los headers X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset informan el estado actual del limite.

SDKs disponibles

SDK oficial en Go

El SDK oficial es go-forgejo/forgejo:

go get codeberg.org/forgejo/go-forgejo

Es el mas completo y se mantiene en sincronismo con la API.

Clientes comunitarios

Para proyectos nuevos en Python o JS, verificar la compatibilidad con la version de Forgejo instalada antes de elegir un cliente.

Siguiente: Capitulo 19: Webhooks y Migracion

← Volver al listado de tecnologías ← Índice de Forgejo