Glossary¶
The words this site uses, in alphabetical order. Where a term has an owning page, the definition links to it.
Four things are called a gate
The command gate, the approval gate, the merge gate, and the three plan gates are separate mechanisms with separate failure modes. Each has its own entry below, and Policy, security, and cost gates covers the plan gates in full.
| Term | Definition |
|---|---|
| Approval gate (apply gate) | The check that blocks /apply until the pull request meets the repository's required reviews. It reads GitHub's own review decision, so it is configured in branch protection or a ruleset, not in the engine. Every run also publishes it as the informational tf-pr-ops / approval commit status, which must never be made a required check. See The approval gate. |
| Archetype | A named bundle of policy assignments, policy definitions, policy set definitions, and role definitions. An archetype lists asset names only; it does not contain the assets and it does not decide scope. Scope comes from the architecture attaching it to a management group. See The vendored policy library. |
| Architecture (ALZ architecture definition) | The JSON file that declares the management group hierarchy and which archetypes each group gets. The platform ships one, nrit, which is the stock alz architecture reproduced in full plus the nrit_tags archetype on the intermediate root. architecture_name in landing-zones/main.tf selects it. See The vendored policy library. |
| Caller workflow | One of the two thin files in a customer repository's .github/workflows/ that call the engine's reusable workflows at a pinned tag: terraform-pr-ops.yml and drift.yml. They are about thirty lines each and stay stable across engine releases. See The PR-ops engine. |
| Catalog app | The GitHub App whose token authenticates the checkout of the private engine repository. Its variable and secret names, CATALOG_APP_CLIENT_ID and CATALOG_APP_PRIVATE_KEY, are historical: they are kept from a module catalog that no longer exists. See Self-hosted runner and the engine GitHub App. |
| Command gate | The first check on a comment command. /plan and /apply are accepted only from a comment whose GitHub author_association is OWNER, MEMBER, or COLLABORATOR. It answers "who is asking", and it is not a write-permission check. See Who can run a command. |
| Drift | A difference between the deployed tenant and the code that is supposed to describe it. A daily read-only sweep plans every unit and opens one GitHub issue per drifted unit, titled Drift: <label>. See Drift detection. |
| Engine | The PR-ops engine in the private nrit-tf-pr-ops repository. It runs plan, apply, the gates, and the drift sweep. It surfaces on a pull request through checks and commit statuses under the tf-pr-ops / prefix. See The PR-ops engine. |
| Foundation | The three units under live/_foundation/ that build the platform: management-resources, landing-zones, and amba. _foundation/ is not a management group; the underscore marks it as tenant-global. See The foundation units. |
| Gates | Four different things carry the name. The command gate decides who may type a command. The approval gate decides whether /apply may run. The merge gate decides whether the pull request may merge. The plan gates are the three post-plan checks on the plan itself. Each has its own entry here. |
| Impacted set | The units a run plans. A unit is impacted when its own directory changed, when a file it reads changed, or when it is downstream of an impacted unit through a dependencies block. Because every unit reads root.hcl, a one-line change there impacts the whole tree. See The impacted set. |
| Initiative | An Azure policy set definition: a group of policy definitions assigned together with shared parameters. The vendored library ships one, Enforce-Tag-Governance, with eleven members. See The vendored policy library. |
| Library (vendored library) | live/_foundation/landing-zones/lib/, a complete Azure Landing Zones library carried inside the customer repository. The alz provider reads it on top of the stock library, so a policy change is reviewable in the same diff as the code that consumes it. See The vendored policy library. |
| Live tree | Everything under live/. The folder tree mirrors the management group hierarchy, and each folder is named after the management group ID it represents. Position in the tree is the wiring: it decides inherited context and the state key. See The live tree. |
| Management group scope files | tenant.hcl, subscription.hcl, and region.hcl. They carry scope rather than resources: the tenant and root management group, the subscription a subtree deploys into, and the region and environment for a subtree. Units never include them directly; root.hcl walks up the tree and the nearest ancestor wins. See The live tree. |
| Merge gate | The tf-pr-ops / merge-gate commit status. It is green when the pull request has no Terraform changes, when every unit is a no-op, or when every impacted unit has been applied. Make it a required status check; it is the only engine status that should be required. See The merge gate. |
| Plan gates | The three post_plan checks that run against every plan and every drift plan: conftest for policy, checkov for security, and infracost for cost. All three start advisory, so they report without blocking. See Policy, security, and cost gates. |
| Project | The engine's word for a planning target. In this platform a project is a Terragrunt unit, discovered from the terragrunt: block in projects.yml and labelled by its path under live/. See projects.yml schema. |
| Reusable workflow mode | The default consumption model. The customer repository holds no engine code; the caller workflows reference the engine's reusable workflows with uses: and an engine_ref, and the engine checks its own scripts out at that tag into $TFPR_ENGINE_DIR. See The PR-ops engine. |
| Root contract | live/root.hcl, the single file every unit includes. It generates the backend, the providers, and a context.tf from the nearest scope files, and sets the state key from the unit's path. See The root contract. |
| Run report | The comment the engine posts for each unit on each run. It is ordered for scanning: a validation check first, then pre-plan output, the plan in a collapsible block, a change summary, the exact /apply instructions, and the gate findings. Each run posts a fresh comment, so the pull request keeps a history. See The plan comment. |
| Unit | A leaf folder containing a terragrunt.hcl. That is the whole definition. It pairs terragrunt.hcl, which wires the unit into the tree, with main.tf, which sources an Azure Verified Module at a pinned version. Each unit has its own state. See What a unit is. |
| Vendored mode | The escape hatch for a repository that cannot call the org-shared workflow. It copies the engine's .github/workflows/, .github/actions/setup-tools/, and scripts/ in at a tag and runs them directly, with no uses: and no engine_ref. $TFPR_ENGINE_DIR then falls back to the workspace, so hook paths still resolve, and the repository owns updates by re-copying at a new tag. See Vendored mode, the escape hatch. |
For the version numbers behind the pins, see Versions and upgrades.