# Contexto para a sua IA: desenvolvedor no dsgit

Cole este arquivo inteiro na sua IA (Claude Code, Codex ou outra), por exemplo no CLAUDE.md, no AGENTS.md ou no inicio da conversa. Depois dele, a IA sabe trabalhar no dsgit sem outra explicacao.
Versao 1.0, 18/11/2026. Marcas: [conferido] = comando rodado contra o kit e a API 17.0.1 do dsgit; [a validar] = escrito conforme a documentacao, ainda nao rodado. Em duvida, vale o que a IA medir; registre a divergencia.

## 1. O que e o dsgit
Plataforma propria de Git e CI/CD da DS Marketing (Forgejo 17.0.1, mesma API do Gitea), em https://dsgit.dsmarketing.com.br. Vai substituir o Bitbucket Cloud. Tem repositorios, pull requests, issues, Actions (workflows em `.forgejo/workflows/`) e runners de varios tamanhos. Esta em piloto: o dsgit e espelho; **nenhum workflow faz deploy real** nem usa credencial de producao.
Voce e um usuario comum do dsgit: entra, clona, abre PR, le o CI. Nao altera a plataforma (isso e dos desenvolvedores de infraestrutura).

## 2. Entrar
- **Google:** botao "Entrar com Google" com o e-mail da empresa (dominios liberados). Se o e-mail ja tem conta local, entra nela; senao cria conta nova sem permissao em nenhuma organizacao, e o administrador precisa adiciona-la. [conferido]
- **Usuario e senha:** o administrador cria a conta. Senha: minimo 12 caracteres, com maiuscula, minuscula e numero. Troque no primeiro login (Configuracoes, Conta). [conferido]
- **Esqueci a senha:** `/user/forgot_password` (e-mail pelo Amazon SES; hoje so chega para e-mails do dominio da empresa). Outro dominio: peca ao administrador. [conferido]
- **2FA (opcional hoje):** `/user/settings/security`. Cadastre antes de ele virar obrigatorio, senao perde o acesso. [conferido]

## 3. Como pegar as suas proprias chaves (token pessoal)
O token e a sua senha para Git, API, CLI e MCP. Cada pessoa gera o seu; ninguem passa token a ninguem.
1. Entre no dsgit e abra `/user/settings/applications` (avatar, Configuracoes, Aplicacoes, "Gerar novo token"). [conferido]
2. Nome que diga onde ele vive, ex.: `pc-minha-maquina`.
3. Escopos minimos para o dia a dia [conferido no kit]:

| Escopo | Nivel | Para que |
|---|---|---|
| repository | leitura e escrita | clone, push, PRs, execucoes, logs, reexecutar (so leitura se for so ler) |
| issue | leitura e escrita | issues e comentarios em PR |
| user | leitura | o kit conferir quem voce e |
| organization | leitura | listar organizacoes e times |
| notification | leitura | avisos (MCP) |
| package | leitura | baixar pacotes |

Nada de admin, nem escrita em user/organization. Esse token **nao cria repositorio** (403): peca ao administrador ou crie pela tela.
4. **Restringir por repositorio:** no mesmo formulario ha o acesso a repositorios (todos, so publicos ou repositorios especificos). Para token de automacao marque so os repositorios necessarios. [conferido na tela; o efeito na API a validar]
5. Copie o token: aparece uma unica vez. Nao cole em arquivo, repositorio, chat nem variavel de ambiente permanente.
6. **Onde ele fica guardado:** no cofre de credenciais do sistema (Gerenciador de Credenciais no Windows, Keychain no macOS, libsecret no Linux), pelo `git credential`. O kit faz isso. Excecao do kit: a CLI `tea` guarda o token em texto na configuracao dela no perfil do usuario (limite da ferramenta; `sair` remove).
7. Se vazar: apague em `/user/settings/applications` e gere outro. Trocar de token: `DSGIT_TOKEN_FILE=<arquivo> bash entrar.sh` (ou `sair` e `entrar`) e apague o antigo.
8. Chaves SSH em `/user/settings/keys` **nao servem para o Git** (o SSH do Git e desligado). Git e so por HTTPS.

