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