--- 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 ```