Run the pull-request linting and drift gauntlet against the resolved module: metadata -> initialize (Terraform) -> sync -> format -> transform -> lint -> check policy -> check convention -> validate -> docs.
Composition cmdlet. Resolves the module context once with Get-AvmModuleContext, then invokes the verb chain above in sequence against that same module root. Each step's structured result is captured. The overall Status is 'pass' only when every executed step reports Status='pass' (or didn't throw, for verbs that don't carry a Status field).
This is the broader sibling of Invoke-AvmPreCommit. It adds the credentialled policy evaluation and read-only drift checks used to verify that pre-commit output is current. Before any step runs, git status must report a clean working tree. Metadata validation runs after tool resolution but before the other steps. Missing or invalid root or child metadata aborts the chain without changing module files or reading indexes, regardless of StopOnFail, unless metadata is explicitly excluded with -ExcludeSteps.
ExcludeSteps omits named steps and tools needed only by those steps. Excluded steps remain visible as 'skipped' in the result and log. Excluding every step returns overall Status='skipped', not 'pass'.
When Terraform validation is enabled, an explicit initialize step
prepares each source example once after metadata and before the remaining
checks, reusing compatible locked dependency selections without requesting
upgrades. An incompatible locked selection fails initialization rather
than being silently upgraded. The validate step reuses that persistent
.terraform state.
Initialization has its own step log, result and duration, matching
pre-commit. Failure aborts the chain even without StopOnFail.
Excluding validate omits the initialize step; formatting needs only the
executable, while transform, lint and policy prepare their own working
directories.
The 'validate' step is a build-validation
pass ('terraform validate' / 'bicep build'), not a test run. Unit tests remain a
separate CI job so a failure produces one actionable signal and
all contributors receive results without environment approval.
The convention step requires a tests/unit/*.tftest.hcl fixture,
preventing an empty unit tier from reading as a green gauntlet.
Set AVM_TF_UTILITY_MIGRATION=preserve when pre-commit used that setting to retain exact utility sources, versions and migration-related inputs/provider bindings. Unset or migrate retains default migrations. Invalid nonempty values fail configuration. Preservation does not exclude any checks, relax exact-pin validation or approve dependency changes; ordinary policy evaluation remains enabled.
After metadata validation, the managed-files sync step (terraform only) in drift-check mode (-CheckDrift): unlike pre-commit, which reconciles the governed files by writing them, pr-check writes nothing and instead treats any needed add/update/remove as Status='fail'. This makes stale governed files a hard CI failure so the module is refreshed before merge rather than silently rewritten in CI. For Bicep the sync step is unsupported and skipped. Bicep policy runs the required and advisory PSRule baselines when its repository config and selected test sources are available. Its public namePrefix test token defaults to 'gci'; other missing inputs fail the check. Bicep policy, convention, and docs must report inspectable results rather than skipping. The required docs step checks README drift and confirms every selected source-backed README was rendered; source-less READMEs are reported separately.
The sync step also gates on the managed-files release recorded in '.avm/managed-files-version.json': governed files are compared against that pinned release, and a superseded major version is reported as a drift issue so the run fails until the repository adopts it with 'avm pre-commit -Upgrade'.
Status semantics (same as Invoke-AvmPreCommit):
- 'pass' : step returned Status='pass' (or didn't throw for format).
- 'fail' : step returned Status='fail'.
- 'error' : step threw an unexpected exception; the chain aborts.
- 'skipped' : step was explicitly excluded or threw AvmNotSupportedException because it does not apply to the selected ecosystem.
- configuration exceptions are failures, not skips.
By default the gauntlet is fail-soft: a step that returns Status='fail' does NOT abort subsequent steps - the caller gets the full picture in one run. A step that THROWS (non- AvmConfigurationException) IS fatal and aborts the rest of the chain. Set -StopOnFail to abort on the first Status='fail' instead.
Routed by the dispatcher: 'avm pr-check'.
avm pr-check
Invoke-AvmPrCheck [[-Path] <string>] [-Ecosystem <string>] [-AllowPathFallback] [-StopOnFail] [-ExcludeSteps <string[]>] [-ThrottleLimit <int>] [-SkipModuleVersionCheck] [<CommonParameters>]When set, accept a PATH-resolved tool binary that self-reports the lock-pinned version. Forwarded to each step.
| Property | Value |
|---|---|
| Type | Switch |
| Required | false |
| Position | named |
| Default value | False |
| Accept pipeline input | false |
| Accept wildcard characters | false |
Force the ecosystem selector. Defaults to 'auto'.
| Property | Value |
|---|---|
| Type | String |
| Required | false |
| Position | named |
| Default value | auto |
| Accept pipeline input | false |
| Accept wildcard characters | false |
Step names to skip: metadata, sync, format, transform, lint, check policy, check convention, validate, docs. Accepts an array; names are case-insensitive and duplicates are ignored. Unknown or empty names are rejected. Omit this parameter or supply an empty array to run every step. Excluding validate also omits the Terraform initialize step. Version and clean-working-tree checks always run.
| Property | Value |
|---|---|
| Type | String[] |
| Required | false |
| Position | named |
| Default value | @() |
| Accept pipeline input | false |
| Accept wildcard characters | false |
Working directory whose enclosing module to validate. Defaults to the current location.
| Property | Value |
|---|---|
| Type | String |
| Required | false |
| Position | 1 |
| Default value | $PWD.Path |
| Accept pipeline input | false |
| Accept wildcard characters | false |
Skip the PowerShell Gallery check that otherwise stops the command when a newer Avm.Authoring version is available. Writes a warning once.
| Property | Value |
|---|---|
| Type | Switch |
| Required | false |
| Position | named |
| Default value | False |
| Accept pipeline input | false |
| Accept wildcard characters | false |
When set, abort the chain on the first step whose Status is 'fail'. A throwing step is always fatal regardless of this flag.
| Property | Value |
|---|---|
| Type | Switch |
| Required | false |
| Position | named |
| Default value | False |
| Accept pipeline input | false |
| Accept wildcard characters | false |
Maximum number of independent Terraform transform targets, lint scopes, or policy examples to process at once. Defaults to four.
| Property | Value |
|---|---|
| Type | Int32 |
| Required | false |
| Position | named |
| Default value | 4 |
| Accept pipeline input | false |
| Accept wildcard characters | false |
avm pr-checkInvoke-AvmPrCheck -Path C:\repos\my-module -StopOnFailavm pr-check -ExcludeSteps @('check policy', 'docs')avm pr-check -Ecosystem terraform -ExcludeSteps 'check policy'Run the fork-compatible Terraform checks. Run unit tests separately with 'avm test unit'.
- `pscustomobject with:
- Path : the resolved module root
- Ecosystem : bicep | terraform
- Status : pass | fail | error | skipped
- Steps : array of { Step, Status, Error?, Result?, DurationMs }
- DurationMs : total wall-clock cost`
The reusable workflows run one shared unit-test job for fork and same-repository pull requests, independently of pr-check. Bicep pr-check runs the complete public gauntlet with no GitHub environment, subscription selection, Azure OIDC permission, secret map, or configured secret. The portable Bicep policy defaults are identical for local and CI invocations. Terraform fork pr-check excludes only check policy and its Conftest prerequisite.
Normal branch pr-check retains the full checks and credentials, using the pr-check environment for OIDC without required reviewers. Integration and end-to-end tests remain non-fork and approval-gated. Callers run the checks on pull-request opened, reopened, and synchronize events without a fork or draft exclusion. GitHub's separate fork-workflow approval policy still applies.
Publish a compatible Avm.Authoring release containing -ExcludeSteps before adopting this workflow revision. Older releases fail with upgrade guidance rather than running policy or silently omitting the other checks.