diff --git a/skills/gitea-api-access/SKILL.md b/skills/gitea-api-access/SKILL.md new file mode 100644 index 0000000..242b161 --- /dev/null +++ b/skills/gitea-api-access/SKILL.md @@ -0,0 +1,239 @@ +--- +name: gitea-api-access +description: "GUIA DEFINITIVO para agentes Hermes acessarem o Gitea do homelab (gitea.hackerfortress.cc). Qualquer agente que precise de Git (clone, push, PRs, issues, repos) DEVE usar esta skill. Baseado em github-auth mas adaptado para self-hosted Gitea." +category: github +--- + +# Gitea — Guia de Acesso para Agentes Hermes + +## Identidade + +| Campo | Valor | +|-------|-------| +| **Usuário** | `hestia` | +| **Email** | `hestia@hestia.com` | +| **Senha** | `%SLH&7$$Cb5OBc` | +| **URL** | `https://gitea.hackerfortress.cc` | +| **SSH Porta** | `2222` (não 22) | +| **Repo inicial** | `hestia/homelab-docs` | + +--- + +## Método Padrão: Git Clone/Push HTTPS + +Este é o método **OBRIGATÓRIO** para todos os agentes. Não use SSH sem necessidade. + +### Regra do `%` — CRÍTICO + +A senha contém `%SLH` — o `%` **DEVE** ser escapado como `%25` em qualquer URL. + +``` +# CERTO (escapado): +https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/hestia/repo.git + +# ERRADO (vai falhar): +https://hestia:%SLH&7$$Cb5OBc@gitea.hackerfortress.cc/hestia/repo.git +``` + +### Clone de um Repositório + +```bash +git clone https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/hestia/homelab-docs.git +``` + +### Push de Alterações + +```bash +# Entra no repo +cd homelab-docs + +# Configura identity (primeira vez) +git config user.name "hestia" +git config user.email "hestia@hestia.com" + +# Faz alterações, commit +git add . +git commit -m "descrição da mudança" + +# Push — credeenciais na URL +git push https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/hestia/homelab-docs.git +``` + +### Configure o Credential Helper (recomendado) + +Para não precisar digitar a URL comcredenciais toda vez: + +```bash +git config --global credential.helper store +# Escrevecredencial +echo "https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc" > ~/.git-credentials +``` + +Após isso, `git push` e `git pull` funcionam semcredenenciais explícitas. + +--- + +## Criar um Novo Repositório + +### Opção 1: Via Web UI (indicado para agents) + +1. Navegar para https://gitea.hackerfortress.cc/repo/create +2. Login com hestia / %SLH&7$$Cb5OBc +3. Preencher nome e descrição +4. Criar + +### Opção 2: Via API (para automation) + +```bash +curl -s -X POST \ + -H "Content-Type: application/json" \ + -d '{"name":"nome-do-repo","description":"...","private":false}' \ + "https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/api/v1/user/repos" +``` + +--- + +## Operações Comuns + +### Listar Repositórios do Usuário + +```bash +curl -s "https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/api/v1/user/repos" +``` + +### Criar Issue + +```bash +curl -s -X POST \ + -H "Content-Type: application/json" \ + -d '{"title":"Bug encontrado","body":"Descrição","labels":["bug"]}' \ + "https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/api/v1/repos/hestia/repo/issues" +``` + +### Listar Issues + +```bash +curl -s "https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/api/v1/repos/hestia/repo/issues" +``` + +### Criar Pull Request + +```bash +curl -s -X POST \ + -H "Content-Type: application/json" \ + -d '{"title":"Feature XYZ","body":"Descrição","head":"feature-branch","base":"main"}' \ + "https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/api/v1/repos/hestia/repo/pulls" +``` + +### Obter Branch + +```bash +curl -s "https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/api/v1/repos/hestia/repo/branches" +``` + +### Obter Conteúdo de Arquivo + +```bash +curl -s "https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/api/v1/repos/hestia/repo/contents/README.md" +``` + +### Criar/Atualizar Arquivo (create_or_update) + +```bash +# PUT = criar ou atualizar +curl -s -X PUT \ + -H "Content-Type: application/json" \ + -d '{"content":"bmFzZGUG","message":"Atualiza README","sha":""}' \ + "https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/api/v1/repos/hestia/repo/contents/README.md" +``` + +> `content` é Base64-encoded. `bmFzZGUG` = "nasdeG" em Base64. + +--- + +## SSH (método alternativo) + +Se precisar de SSH (para CI/CD por exemplo): + +```bash +# Gerar chave (uma vez) +ssh-keygen -t ed25519 -C "hestia@gitea" -f ~/.ssh/gitea_ed25519 -N "" + +# Adicionar ~/.ssh/gitea_ed25519.pub no Gitea: +# User Settings → SSH / GPG Keys → Add Key + +# Configurar ~/.ssh/config +Host gitea + HostName gitea.hackerfortress.cc + User git + Port 2222 + IdentityFile ~/.ssh/gitea_ed25519 + +# Clone SSH +git clone gitea:hestia/repo.git +# ou +git clone ssh://git@gitea.hackerfortress.cc:2222/hestia/repo.git +``` + +--- + +## Fluxo Típico de um Agent + +``` +1. Agent recebe task que exige Git +2. Carrega esta skill (gitea-api-access) +3. Identifica se precisa criar repo ou usar existente +4. Se repo existe: clone com URL-encoded password +5. Faz trabalho local (criar arquivos, editar) +6. Commit com message descritiva +7. Push de volta +``` + +--- + +## armadilhas + +### `%` na senha +- Sempre escaping como `%25` em URLs +- Em scripts Python: `"%SLH&7$$Cb5OBc"` funciona diretoporque é string literal +- No shell: `$$` vaza para o PID — usar aspas duplas NÃO interpola `$$` +- Exemplo shell: `echo "https://hestia:%SLH&7$$Cb5OBc@..."` → o `$$` vaza + +### Sessão expirada +- Browser sessions expiram. Se o browser não está logado, fazer login novamente comcredenciais + +### Repo vazio +- Repos novos começam vazios (0 commits). Clone funciona mas `git log` retorna vazio + +### Gitea API Bearer Token +- Gitea 1.22.6 **não suporta** OAuth2 password grant por padrão (retorna 404) +- Não tentar `POST /api/v1/oauth2/token` com grant_type=password +- Usar sempre URL-encoded credentials em vez de Bearer tokens + +--- + +## Repositórios Existentes + +| Repo | URL | Descrição | +|------|-----|-----------| +| homelab-docs | https://gitea.hackerfortress.cc/hestia/homelab-docs | Documentação do homelab | + +--- + +## Referência Rápida (resumo) + +```bash +# Clone +git clone https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/hestia/REPO.git + +# Push +git push https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/hestia/REPO.git + +# API listar repos +curl https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/api/v1/user/repos + +# API criar repo +curl -X POST -H "Content-Type: application/json" \ + -d '{"name":"novo-repo","private":false}' \ + https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/api/v1/user/repos +```