## 4. Kit para a sua maquina (entrar / sair)
Precisa de Git 2.36 ou mais (no Windows, Git for Windows, que traz Git Bash e o cofre) e `curl`. Claude Code e opcional (sem ele o MCP nao e registrado). Os arquivos estao em `https://dsgit.dsmarketing.com.br/assets/central/kit/` (pagina "Contexto para a sua IA" da Central). Baixe `entrar.ps1`, `entrar.sh`, `sair.ps1`, `sair.sh`, `dsgit` e `compilar-mcp-windows.sh` na mesma pasta.
- Windows (PowerShell): `.\entrar.ps1` (se bloquear: `powershell -ExecutionPolicy Bypass -File .\entrar.ps1`)
- Linux, macOS ou Git Bash: `bash entrar.sh`

Cole o token quando pedir (nao aparece). Rodar de novo e seguro. No fim o **autoteste** mostra 5 linhas PASS e `0 FAIL` (API, git ls-remote, CLI, MCP, Claude Code). Repetir depois: `dsgit teste`. Abra um terminal novo para valer os comandos. [conferido]
No Windows, na 1a vez, o kit compila o `forgejo-mcp` (4 a 13 min, ~75 MB; nada e instalado fora da pasta temporaria). O kit grava em `~/.dsgit/bin` (tea 0.16.0, forgejo-mcp 2.30.2, comando `dsgit`), 3 chaves de `~/.gitconfig` so para este host, um bloco marcado `# >>> dsgit` no perfil do shell e o servidor MCP `dsgit` no Claude Code (escopo de usuario). Desfazer tudo: `bash sair.sh` ou `.\sair.ps1`, e apagar o token na tela.
Avisos: VPN da Under em tunel completo nao abre o dsgit (use a dividida). `tea actions runs view|logs` nao funciona com o Forgejo 17.

## 5. Regras para a IA (obrigatorias)
1. **Nunca** leia, imprima ou grave o token. Nao rode `git credential fill` nem abra a configuracao da `tea`. Use so `git`, `dsgit`, `tea` e o MCP: eles buscam o token no cofre sozinhos.
2. **Nunca** coloque segredo (senha, token, chave, `.env`) em repositorio, log, issue, PR ou conversa. O push com segredo e recusado (gitleaks): trate a recusa como alerta, remova o segredo, nao contorne; se o segredo era real, avise o administrador para rotacionar.
3. **Um PR por tarefa**, com a chave do card (T-N) no nome da branch e nos commits.
4. **Nada de deploy real no piloto.** Nao use credencial de producao em workflow.
5. **Quando o CI falha:** leia o log da etapa que falhou (secao 7), corrija o causador, faca `git push`, e so reexecute sem mudar nada se a falha foi do runner. Nao desligue teste para passar.
6. Voce age como o usuario dono do token. Faca so o que ele pediu.
7. VPN, SSH nas maquinas, Grafana e cofre de servico **nao sao para desenvolvedor comum**. Se precisar, peca ao administrador do dsgit (ou a equipe de infraestrutura) e diga o motivo; nao tente contornar.
8. Alterar a plataforma (repositorios `dsgit/infra` e `dsgit/dispatcher`, VMs, borda, firewall, runners, cofre, AWS) e **zona perigosa**, so para desenvolvedores de infraestrutura. Se o pedido for esse e o usuario nao e um deles, pare e avise.

