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¶
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¶
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¶
gh repo create --template. A comunidade pode usá-los.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}¶
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¶
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}¶
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/
├── 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.