Agrega gitea_skill: skill para operar Gitea self-hosted (scripts API BOM-safe + push headless sin persistir token, SKILL/TOOLS/api-index). Actualiza CLAUDE.md, README.md, .env.example.

2026-07-19 09:35:52 -06:00
parent f587a8baa2
commit 3b7209dcc1
11 changed files with 823 additions and 0 deletions
@@ -0,0 +1,66 @@
+# Gitea API quick reference (v1.26.x)
+
+Base URL: `$GITEA_URL/api/v1` (default `https://gitea-hjwh0svsoo9p5w5kj2j6b1bd.urieljareth.org/api/v1`).
+Auth header: `Authorization: token <GITEA_TOKEN>` (also accepts `Bearer` on 1.16+).
+Docs (Swagger): `$GITEA_URL/api/swagger` (browsable in a browser).
+
+## Verified 2026-07-19 on this instance
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/version` | GET | Server version (anonymous). Returns `{"version":"1.26.2"}`. |
+| `/user` | GET | Authenticated user. Proves token. |
+| `/settings/api` | GET | Pagination/limits config. |
+| `/repos/search?limit=50` | GET | All repos visible to the token. |
+| `/repos/{owner}/{name}` | GET | Single repo (404 if missing or no access). |
+| `/user/repos` | POST | Create repo under auth user. |
+| `/orgs/{org}/repos` | POST | Create repo under an org. |
+| `/repos/{owner}/{name}` | PATCH | Update description, visibility, default branch. |
+| `/repos/{owner}/{name}` | DELETE | Delete repo. |
+| `/repos/{owner}/{name}/branches` | GET | List branches. |
+| `/repos/{owner}/{name}/branch protections` | POST | Branch protection rules. |
+| `/repos/{owner}/{name}/releases` | GET/POST | List / create releases. |
+| `/repos/{owner}/{name}/tags` | GET | List tags. |
+| `/repos/{owner}/{name}/hooks` | GET/POST | Webhooks (e.g. Coolify pull). |
+| `/repos/{owner}/{name}/mirror-sync` | POST | Sync a mirror repo. |
+| `/repos/migrate` | POST | Migrate/mirror from GitHub/GitLab/etc. |
+| `/users/{username}/tokens` | POST | Create a new app token (needs username+password or admin). |
+| `/orgs` | GET | List orgs. |
+| `/admin/users` | GET | List users (admin only). |
+
+## Token scopes (Gitea 1.20+ fine-grained)
+
+Tokens carry scopes. The current skill token (`GITEA_TOKEN` in `.env.local.ps1`)
+needs at minimum: `read:repository`, `write:repository`, `read:user`. Create at
+`$GITEA_URL/user/settings/applications` (or via API `/users/{user}/tokens` with
+basic auth). Verify scopes with:
+
+```powershell
+.\gitea_skill\scripts\Test-GiteaConnection.ps1
+```
+
+## Auth header convention
+
+Gitea's canonical header is `Authorization: token <T>` (note: literal `token`,
+not `Bearer`). This differs from GitHub/Coolify. `Invoke-GiteaApi.ps1` uses the
+canonical form. `Bearer` also works on 1.16+ but stick to `token` for max
+compat.
+
+## Git push with token (headless, no wincred)
+
+The token is NOT persisted into `.git/config` by `Sync-GiteaRemote.ps1`. It is
+sent via a one-shot `http.extraHeader`:
+
+```powershell
+git -c "http.extraHeader=Authorization: token $env:GITEA_TOKEN" `
+    -c "credential.helper=" `
+    push -u gitea main
+```
+
+If you prefer wincred (so plain `git push` works afterwards), seed it once:
+
+```powershell
+cmdkey /generic:"git:$env:GITEA_URL" /user:"$env:GITEA_USER" /pass:"$env:GITEA_TOKEN"
+```
+
+But note: the skill scripts do not require this. They work headlessly.