pulse-memory/skills/gitea-api/SKILL.md

Gitea API — Skill

Automate Gitea via REST API — auth, repos, issues, users, webhooks.

🎯 O que esta skill faz

• Autenticação na API Gitea de todas as formas suportadas
• Gerenciar tokens de API (criar, listar, revogar)
• CRUD de repositórios, issues, pull requests
• Gerenciar usuários, organizações, webhooks
• OAuth2 como provider e como consumer

Fonte oficial: https://docs.gitea.com/development/api-usage

---

🔐 Autenticação — 5 métodos

Gitea aceita os 5 métodos abaixo. Todos usam o mesmo token de API.

1. HTTP Basic (username + senha)

curl -u "username:password" https://gitea.host/api/v1/user

2. HTTP Basic + OTP (2FA habilitado)

curl -u "username:password" \
     -H "X-Gitea-OTP: 123456" \
     https://gitea.host/api/v1/user

3. Header Authorization: token ...

curl -H "Authorization: token 9fcb1158165773dd..." \
     https://gitea.host/api/v1/user

Nota histórica: Gitea exige a palavra token antes do hash (não é Bearer).

4. Query param token=...

curl "https://gitea.host/api/v1/user?token=9fcb1158165773dd..."

5. Query param access_token=...

curl "https://gitea.host/api/v1/user?access_token=9fcb1158165773dd..."

OAuth2 access tokens também funcionam nos métodos 3, 4 e 5.

6. HTTP Signature com SSH key

# Assina a requisição com chave SSH privada — draft-cavage-http-signatures
curl -H "Signature: keyId=\"ssh-rsa AAA...\",..." https://gitea.host/api/v1/user

Chave SSH pública deve estar registrada na conta do usuário. Ver go-sdk para implementação de referência.

---

🔑 Criar token de API

Pela UI (recomendado)

https://gitea.host/user/settings/applications → Create New Token

O token é exibido apenas uma vez (toast). Não é possível reexibi-lo.

Pela API (requer senha + Basic Auth)

curl -H "Content-Type: application/json" \
     -d '{"name":"meu-token","scopes":["all"]}' \
     -u "Roberto:senha123" \
     https://git.octal.tec.br/api/v1/users/Roberto/tokens

Resposta:

{"id":1,"name":"meu-token","sha1":"9fcb1158165773dd...","token_last_eight":"...e37d"}

⚠️ sha1 = o token real, retornado apenas uma vez.

Scopes / Permissões

Permissões podem ser read:<perm> ou write:<perm>. write implica read.

Scope	Descrição
activitypub	ActivityPub (federated social)
admin	Admin geral
issue	Issues
misc	Miscelânea
notification	Notificações
organization	Organizações
package	Pacotes
repository	Repositórios
user	Dados do usuário
all	Todas as permissões (read + write)

Exemplo com permissões específicas:

-d '{"name":"token-custom","scopes":["write:repository","read:issue","read:user"]}'

---

📋 Listar tokens

# O sha1 vazio é intencional — Gitea nunca retorna o token completo em listagens
curl -u "Roberto:senha123" \
     https://git.octal.tec.br/api/v1/users/Roberto/tokens

Resposta:

[
  {"name":"dev","sha1":"","token_last_eight":"........"},
  {"name":"prod","sha1":"","token_last_eight":"........"}
]

---

🗂️ Endpoints principais

Usuário autenticado

GET  /api/v1/user              # dados do usuário logado
GET  /api/v1/users/:username   # dados públicos de um usuário

Repositórios

GET    /api/v1/users/:username/repos         # listar repos do usuário
POST   /api/v1/user/repos                    # criar repo (autenticado)
GET    /api/v1/repos/:owner/:repo            # detalhes do repo
DELETE /api/v1/repos/:owner/:repo            # deletar repo

Issues

GET  /api/v1/repos/:owner/:repo/issues       # listar issues
POST /api/v1/repos/:owner/:repo/issues       # criar issue
GET  /api/v1/repos/:owner/:repo/issues/:index # detalhes

Pull Requests

GET  /api/v1/repos/:owner/:repo/pulls
POST /api/v1/repos/:owner/:repo/pulls

Organizações

GET  /api/v1/orgs/:orgname
POST /api/v1/orgs/:orgname

Webhooks

GET  /api/v1/repos/:owner/:repo/hooks
POST /api/v1/repos/:owner/:repo/hooks

Gerenciamento de usuários (admin)

GET    /api/v1/admin/users
POST   /api/v1/admin/users
PUT    /api/v1/admin/users/:username
DELETE /api/v1/admin/users/:username

---

🔄 Paginação

Endpoints de lista suportam page e limit. A resposta inclui o header Link com rel="next", rel="prev", rel="last", e x-total-count.

curl -v "https://gitea.host/api/v1/repos/search?limit=1&page=2"

< link: <...?limit=1&page=2>; rel="next", <...?limit=1&page=5252>; rel="last"
< x-total-count: 5252

---

👑 Sudo (admin impersonando usuário)

Usuários admin podem executar requisições em nome de outro usuário:

# Parâmetro de query
curl -H "sudo: outro_username" https://gitea.host/api/v1/users/outro_username

# Ou header
curl -H "Sudo: outro_username" https://gitea.host/api/v1/users/outro_username

---

📚 Referências

• Swagger UI: https://gitea.host/api/swagger
• OpenAPI JSON: https://gitea.host/swagger.v1.json
• Go SDK oficial: https://gitea.com/gitea/go-sdk
• Fonte código auth: https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go

---

💡 Dicas

Dica	Por quê
Usar scopes: ["all"] para automação total	Evita ter que listar cada permissão
Token nunca é reexibido — guarde com segurança	Só aparece uma vez na UI ou na resposta da API
X-Gitea-OTP header só quando 2FA ativo	Sem 2FA, não precisa
Sempre use HTTPS com o token	Token em query string pode ser logado por proxies