Ir para o conteúdo

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}-apis ou {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 → Enable
  • Settings → Code security → Dependabot alerts → Enable
  • Settings → 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:

  1. LICENSE — Escolher antes de qualquer commit público

    MIT License
    Copyright (c) 2026 {empresa}
    ...
    

    Baixar de: https://www.apache.org/licenses/LICENSE-2.0.txt

  2. openapi.yaml — Spec first, mínimo 1 endpoint real

    openapi: "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"
    
  3. service.yaml — Service Master Record

    service:
      id: SVC-BR-001
      name: "{Nome do Serviço}"
      description: "{Descrição}"
      owner: founder
      lifecycle: alpha
      status: active
    
  4. README.md — O que é, como usar, como contribuir

  5. CHANGELOG.md

    # Changelog
    
    ## [Unreleased]
    
    ## [0.1.0] — 2026-01-01
    ### Added
    - Versão inicial
    
  6. SECURITY.md — Igual ao do .github/, mas específico desta API

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