126 lines
4.8 KiB
Markdown
126 lines
4.8 KiB
Markdown
# Gitea — Tooling
|
|
|
|
All commands assume PowerShell from the project root. Load env first:
|
|
|
|
```powershell
|
|
. .\.env.local.ps1
|
|
```
|
|
|
|
Required env vars (in `.env.local.ps1`, gitignored):
|
|
|
|
- `GITEA_URL` — base URL, e.g. `https://gitea-hjwh0svsoo9p5w5kj2j6b1bd.urieljareth.org`.
|
|
- `GITEA_USER` — auth user (informational; `GITEA_TOKEN` encodes the identity).
|
|
- `GITEA_TOKEN` — app token with `read:repository`, `write:repository`,
|
|
`read:user` scopes (generate at `$GITEA_URL/user/settings/applications`).
|
|
|
|
## Smoke test
|
|
|
|
```powershell
|
|
.\gitea_skill\scripts\Test-GiteaConnection.ps1
|
|
```
|
|
|
|
Calls `/version`, `/user`, `/settings/api`, `/repos/search`. Exits 1 on any
|
|
FAIL — gate operational work on this.
|
|
|
|
## Read-only
|
|
|
|
```powershell
|
|
# Who am I?
|
|
.\gitea_skill\scripts\Invoke-GiteaApi.ps1 -Path "/user"
|
|
|
|
# List visible repos
|
|
.\gitea_skill\scripts\Get-GiteaRepo.ps1 -List
|
|
|
|
# Get one repo (owner defaults to auth user)
|
|
.\gitea_skill\scripts\Get-GiteaRepo.ps1 -Name Proxmox-Coolify-Manager
|
|
.\gitea_skill\scripts\Get-GiteaRepo.ps1 -Owner urieljareth -Name MP-Manager
|
|
|
|
# Search
|
|
.\gitea_skill\scripts\Get-GiteaRepo.ps1 -Search manager
|
|
|
|
# Branches + tags
|
|
.\gitea_skill\scripts\Invoke-GiteaApi.ps1 -Path "/repos/urieljareth/MP-Manager/branches"
|
|
.\gitea_skill\scripts\Invoke-GiteaApi.ps1 -Path "/repos/urieljareth/MP-Manager/tags"
|
|
```
|
|
|
|
## Create a repo (idempotent)
|
|
|
|
```powershell
|
|
.\gitea_skill\scripts\New-GiteaRepo.ps1 -Name my-app -Description "demo" [-Private] [-NoAutoInit]
|
|
```
|
|
|
|
If the repo already exists, prints its URL and returns the existing object
|
|
(no failure). `-NoAutoInit` skips the Gitea-side README so you can push an
|
|
existing local history without conflicts.
|
|
|
|
## Push a local repo to Gitea (headless, token NOT persisted)
|
|
|
|
```powershell
|
|
.\gitea_skill\scripts\Sync-GiteaRemote.ps1 `
|
|
-AppPath .\my-app `
|
|
-Name my-app `
|
|
-RemoteName gitea `
|
|
-CreateIfMissing [-Private] [-Force]
|
|
```
|
|
|
|
What it does:
|
|
|
|
1. Ensures `urieljareth/<Name>` exists (creates if `-CreateIfMissing`).
|
|
2. Adds (or updates) the `gitea` remote with the **clean** HTTPS URL — **no
|
|
token in `.git/config`**.
|
|
3. Pushes the current branch with a **one-shot** `http.extraHeader=Authorization:
|
|
token <T>` and a blanked `credential.helper`. The token never reaches disk.
|
|
|
|
`-RemoteName gitea` (default) coexists with a GitHub `origin`. To replace an
|
|
existing `origin` that already points at Gitea (as in this manager repo),
|
|
pass `-RemoteName origin`.
|
|
|
|
### If you prefer wincred for interactive pushes (one-time)
|
|
|
|
```powershell
|
|
cmdkey /generic:"git:$env:GITEA_URL" /user:"$env:GITEA_USER" /pass:"$env:GITEA_TOKEN"
|
|
```
|
|
|
|
After that, plain `git push` works. The skill scripts do NOT require this —
|
|
they work headlessly out of the box.
|
|
|
|
## Low-level API
|
|
|
|
```powershell
|
|
# GET
|
|
.\gitea_skill\scripts\Invoke-GiteaApi.ps1 -Path "/repos/urieljareth/MP-Manager/releases"
|
|
|
|
# POST with body
|
|
$body = @{ name = "v1.0.0"; tag_name = "v1.0.0" } | ConvertTo-Json -Compress
|
|
.\gitea_skill\scripts\Invoke-GiteaApi.ps1 -Method POST `
|
|
-Path "/repos/urieljareth/MP-Manager/releases" -BodyJson $body
|
|
|
|
# Raw (status + headers + body string)
|
|
.\gitea_skill\scripts\Invoke-GiteaApi.ps1 -Path "/user" -Raw
|
|
```
|
|
|
|
`Invoke-GiteaApi.ps1` uses `curl.exe --data-binary @<tmpfile>` (UTF-8 no BOM)
|
|
so Gitea's JSON parser never trips on a BOM — same pattern as
|
|
`Invoke-GitHubApi.ps1`.
|
|
|
|
## Commands that always require confirmation
|
|
|
|
- Creating a repo (`New-GiteaRepo.ps1` warns if it already exists).
|
|
- Any `git push` (`Sync-GiteaRemote.ps1` asks unless `-Force`).
|
|
- Any Gitea `POST`/`PATCH`/`DELETE` (repo, release, hook, branch protection).
|
|
- Mirror/migrate operations.
|
|
- Deleting a repo (no Coolify-side recycle bin — data is gone).
|
|
|
|
`-Force` skips the interactive prompts. Use only after manually reviewing the plan.
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Likely cause | Fix |
|
|
|---------|--------------|-----|
|
|
| `GITEA_TOKEN not set` | `.env.local.ps1` not loaded | `. .\.env.local.ps1` |
|
|
| `401`/`403` on writes | Token lacks `write:repository` | Regenerate token with the right scope at `$GITEA_URL/user/settings/applications` |
|
|
| `invalid character '\u00ef'` | Body sent with a BOM | Already handled by `Invoke-GiteaApi.ps1` (uses `[IO.File]::WriteAllText` no-BOM); do not switch to `Set-Content -Encoding utf8` |
|
|
| `git push` prompts for credentials | The one-shot header was overridden by a stored helper | The script blanks `credential.helper` for the push; if you configured wincred manually, that's fine too. If a different helper intercepts, run from a clean shell. |
|
|
| `404` creating repo under an org | Org does not exist or token lacks access | Create the org first at `$GITEA_URL/org/create` |
|
|
| Cloudflare 5xx on Gitea URL | Tunnel routing or the Gitea container is down | `coolify_skill/scripts/Get-CoolifyDockerStatus.ps1 -Filter gitea`; tunnel is dashboard-managed, see `docs/runbooks/cloudflare-tunnel.md` |
|