Automating Azure Policy Reviews with Policy Linter, PowerShell and Copilot CLI

Azure Policy is one of those services that looks simple until you start authoring your own definitions. The JSON may be valid and the policy may deploy successfully, but that does not necessarily mean it is robust, safe to roll out or consistent across the resource API versions you support.

That is why the public release of the Azure Policy Linter is useful. It provides policy authors with fast, repeatable feedback on known issues, common pitfalls and established good practice before a definition is assigned to an environment.

Why the public release matters

Policy teams have often relied on documentation reviews, testing and operational experience to identify authoring problems. A publicly available linter makes many of those checks repeatable and allows them to run locally or as part of a delivery pipeline.

That lowers the barrier to adopting Policy as Code. It also gives teams a practical way to improve an existing policy estate without depending on every reviewer remembering every Azure Policy edge case.

Policy should be treated as code

If Azure Policy controls how resources can be deployed and configured, the definitions themselves should be managed with the same discipline as application or infrastructure code. They should live in source control, follow a review process and move through repeatable validation and deployment pipelines.

This creates a shared place to collaborate, a history of why a control changed and a single source of truth for deployment. More importantly, it creates an opportunity to catch problems before a policy reaches Azure. A definition that defaults to Deny, uses an unreliable alias or matches more resources than intended can have a much wider blast radius than a normal coding mistake.

What Azure Policy Linter does

The linter codifies knowledge that is otherwise spread across Azure Policy documentation, resource-provider behaviour and hard-won operational experience. It returns error, warning and informational findings that can be reviewed locally or used as a quality gate in continuous integration.

If the .NET SDK is already available, the tool can be installed globally:

dotnet tool install --global Microsoft.Azure.Policy.PolicyLinter.Cli 

A single definition can then be checked with:

policylinter C:\policies\policyDefinition.json 

Running the linter across a policy repository

Running the command against one file is useful while authoring, but most policy repositories contain a collection of definitions. I wrote a small PowerShell wrapper that discovers the policy files in a supplied folder, validates the prerequisites, creates the output directory when necessary and passes the collection to the linter in one run.

.\policylinter.ps1 -PoliciesDirectory .\policies -OutputDirectory .\output 

The core of the wrapper is deliberately small:

$policyPaths = @( 
    Get-ChildItem -LiteralPath $PoliciesDirectory -File | 
        Sort-Object FullName | 
        ForEach-Object FullName 
) 
 
& policylinter @policyPaths --output $resultPath 

The full, maintained PowerShell scripts are available in my Azure Policy code snippets repository.

Using Copilot CLI to create a readable assessment

The challenge with linter output is not generating it; it is making it easy to consume. Structured JSON is ideal for automation, but a pull-request reviewer, platform owner or governance lead often needs a concise view of the risk, affected files and next actions.

The second version of the wrapper parses and groups the findings before passing a deliberately reduced summary to Copilot CLI. Rather than sending the raw report, it extracts the rule identifier, severity, description, policy path and documentation reference. PowerShell calculates the exact counts and groups repeated findings before the model sees them.

This can then be push to Pull Requests for easy review and summary.

$analysisReport = [pscustomobject]@{ 
    fileCount      = @($linterResults.PSObject.Properties).Count 
    findingCount   = $findings.Count 
    severityCounts = $severityCounts 
    findings       = $groupedFindings 
} 

Design Explained: The linter supplies the facts, PowerShell performs deterministic counting and grouping, and Copilot explains the result. AI is an enrichment layer, not a validation dependency.

The prompt also treats the linter output as untrusted data, tells Copilot not to follow instructions contained within it and requests only a final Markdown report. If Copilot CLI is unavailable or fails, the original results.json remains available. You can get the full PowerShell version from chris-pateman/code-snippets

What the report looks like

In my example run, the linter returned 73 findings across 14 files: 25 warnings and 48 informational findings, with no error-level issues. The generated report reduced that output to a short set of review points: 

• 12 policy definitions had parameterised effects defaulting to Deny, increasing the risk of accidental enforcement. 

• Several field aliases were unavailable in older resource API versions. 

• Two definitions supported a deny-capable effect without an audit counterpart for safer rollout. 

• One type comparison used a broad matching operator, and another finding highlighted a read-only field alias. 

This is much easier to consume than a long JSON file. It gives a reviewer enough information to understand the risk and decide where to investigate, while the original machine-readable results remain the source of truth.

Where this fits in a delivery workflow

The immediate use case is local validation, but the same approach fits naturally into a pull request or deployment pipeline:

• Run the linter whenever Azure Policy files change.

• Retain results.json as a pipeline artefact and auditable source of truth.

• Publish the Markdown assessment for reviewers.

• Decide which severities or individual rules should block a merge and which should remain advisory.

I would avoid making every warning a hard failure on day one. Start by running the tool against the existing policy estate, understand the baseline and agree how each rule should be treated. Once the noise is understood, the linter can become a reliable quality gate rather than another check that teams learn to ignore.

Conclusion

Azure Policy Linter gives authors fast feedback and deserves a place in a Policy as Code workflow. It does not replace design review or testing in a representative Azure environment, but it helps teams find repeatable problems before a definition is assigned.

Combining it with PowerShell makes repository-wide validation practical. Adding Copilot CLI makes the findings easier for people to consume without weakening the deterministic output underneath. The key is to keep the responsibilities clear: use the linter for facts, code for counts and grouping, and AI to explain the result.