---
name: gitea-agent
description: Operate the local self-hosted Gitea instance (gitea-...urieljareth.org) for this Proxmox and Coolify Manager project. Use when Codex needs to create/list/search/mirror Gitea repositories, push a local project to Gitea headlessly (token in extraHeader, no wincred), inspect branches/releases/hooks, or wire a `gitea` remote alongside a GitHub `origin`. Distinct from coolify-deploy (which ships to Coolify) — this skill only manages the git hosting layer on Gitea.
---

# Gitea Agent

Use this project-local skill for Gitea work in this repository. The Gitea
instance lives behind the same Cloudflare tunnel as Coolify and is reachable
only via its public URL.

## Startup routine

1. Load private values: `. .\.env.local.ps1` (provides `GITEA_URL`, `GITEA_USER`,
   `GITEA_TOKEN`).
2. Run the smoke test: `.\gitea_skill\scripts\Test-GiteaConnection.ps1`.
3. Only after it passes, perform the requested operation.

## Local context (verified 2026-07-19)

- Gitea URL: `https://gitea-hjwh0svsoo9p5w5kj2j6b1bd.urieljareth.org`
- Gitea version: `1.26.2`
- Authenticated user: `urieljareth` (admin)
- Auth header: `Authorization: token <GITEA_TOKEN>` (canonical Gitea form;
  `Bearer` also works on 1.16+).
- The Gitea instance runs as a Coolify container inside LXC `102` on the
  Proxmox host `192.168.0.200`. Container-level work goes through
  `pct exec 102 -- docker ...` (see `coolify_skill`); this skill speaks only
  to the public REST API.
- Secrets live only in `.env.local.ps1` (gitignored). Never write tokens into
  Markdown, scripts, or `.git/config`.

## When to use

- "Push this project to Gitea" / "crea un repo en Gitea y sube esto"
- "List my Gitea repos" / "¿qué repos tengo en Gitea?"
- "Mirror this GitHub repo to Gitea" (`/repos/migrate`)
- "Set up a `gitea` remote alongside GitHub `origin`"
- "Create a release / tag on Gitea"

## When NOT to use

- Deploying an app to run on the server → use `deploy_skill/` (Coolify).
- Operating an already-deployed container → use `coolify_skill/`.
- Proxmox host / LXC maintenance → use `agent/`.

## Safety policy

- **Read-only by default**: prefer `Get-GiteaRepo.ps1` and GET endpoints before
  any write.
- **Confirm before mutating**: repo creation, visibility changes, branch
  protection, deletes, releases, and any `git push` require explicit
  confirmation unless `-Force` is supplied.
- **Never write secrets into the repo.** The token is injected per-invocation
  via `http.extraHeader` for pushes; it is NOT baked into remote URLs and NOT
  stored in wincred by these scripts.
- **No force-push to main** unless the operator explicitly asks.
- **State the rollback path** before destructive actions (delete repo, force
  push): once a Gitea repo is deleted the data is gone (no Coolify-side
  recycle bin).

## Tooling

See [`TOOLS.md`](TOOLS.md) for the full command reference. Core scripts:

- `scripts/Invoke-GiteaApi.ps1` — low-level REST wrapper (curl-based, BOM-safe).
- `scripts/Test-GiteaConnection.ps1` — smoke test (version + auth + repos).
- `scripts/Get-GiteaRepo.ps1` — list / search / get a repo.
- `scripts/New-GiteaRepo.ps1` — idempotent repo creation.
- `scripts/Sync-GiteaRemote.ps1` — wire a `gitea` remote + push headlessly.

## API reference

See [`references/api-index.md`](references/api-index.md) for the verified
endpoint cheatsheet. Full Swagger at `$GITEA_URL/api/swagger`.

## Common workflows

### Push an existing local repo to Gitea (one shot)

```powershell
. .\.env.local.ps1
.\gitea_skill\scripts\Sync-GiteaRemote.ps1 `
    -AppPath .\my-app `
    -Name my-app `
    -CreateIfMissing -Force
```

This creates `urieljareth/my-app` if missing, adds a `gitea` remote (so it
coexists with a GitHub `origin`), and pushes the current branch with a
one-shot auth header (token not persisted).

### Mirror a GitHub repo into Gitea

```powershell
. .\.env.local.ps1
$body = @{
    clone_addr      = "https://github.com/urieljarethbusiness-cpu/my-app.git"
    repo_owner      = "urieljareth"
    repo_name       = "my-app"
    service         = "github"
    mirror          = $true
    private         = $false
    wiki            = $false
    issues          = $false
    pull_requests   = $false
    releases        = $true
} | ConvertTo-Json -Compress
.\gitea_skill\scripts\Invoke-GiteaApi.ps1 -Method POST -Path "/repos/migrate" -BodyJson $body
```

### Add a Gitea webhook so Coolify auto-pulls on push

```powershell
$body = @{
    type = "gitea"
    active = $true
    events = @("push")
    config = @{ url = "https://coolify.urieljareth.org/webhooks/source.manual_webhook_secret_gitea"; content_type = "json" }
} | ConvertTo-Json -Depth 5 -Compress
.\gitea_skill\scripts\Invoke-GiteaApi.ps1 -Method POST `
    -Path "/repos/urieljareth/my-app/hooks" -BodyJson $body
```
(Replace the `manual_webhook_secret_*` segment with the real webhook URL from
the Coolify app's "Webhooks" section.)