## 6. Git, CLI, MCP e API
**Git (HTTPS, sem pedir senha depois do kit):** `git clone https://dsgit.dsmarketing.com.br/<dono>/<repo>.git` [conferido]
**Comando `dsgit`** (no PowerShell tambem como `dsgit-prs`, `dsgit-runs`, `dsgit-log`, `dsgit-rerun`, `dsgit-api`). Sem `<dono>/<repo>`, usa o repositorio da pasta atual:
```
dsgit prs  <dono>/<repo>               # PRs abertos                                  [conferido]
dsgit runs <dono>/<repo>               # execucoes; anote o #N (e o id da execucao)   [conferido]
dsgit log  <N> <dono>/<repo> [etapa]   # jobs, etapas e log (etapa = numero)          [conferido]
dsgit rerun <N> <dono>/<repo>          # reexecuta (so execucao terminada)            [conferido]
dsgit api /user                        # API direta; aceita opcoes do curl            [conferido]
dsgit teste                            # autoteste                                    [conferido]
```
**CLI `tea`** (login `dsgit`): `tea pulls create --login dsgit --repo <dono>/<repo> --head minha-branch --base main --title "..." --description "..."`, `tea pulls ls`, `tea issues ls`, `tea repos ls` [conferido: pulls e repos]. Nao use `tea actions runs view|logs`.
**MCP:** servidor `dsgit` no Claude Code, ferramentas `mcp__dsgit__<nome>` (128 ferramentas). Conferir: `claude mcp get dsgit` (Connected). Fora do Claude Code: `dsgit mcp --cli list`, `dsgit mcp --cli <ferramenta> --args '<json>'`. [conferido]

| Tarefa | Ferramenta |
|---|---|
| listar / abrir PR | `list_repo_pull_requests`, `create_pull_request` (owner, repo, head, base, title, body) |
| ver diff e arquivos do PR | `get_pull_request_diff`, `list_pull_request_files` (owner, repo, index) |
| revisar / mesclar | `create_pull_review`, `merge_pull_request` [a validar] |
| issues e comentarios | `create_issue`, `list_repo_issues`, `create_issue_comment` (index = numero do PR ou da issue) |
| execucoes | `list_workflow_runs` (filtros status, event, head_sha), `get_workflow_run` (run_id) |
| disparar workflow manual | `dispatch_workflow` (workflow, ref; o workflow precisa de `workflow_dispatch`) [a validar] |
| nao tem no MCP | log de etapa e reexecutar: use `dsgit log` / `dsgit rerun` ou a API |

