Proxmox-Coolify-Manager/gitea_skill/SKILL.md

name, description

name

description

gitea-agent

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 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 for the verified endpoint cheatsheet. Full Swagger at $GITEA_URL/api/swagger.

Common workflows

Push an existing local repo to Gitea (one shot)

. .\.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

. .\.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

$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.)