How the repositories fit together

Airframe is not one program but seven git repositories, each owning one part of the platform, plus the repository of this website. They are all public on GitLab under gitlab.com/projectairframe. This page is the map: what each repository is for, how they depend on each other, and who may change each one. Every repository then has its own page.

The seven repositories in one sentence each

• catalog holds the intent: which products, teams and people exist, and who owns what. Everything else is derived from it.
• landing-zone builds the cloud foundation: the organization’s folders and policies, the networks, the project factories that create every product’s projects, the identities and the audit trail. It also holds the platform’s specification and handbook.
• control-plane runs the machinery of change: the gate, the executor, the pipeline components every repository includes, the policy pack, and the roots that configure GitLab.
• golden-path holds the product template, which generates a new product’s repository in Java, Node or Python, and the Terraform modules products build with.
• operations runs what keeps products observable: the telemetry pipeline, the dashboards and alert rules in Grafana, and the scheduled jobs such as the daily cost report.
• platform-skills teaches every coding agent the platform’s patterns, as skills a coding agent loads, each with tests.
• security-policies holds GitLab’s group-wide policies: the jobs injected into every pipeline, and the rules for who must approve a merge.

The website repository holds this site. It is not part of the platform, but it runs on it: it deploys through the same gate and pipeline as everything else.

How they connect

Read the map from the left.

The catalog drives three repositories. When a change to the catalog merges, its pipeline starts the pipelines of landing-zone, operations and control-plane in turn. Each of them reads the catalog and makes its own part match it: projects and groups, then dashboards, then repositories. The reconcilers page explains that chain.

Five repositories shape every product repository. A product’s repository is generated from golden-path’s template. Its pipeline includes control-plane’s components, which plan, apply, build and promote. security-policies injects the validation and the gate’s check, which the product cannot remove. And the product’s projects, identities and dashboards come from landing-zone and operations.

Releases tie the tooling together. control-plane, golden-path, the modules, security-policies and platform-skills are released together, as one release that names the exact commit of each. Every repository’s pipeline file says which release it uses.

platform-skills is used by people’s tools, not by pipelines. A developer’s coding agent loads the skills while working in any repository; the skills are tested against the policy pack of the release they pin.

Who changes each repository

Every change to every repository is a merge request, and none can merge with only its author’s approval. The differences are in who must approve:

• The platform repositories, landing-zone, control-plane, golden-path, operations, platform-skills and the website, need the approval of the platform team. The design asks for two approvals; while one person runs the platform it is one, and the number returns to two in the live catalog when a second maintainer joins.
• The catalog follows its own ownership model: a product file is approved by its team or its leads, a budget rise by a domain lead, a lifecycle change by two people, and the catalog’s structure by two members of the platform team. The catalog page lists the rules.
• security-policies is the break-glass. It holds the approval rules themselves, so it is the one repository the gate does not judge, and its own pipelines carry no gate:integrity, so it merges even when the gate cannot be reached. A named person’s approval, never the author’s, is what protects it. Its page explains why.

Today, in every repository but security-policies, the gate’s approval is required too (the approval policy names each repository it covers, and a new one joins by merge request), and the gate gives it only once the owners the catalog names have approved the latest commit.

Who applies what

Most of the platform’s Terraform roots are applied by their repository’s own pipeline, on the protected main branch, each under its own identity. A few are not:

• three landing-zone roots, the organization’s policies, the audit configuration and the identities, are applied from a laptop under a time-boxed grant, and are planned every day to catch any drift;
• control-plane’s gitlab root, which holds the few GitLab settings fixed at the bootstrap, is applied from a laptop with the administrator’s short-lived token, and each run is logged.

Each repository’s page says which of its roots apply how.