Run the standard pre-commit gauntlet against the resolved module: bicep: metadata -> format -> lint -> validate -> transform -> docs. terraform: metadata -> initialize -> sync -> check convention -> transform -> format -> docs.
Composition cmdlet. Resolves the module context once with Get-AvmModuleContext, then invokes the per-ecosystem step chain 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' (format reports an implicit pass when no errors are thrown).
The Terraform chain follows the legacy Terraform governance
pre-commit.porch.yaml philosophy: its initialize step prepares the shared
Terraform provider and Mapotf schema caches without running terraform init, then the managed-files sync and remaining checks stay offline
(check convention -> transform -> format -> docs). The sync step runs after metadata so the
rest of the chain sees the freshest governed files; it fetches the
managed-file source (the Azure/azure-verified-modules-tools repo by
default, overridable or pinned to a local path - see Invoke-AvmSync)
and writes any adds/updates/removals straight into the 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.
The two checks that require an
initialised working directory - lint (tflint) and validate
(terraform validate) - live in avm pr-check instead, mirroring
upstream porch, which runs tflint and the policy/plan checks in
pr-check rather than pre-commit.
Terraform utility migrations default to migrate. Set AVM_TF_UTILITY_MIGRATION=preserve to retain exact authored utility selections and their migration-related inputs/provider bindings. Keep the same setting for pr-check. Exact-pin validation and all other transformations and checks remain enabled.
Status semantics:
- 'pass' : step returned Status='pass' (or didn't throw for format).
- 'fail' : step returned Status='fail'.
- 'error' : step threw any exception other than AvmConfigurationException; the chain aborts.
- 'skipped' : step threw AvmConfigurationException - the engine is a deliberate placeholder for a future slice (e.g. bicep-docs). The chain CONTINUES and overall status is NOT marked failed by a skip.
By default the gauntlet is fail-soft: a step that returns Status='fail' (e.g. lint diagnostics) 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 pre-commit'.
avm pre-commit
Invoke-AvmPreCommit [[-Path] <string>] [-Ecosystem <string>] [-AllowPathFallback] [-StopOnFail] [-ThrottleLimit <int>] [-ManagedFilesRepo <string>] [-ManagedFilesRef <string>] [-ManagedFilesPath <string>] [-ManagedFilesLocalPath <string>] [-ConfigRepo <string>] [-ConfigRef <string>] [-ConfigPath <string>] [-ConfigLocalPath <string>] [-RepoId <string>] [-Upgrade] [-SkipManagedFilesVersionCheck] [-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 |
Direct local path to the managed-files config folder. Skips the config repo fetch and is forwarded only to the Terraform sync step.
| Property | Value |
|---|---|
| Type | String |
| Required | false |
| Position | named |
| Default value | |
| Accept pipeline input | false |
| Accept wildcard characters | false |
Path within the config repo to the folder holding 'config.json'. Forwarded only to the Terraform sync step.
| Property | Value |
|---|---|
| Type | String |
| Required | false |
| Position | named |
| Default value | |
| Accept pipeline input | false |
| Accept wildcard characters | false |
Git ref for the config repo. Forwarded only to the Terraform sync step.
| Property | Value |
|---|---|
| Type | String |
| Required | false |
| Position | named |
| Default value | |
| Accept pipeline input | false |
| Accept wildcard characters | false |
owner/name of the git repo holding the managed-files config folder. Forwarded only to the Terraform sync step.
| Property | Value |
|---|---|
| Type | String |
| Required | false |
| Position | named |
| Default value | |
| 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 |
Direct local path to the managed-files base folder. Skips the managed files git fetch and is forwarded only to the Terraform sync step.
| Property | Value |
|---|---|
| Type | String |
| Required | false |
| Position | named |
| Default value | |
| Accept pipeline input | false |
| Accept wildcard characters | false |
Path within the source repo to the managed-files base folder. Forwarded only to the Terraform sync step.
| Property | Value |
|---|---|
| Type | String |
| Required | false |
| Position | named |
| Default value | |
| Accept pipeline input | false |
| Accept wildcard characters | false |
Git ref to fetch for the managed files. Forwarded only to the Terraform sync step.
| Property | Value |
|---|---|
| Type | String |
| Required | false |
| Position | named |
| Default value | |
| Accept pipeline input | false |
| Accept wildcard characters | false |
owner/name of the git repo holding the managed files. Forwarded only to the Terraform sync step.
| 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 |
Repository id used to look up overlays/exclusions in config.json. Forwarded only to the Terraform sync step.
| Property | Value |
|---|---|
| Type | String |
| Required | false |
| Position | named |
| Default value | |
| Accept pipeline input | false |
| Accept wildcard characters | false |
Skip the managed-files release lookup and sync against whatever ref the normal precedence resolves. Forwarded only to the Terraform sync step.
| Property | Value |
|---|---|
| Type | Switch |
| Required | false |
| Position | named |
| Default value | False |
| 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 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 |
Move the repository to the latest managed-files release and restamp '.avm/managed-files-version.json'. Without it the sync stays on the recorded pin and only warns about newer patch or minor releases. Forwarded only to the Terraform sync step.
| Property | Value |
|---|---|
| Type | Switch |
| Required | false |
| Position | named |
| Default value | False |
| Accept pipeline input | false |
| Accept wildcard characters | false |
avm pre-commitInvoke-AvmPreCommit -Path C:\repos\my-module -StopOnFailavm pre-commit -Ecosystem terraform -ManagedFilesRepo Contoso/governance -ManagedFilesRef v1.2.3 -ConfigRepo Contoso/governance -ConfigRef v1.2.3 -RepoId avm-res-fooavm pre-commit -Ecosystem terraform -ManagedFilesLocalPath D:\gov\managed-files -ConfigLocalPath D:\gov\repository-config -RepoId avm-res-foo- `pscustomobject with:
- Path : the resolved module root
- Ecosystem : bicep | terraform
- Status : pass | fail | error
- Steps : array of { Step, Status, Error?, Result? }
- DurationMs : total wall-clock cost`