67 lines
2.8 KiB
Markdown
67 lines
2.8 KiB
Markdown
# 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.
|