126 lines
4.8 KiB
Markdown
126 lines
4.8 KiB
Markdown
---
|
|
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.)
|