Skip to content

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 check run, 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 four thin files in a customer repository's .github/workflows/ that call the engine at a pinned tag: tf-pr-ops-pr.yml and tf-pr-ops-unlock.yml (the dispatch composite action), and tf-pr-ops.yml and drift.yml (the reusable workflows). They stay stable across most engine releases. See The PR-ops engine.
Engine app The GitHub App whose token authenticates the checkout of the private engine repository and the prebuilt-binary download. Wired through ENGINE_APP_CLIENT_ID and ENGINE_APP_PRIVATE_KEY. 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: the private nrit-tf-pr-ops core, called through the public nrit-solutions/tf-pr-ops entrypoint at the same tag. It runs plan, apply, the gates, and the drift sweep. It surfaces on a pull request through App check runs 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 check run. 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 check; it is the only engine check 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 quiet (conftest ships no active policy, checkov soft-fails, infracost never gates), so they report without blocking until you enforce them. 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 labeled by its path under live/. See projects.yml schema.
Reusable workflow mode The default consumption model. The customer repository holds no engine code; two callers reference the engine's reusable workflows with uses: and an engine_ref, two pin its dispatch composite action, and at run time the engine installs the tfpr binary for that tag and checks the engine repo out into $TFPR_ENGINE_DIR for the gate scripts. 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 one-line result headline first, then pre-plan output, the plan in a collapsible block, a change summary, the exact /apply instructions, and the validation checks with the gate findings. Each run posts a fresh comment and minimizes the superseded one as Outdated, so the newest report is the one that reads. 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 tree in at a tag, Go source included, and runs the workflows directly, with no uses: and no engine_ref; the tfpr binary is built from the vendored source. $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.