Add gitea-api-access skill for agent authentication
Versioned so any future agent can learn how to authenticate and use the Gitea API. Includes credential helper setup, SSH config, and all common API operations.
This commit is contained in:
parent
1b4ba18e88
commit
ca79a67eb9
239
skills/gitea-api-access/SKILL.md
Normal file
239
skills/gitea-api-access/SKILL.md
Normal file
@ -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":"<sha_se_atualizando>"}' \
|
||||||
|
"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
|
||||||
|
```
|
||||||
Loading…
Reference in New Issue
Block a user