Repository Structure and Documentation Standard

Defines a consistent repository layout, documentation baseline, ownership model, change history, and operational evidence for cloud engineering repositories.

Purpose

This standard defines the minimum structure and documentation required for repositories that contain infrastructure, platform configuration, deployment automation, policy, operational tooling, or cloud architecture assets. Consistency reduces onboarding time, review defects, and operational dependency on individual contributors.

Normative language

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, and MAY are normative:

• MUST / MUST NOT: mandatory for in-scope platforms and workloads.
• SHOULD / SHOULD NOT: expected unless a documented risk-based exception is approved.
• MAY: optional and selected according to workload requirements.

Where a cloud-provider feature cannot implement a requirement directly, the implementation MUST provide an equivalent control and record the equivalence in the architecture decision record (ADR).

Repository principles

1. A repository has an explicit product boundary. Its scope, owner, consumers, and lifecycle MUST be clear.
2. Documentation is part of the change. Code that changes behavior MUST update relevant documentation in the same review.
3. Operational ownership is visible. A responder MUST be able to find support, deployment, rollback, and escalation information without tribal knowledge.
4. Generated and authored content are distinguished. Generated files MUST be reproducible and marked as generated.
5. Repository access follows least privilege. Administrative permissions and bypass rights MUST be limited and reviewed.

Mandatory requirements

Standard repository model

A typical layout is:

.
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── CODEOWNERS
├── docs/
│   ├── architecture.md
│   ├── operations.md
│   └── adr/
├── src/ or infrastructure/
├── modules/ or components/
├── examples/
├── tests/
├── policies/
├── scripts/
└── .github/, .gitlab/, or pipelines/

Detailed implementation standard

Repository boundary selection

A repository SHOULD align to a deployable product, reusable module, policy bundle, or clearly owned platform component. A monorepo MAY be used when components share ownership, release cadence, tooling, and access requirements. Multiple repositories SHOULD be used when access boundaries, lifecycle, regulatory classification, or deployment authority differ.

The chosen model MUST be documented. Repository sprawl without cataloging and ownership is non-compliant; a monorepo that grants excessive access is also non-compliant.

README minimum content

The README MUST answer:

• What problem does this repository solve?
• What is explicitly in and out of scope?
• Who owns and supports it?
• What are the prerequisites and supported versions?
• How is it tested, deployed, upgraded, and rolled back?
• What identities and secrets are required?
• Where are architecture, operations, and incident documents?

Architecture and ADRs

Architecture documentation MUST identify trust boundaries, dependencies, data flows, deployment units, stateful components, recovery assumptions, and external integrations. ADRs MUST record context, decision, alternatives, consequences, date, and status. Superseded ADRs MUST remain available and point to the replacing decision.

Operational documentation

Production repositories MUST include or link to runbooks for deployment, rollback, credential failure, state recovery, capacity constraints, and common incidents. Runbooks MUST use role names rather than personal names and SHOULD contain validation commands and expected results.

Documentation quality controls

Documentation MUST avoid undocumented acronyms, stale screenshots, and copy-pasted commands containing real identifiers or secrets. Commands SHOULD be safe by default and MUST clearly label destructive operations. Examples MUST use placeholders that cannot be mistaken for production values.

Multi-cloud implementation mapping

Provider products are implementation examples, not exemptions from the normative requirements. Equivalent services MAY be used when they satisfy the same control objective.

Validation

Adoption checklist

• Define repository product boundary and owner.
• Create README, CONTRIBUTING, SECURITY, and CODEOWNERS.
• Protect the default branch.
• Add architecture, operations, and ADR documentation.
• Add changelog or release notes.
• Configure secret, dependency, and link scanning.
• Document generation commands and avoid hand-edited generated files.
• Register metadata in the enterprise catalog.

Assurance evidence

Evidence MUST be reproducible and retained according to the enterprise records schedule. Acceptable evidence includes:

• version-controlled configuration and policy;
• pipeline logs and approval records;
• policy evaluation results;
• configuration snapshots or inventory exports;
• test and recovery reports;
• dashboards with query definitions; and
• approved ADRs and exception records.

Screenshots alone SHOULD NOT be treated as primary evidence when machine-readable evidence is available.

Governance, exceptions, and enforcement

The Cloud Center of Excellence owns this standard. Platform engineering, security, reliability, application, data, and FinOps teams are accountable for implementing controls within their scope.

Exceptions MUST:

1. identify the unmet requirement ID;
2. describe business justification and quantified risk;
3. define compensating controls;
4. name an accountable owner;
5. include an expiry date not exceeding 180 days; and
6. be approved by the control owner and the relevant risk authority.

Expired exceptions are non-compliant. Automated policy checks SHOULD block new non-compliant deployments. Existing non-compliance MUST be tracked through a remediation backlog with owners and due dates.

Review cycle

This document MUST be reviewed at least annually and after a material change to cloud-provider capabilities, regulatory obligations, enterprise risk tolerance, or the operating model. Changes MUST preserve requirement identifiers where the underlying control intent remains unchanged.

Related topics

• Cloud Security and Zero-Trust Standard
• Resource Naming and Tagging Standard
• Backup, Recovery, and Resilience Standard

References

• GitHub documentation: About code owners
• GitHub documentation: About protected branches
• Keep a Changelog
• Architecture Decision Records
• Microsoft Azure Well-Architected Framework
• AWS Well-Architected Framework
• GCP Well-Architected Framework
• OCI Cloud Adoption Framework