From 5619b0b050d47ea91e131c8e199e689759e55cce Mon Sep 17 00:00:00 2001 From: Pulse Agent Date: Wed, 20 May 2026 10:39:52 -0300 Subject: [PATCH] =?UTF-8?q?feat(skills):=20gitea-api=20v1.0.0=20em=20devop?= =?UTF-8?q?s/=20=E2=80=94=20todos=20m=C3=A9todos=20de=20autentica=C3=A7?= =?UTF-8?q?=C3=A3o=20+=20scopes=20+=20endpoints?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/devops/README.md | 3 + skills/devops/gitea-api.md | 221 +++++++++++++++++++++++++++++++++++++ 2 files changed, 224 insertions(+) create mode 100644 skills/devops/README.md create mode 100644 skills/devops/gitea-api.md diff --git a/skills/devops/README.md b/skills/devops/README.md new file mode 100644 index 0000000..db5dc9c --- /dev/null +++ b/skills/devops/README.md @@ -0,0 +1,3 @@ +# Skills — DevOps + +- `gitea-api.md` — Autenticação e API Gitea completa diff --git a/skills/devops/gitea-api.md b/skills/devops/gitea-api.md new file mode 100644 index 0000000..f603d7a --- /dev/null +++ b/skills/devops/gitea-api.md @@ -0,0 +1,221 @@ +# 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) +```bash +curl -u "username:password" https://gitea.host/api/v1/user +``` + +### 2. HTTP Basic + OTP (2FA habilitado) +```bash +curl -u "username:password" \ + -H "X-Gitea-OTP: 123456" \ + https://gitea.host/api/v1/user +``` + +### 3. Header `Authorization: token ...` +```bash +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=...` +```bash +curl "https://gitea.host/api/v1/user?token=9fcb1158165773dd..." +``` + +### 5. Query param `access_token=...` +```bash +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 +```bash +# 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](https://gitea.com/gitea/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) +```bash +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**: +```json +{"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:` ou `write:`. `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: +```bash +-d '{"name":"token-custom","scopes":["write:repository","read:issue","read:user"]}' +``` + +--- + +## 📋 Listar tokens + +```bash +# 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**: +```json +[ + {"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`. + +```bash +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: + +```bash +# 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 |