Escolha: MCP para PR, issue, arquivo, release; `dsgit` para log e reexecucao; API para o resto.
**API direta** (base `/api/v1`; erro HTTP = saida diferente de zero). O numero de execucao da API e o **id** (o #N de `dsgit runs`), nao o numero da URL da tela:
```
dsgit api "/repos/<dono>/<repo>/pulls?state=open"                              # listar PRs        [conferido]
dsgit api "/repos/<dono>/<repo>/pulls" -X POST -H 'Content-Type: application/json' -d '{"head":"minha-branch","base":"main","title":"T","body":"Texto"}'   # abrir PR [conferido]
dsgit api "/repos/<dono>/<repo>/actions/runs?limit=10&status=failure"          # execucoes         [conferido]
dsgit api "/repos/<dono>/<repo>/actions/runs/<N>/jobs"                         # jobs da execucao  [conferido]
dsgit api "/repos/<dono>/<repo>/actions/jobs/<J>/logs?step=1"                  # log de UMA etapa  [conferido]
dsgit api "/repos/<dono>/<repo>/actions/jobs/<J>/logs"                         # log do job        [conferido]
dsgit api "/repos/<dono>/<repo>/actions/runs/<N>/rerun" -X POST                # reexecutar (204)  [conferido]
dsgit api "/repos/<dono>/<repo>/actions/runs/<N>/cancel" -X POST               # cancelar          [a validar]
dsgit api "/repos/<dono>/<repo>/issues" -X POST -H 'Content-Type: application/json' -d '{"title":"T","body":"Texto"}'   # abrir issue [a validar]
dsgit api "/repos/search?limit=50"                                             # repositorios que voce ve [conferido]
```
Parametros de log: `step`, `attempt`, `q`/`qi` (filtro de texto), `format=text|ndjson`. Os caminhos acima existem no Swagger da versao 17 (https://code.forgejo.org/swagger.v1.json).

## 7. Consultar fila, deploys e projetos
Paginas da Central (https://dsgit.dsmarketing.com.br/assets/central/index.html): `filas.html` (esperando e rodando por rotulo de runner), `deploys.html` (execucoes de deploy, etapa atual, runner e resultado), `projetos.html` (organizacoes e repositorios que voce ve, PRs abertos). `como-usar.html` tem o passo a passo. O **Ao vivo** (`/assets/mapa/vivo.html`) mostra cada runner em uso ou livre e a fila. Dados de pessoas e repositorios so aparecem logado; sem login a pagina mostra so contadores. Pelo terminal, o mesmo vem de `dsgit runs` e da API (`actions/runs`, `actions/tasks`).
**Fluxo "o CI do meu PR falhou":** `dsgit runs <dono>/<repo>` (ache o `failure`) → `dsgit log <N> <dono>/<repo>` (qual job e etapa) → `dsgit log <N> <dono>/<repo> <etapa>` (so aquela) → corrija e `git push` → comente no PR (`create_issue_comment`).

## 8. Escrever workflow
Arquivo em `.forgejo/workflows/<nome>.yml`. Exemplo (mesmo formato dos workflows reais do projeto):
```yaml
name: testes
on:
  pull_request:
  workflow_dispatch:
concurrency:
  group: testes-${{ github.event.pull_request.number }}
  cancel-in-progress: true
jobs:
  testes:
    runs-on: m
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test
      - name: resumo do job
        run: echo "testes concluidos" >> "$GITHUB_STEP_SUMMARY"
```
- **Runner:** `runs-on` com UM rotulo: `p` (leve: lint, testes curtos), `m` (builds e suites medias), `g` (pesado), `xg` (nuvem spot para pico de fila, nunca para deploy), `xxg` (nuvem sob demanda, urgencia). Comece pelo menor que da conta. `xg` e `xxg` ainda nao tinham runner registrado em 18/11. Situacao real em `filas.html`.
- **Deploy:** `runs-on: estavel` (rotulo dos runners p, m e g, que nao somem no meio do job). Nunca em `xg`. Lista de rotulos (`[estavel, m]`) [a validar].
- **concurrency:** `group` + `cancel-in-progress: true` em CI de PR e de branch (cancela execucao antiga); em deploy use `cancel-in-progress: false` (nao interromper no meio) [a validar].
- **Cache:** `actions/cache` precisa de cache server no runner (ainda nao usado). Cache de imagem Docker: registro/espelho da zona; cache de dependencias: peca a infraestrutura. [a validar]
- **Artefatos:** `uses: code.forgejo.org/forgejo/upload-artifact@v4`; o `actions/upload-artifact@v4` oficial falha. O artefato **nao atravessa execucoes**, so vale dentro da mesma. [lido na analise do agentmaker]
- **Resumo do job:** escreva em `$GITHUB_STEP_SUMMARY`.
- **Etiqueta de projeto (centro de custo):** todo job e registrado com projeto = a organizacao do repositorio. Para cobrar de outro: variavel de Actions `DSGIT_PROJETO` no repositorio (Configuracoes, Actions, Variaveis; ou `POST /repos/<dono>/<repo>/actions/variables/DSGIT_PROJETO` [a validar]). Sem segredo nela. Quem le e o distribuidor (no ar, modo automatico).
- **Urgencia e pedido de runner:** branch `hotfix/<assunto>`, etiqueta `urgente` no PR ou priorizacao manual. Pedir `xg`/`xxg`: etiqueta `runner:xg` ou `runner:xxg` no PR (tem de chegar antes de o job existir); o card do Quadro tambem pode pedir. [medido 18/11: xg/xxg sobem por pedido no runs-on ou na entrada runner; etiqueta runner:xg no PR nao foi testada]
- Segredos de workflow: Configuracoes do repositorio, Actions, Segredos. Nunca no arquivo.
- Repositorios de documentacao nao rodam Actions (desligado por decisao).

## 9. A quem pedir o que voce nao tem
Acesso a organizacao ou repositorio, conta nova, senha, runner especifico, variavel de Actions: o administrador do dsgit. Alteracao na plataforma, VPN, SSH, painel de monitoramento: equipe de infraestrutura, por issue no repositorio `dsgit/infra` (ou pelo administrador, se voce nao o enxerga). Abra a demanda como issue com o que precisa, por que e o card.
