Agrega gitea_skill: skill para operar Gitea self-hosted (scripts API BOM-safe + push headless sin persistir token, SKILL/TOOLS/api-index). Actualiza CLAUDE.md, README.md, .env.example.
This commit is contained in:
urieljareth
@@ -0,0 +1,125 @@
|
||||
---
|
||||
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.)
|
||||
Reference in New Issue
Block a user