# 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` |