homelab-docs/skills/gitea-api-access/SKILL.md

name	description	category
gitea-api-access	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.	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

git clone https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/hestia/homelab-docs.git

Push de Alterações

# 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:

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)

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

curl -s "https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/api/v1/user/repos"

Criar Issue

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

curl -s "https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/api/v1/repos/hestia/repo/issues"

Criar Pull Request

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

curl -s "https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/api/v1/repos/hestia/repo/branches"

Obter Conteúdo de Arquivo

curl -s "https://hestia:%25SLH&7$$Cb5OBc@gitea.hackerfortress.cc/api/v1/repos/hestia/repo/contents/README.md"

Criar/Atualizar Arquivo (create_or_update)

# 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):

# 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)

# 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