Ir para o conteúdo

Estrutura da GitHub Organization


Repositórios por Stage

A tabela abaixo mostra quais repositórios existem em cada estágio de crescimento. Comece apenas com o que o Stage 0 exige.

Repositório Stage 0 Stage 1 Stage 2 Stage 3
.github ✅ ✅ ✅ ✅
docs-company ✅ ✅ ✅ ✅
templates ✅ ✅ ✅ ✅
api-{nome} (primeiro) ✅ ✅ ✅ ✅
docs-governance — ✅ ✅ ✅
data-{nome} — ✅ ✅ ✅
infra-core — ✅ ✅ ✅
api-{nome}-spec — — ✅ ✅
sdk-{linguagem} — — ✅ ✅
svc-status — — ✅ ✅

Grupo 0 — Organization-level (Stage 0)

.github

.github Public
Repositório especial da Organization. Community health files, issue templates, PR templates e reusable workflows compartilhados entre todos os repositórios.
Stage 0 ✅ MVP obrigatório @maintainers: admin @developers: write

Conteúdo:

.github/
├── profile/
│   └── README.md                  ← página pública da Organization
├── ISSUE_TEMPLATE/
│   ├── bug_report.yml
│   ├── feature_request.yml
│   ├── incident.yml
│   └── data_quality.yml
├── PULL_REQUEST_TEMPLATE.md
├── workflows/
│   ├── reusable-openapi-lint.yml
│   ├── reusable-markdown-lint.yml
│   ├── reusable-yaml-validate.yml
│   └── reusable-release.yml
└── SECURITY.md                    ← security disclosure policy

Evolução: Novos workflows reutilizáveis são adicionados conforme necessidade. O profile/README.md é o cartão de visita público da Organization.


docs-company

docs-company Private
Documentação corporativa central: políticas, processos, legal, continuidade de negócio. Não é documentação de API — é documentação interna da empresa.
Stage 0 ✅ MVP obrigatório @developers: read @security: write (policies)

Conteúdo:

docs-company/
├── README.md
├── company/
│   ├── vision.md
│   ├── mission.md
│   └── values.md
├── policies/
│   ├── POL-SEC-001-security-policy.md
│   ├── POL-ACC-001-access-control.md
│   ├── POL-CHG-001-change-management.md
│   └── POL-INC-001-incident-management.md
├── processes/
│   ├── PROC-REL-001-release-process.md
│   ├── PROC-INC-001-incident-response.md
│   └── PROC-CHG-001-change-process.md
├── legal/
│   ├── NOTICE.md                  ← [LEGAL REVIEW REQUIRED]
│   └── third-party-licenses.md
└── continuity/
    └── BCP-001-business-continuity.md

Evolução: Começa com 2–3 documentos. Expande somente quando houver necessidade operacional real.


templates

templates Public
Templates reutilizáveis para novos repositórios de API, dataset e serviço. Base para gh repo create --template. A comunidade pode usá-los.
Stage 0 ✅ MVP obrigatório Criado ANTES do primeiro api-*

Conteúdo:

templates/
├── README.md
├── api-template/
│   ├── README.md
│   ├── openapi.yaml
│   ├── service.yaml
│   ├── CHANGELOG.md
│   ├── SECURITY.md
│   └── docs/
│       ├── getting-started.md
│       ├── authentication.md
│       └── errors.md
├── data-template/
│   ├── README.md
│   ├── dataset.yaml
│   └── sources/
└── service-record-template/
    └── service.yaml

Grupo 1 — APIs

api-{nome}

api-{nome} Public → pode virar Private
Cada API é um repositório independente com código, OpenAPI spec, documentação, testes e service.yaml. A visibilidade pode mudar para private quando o código torna-se comercial.
Stage 0 ✅ Um repo por API Criado a partir do template

Estrutura interna:

api-brasil-geo/
├── README.md               ← porta de entrada do usuário externo
├── openapi.yaml            ← contrato público (spec first)
├── service.yaml            ← Service Master Record
├── CHANGELOG.md
├── SECURITY.md             ← security disclosure
├── LICENSE
├── CONTRIBUTING.md
├── docs/
│   ├── getting-started.md
│   ├── authentication.md
│   ├── rate-limits.md
│   ├── errors.md
│   ├── versioning.md
│   ├── deprecation.md
│   ├── sla.md              ← quando houver SLA formal
│   └── data/
│       ├── overview.md
│       ├── sources.md
│       └── freshness.md
├── src/                    ← código da API
├── tests/
└── .github/
    └── workflows/          ← CI/CD específico desta API

api-{nome}-spec

api-{nome}-spec Public
Criado apenas quando o código da API torna-se privado mas a especificação OpenAPI deve permanecer pública para a comunidade. Separação entre implementação e contrato.
Stage 2 Quando código vira private

Quando criar: A API cresce, ganha clientes pagantes e o código é movido para private. A spec OpenAPI permanece acessível publicamente neste repositório separado, mantendo a comunidade capaz de integrar sem acesso ao código.


Grupo 2 — Dados

data-{nome}

data-{nome} Public ou Private
Pipelines de coleta, normalização e publicação de datasets. Separado da API para versionamento independente. Visibilidade depende do caráter dos dados.
Stage 1 Um repo por dataset @data-engineers: write

Conteúdo:

data-brasil-municipios/
├── README.md
├── dataset.yaml                   ← Dataset Record
├── sources/
│   ├── SRC-BR-001-ibge.yaml
│   └── SRC-BR-002-correios.yaml
├── fields/
│   └── municipio.yaml
├── pipelines/
├── quality/
│   └── quality-report.md
├── lineage/
│   └── lineage.md
└── CHANGELOG.md

Grupo 3 — Infraestrutura

docs-governance

docs-governance Public
Governança do projeto open source. GOVERNANCE, CONTRIBUTING, CODE_OF_CONDUCT, ROADMAP público e ADRs.
Stage 1 Quando houver projeto público @maintainers: admin
docs-governance/
├── README.md
├── GOVERNANCE.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── ROADMAP.md
├── adr/
│   ├── ADR-0001-hybrid-multirepo.md
│   ├── ADR-0002-openapi-first.md
│   └── ADR-0003-data-lineage-model.md
└── decisions/
    └── DECISION-LOG.md

infra-core e svc-status

Repositório Visibilidade Stage Finalidade
infra-core Private 1 IaC, deploy, provisionamento
svc-status Public 2 Status page pública dos serviços

svc-status é necessário quando há SLA formal com clientes e obrigações de comunicação de incidentes.


Próximo passo

Com os repositórios definidos, consulte Teams & Permissões para ver como o acesso é controlado em cada um.