Pulse Agent
222 lines
5.7 KiB
Markdown
222 lines
5.7 KiB
Markdown
# 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:<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:
|
|
```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 |
|