Quickstart — Dia 1¶
Se você tem um dia para preparar a estrutura mínima, execute nesta ordem.
Pré-requisitos¶
- Conta GitHub com permissão para criar uma Organization
- GitHub CLI (
gh) instalado e autenticado - Decisão sobre o nome da Organization (ex:
{empresa}-apisou{empresa}-br) - Decisão sobre a licença open source ⚠️
[LEGAL REVIEW REQUIRED]
Passo 1 — Criar a GitHub Organization¶
# Acessar: github.com/organizations/new
# Nome sugerido: {empresa}-apis ou {empresa}-br
# Plano: Free (suficiente para Stage 0/1)
Após criar, habilitar imediatamente:
Settings → Code security → Dependency graph→ EnableSettings → Code security → Dependabot alerts→ EnableSettings → Code security → Secret scanning→ Enable
Passo 2 — Criar Repositórios Base¶
# Autenticar com a Organization
gh auth login
# Criar os 4 repositórios base do Stage 0
gh repo create {org}/.github \
--public \
--description "Organization community health files"
gh repo create {org}/docs-company \
--private \
--description "Internal company documentation"
gh repo create {org}/templates \
--public \
--description "Repository templates for APIs and datasets"
gh repo create {org}/api-{nome} \
--public \
--description "API: {descrição da API}"
Passo 3 — Configurar Branch Protection em main¶
Para cada repositório api-*:
Settings → Branches → Add rule
Branch name pattern: main
✅ Require pull request before merging
✅ Require status checks to pass (após configurar CI)
✅ Do not allow bypassing the above settings
Por que usar PR mesmo solo?
PRs criam rastreabilidade de mudanças. O histórico de PRs é evidência de que mudanças foram revisadas antes de ir para produção — relevante para auditorias futuras.
Passo 4 — Criar Estrutura Mínima de Arquivos¶
.github/¶
# Em .github/SECURITY.md
cat > SECURITY.md << 'EOF'
# Security Policy
## Reporting a Vulnerability
To report a security vulnerability, please email: security@{empresa}.com
Do not open public issues for security vulnerabilities.
We will respond within 48 hours and work with you to resolve the issue.
EOF
# Em .github/PULL_REQUEST_TEMPLATE.md
cat > PULL_REQUEST_TEMPLATE.md << 'EOF'
## Descrição
<!-- O que esta PR faz? -->
## Tipo de mudança
- [ ] Bug fix
- [ ] Nova funcionalidade
- [ ] Breaking change
- [ ] Documentação
- [ ] Manutenção
## Checklist
- [ ] Código foi testado localmente
- [ ] OpenAPI spec foi atualizado (se aplicável)
- [ ] CHANGELOG.md foi atualizado
- [ ] Documentação foi atualizada (se aplicável)
EOF
api-{nome}/¶
Criar os seguintes arquivos na ordem:
-
LICENSE— Escolher antes de qualquer commit público -
openapi.yaml— Spec first, mínimo 1 endpoint realopenapi: "3.1.0" info: title: "{Nome da API}" version: "0.1.0" description: "{Descrição}" contact: email: "api@{empresa}.com" servers: - url: "https://api.{empresa}.com/v1" description: "Produção" paths: /health: get: summary: "Health check" operationId: "healthCheck" responses: "200": description: "API operacional" -
service.yaml— Service Master Record -
README.md— O que é, como usar, como contribuir -
CHANGELOG.md -
SECURITY.md— Igual ao do.github/, mas específico desta API -
docs/getting-started.md— Primeiros passos para o desenvolvedor externo
Passo 5 — Configurar Dependabot¶
Em cada api-*/.github/dependabot.yml:
version: 2
updates:
- package-ecosystem: "npm" # ajustar: pip, go, maven, etc.
directory: "/"
schedule:
interval: "weekly"
open-pull-requests-limit: 5
Passo 6 — Configurar GitHub Action para OpenAPI Validation¶
Em api-{nome}/.github/workflows/validate-openapi.yml:
name: Validate OpenAPI
on:
pull_request:
paths:
- "openapi.yaml"
push:
branches: [main]
paths:
- "openapi.yaml"
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validate OpenAPI spec
uses: swaggerhub-actions/swaggerhub-cli@v2
with:
args: api:validate --file openapi.yaml
Definição de "Pronto" para o Stage 0¶
Antes de considerar o Stage 0 completo, verificar cada item:
| Item | Como validar |
|---|---|
| GitHub Organization criada | URL acessível em github.com/{org} |
| 4 repositórios base existem | Listados na Organization |
Branch protection em main |
Settings → Branches → regra ativa |
openapi.yaml válido |
Testar em editor.swagger.io |
service.yaml preenchido |
Campos id, name, status não vazios |
LICENSE presente |
Arquivo LICENSE na raiz do api-* |
SECURITY.md presente |
Contém email de contato de segurança |
README.md claro |
Um terceiro consegue entender sem contexto |
| Dependabot habilitado | Insights → Dependency graph → Dependabot |
| Secret Scanning habilitado | Security → Secret scanning → Active |
| Pelo menos 1 PR mergeado | Processo de PR funcionando |
LEGAL REVIEW REQUIRED — Antes de ir ao ar
Se a API vai processar, coletar ou expor dados de pessoas físicas (mesmo indiretamente), consultar advogado especializado em LGPD antes do lançamento público.
Isso inclui:
- Logs de acesso com IP ou user agent
- Análise de padrões de uso vinculados a contas
- Qualquer enriquecimento que possa identificar pessoas
- Dados de empresas cujos titulares sejam pessoas físicas identificáveis
Próximos Passos após o Stage 0¶
Quando o Stage 0 estiver completo, volte ao Roadmap e avalie o que faz sentido para o Stage 1 com base no crescimento real da adoção.
Não antecipe documentos que ainda não têm uso operacional.