Azure/azure-policy is a mirror of built-in definitions, not a place to file issues

What the repository actually stores

The README describes the contents in one line: this repository contains the direct representation of built-in definitions published to Azure. That word direct matters. These are not hand-written tutorials or a policy authoring SDK. They are the built-in policy definitions, expressed as files, in the same shape Azure publishes them.

The top-level layout reflects that. `built-in-policies/` holds the definitions themselves and `built-in-references/` holds supporting reference material. Alongside them sit `samples/`, `patterns/`, `ExternalEvaluationPolicies/` and a `readme.generate.md` file, which by its name appears to drive generation of the per-sample README files rather than serving as documentation itself.

The primary language is recorded as Open Policy Agent. Licence is MIT, and `package.json` names the Azure Governance Team as author.

Practically, this is the repository you open when you want to answer a question like what a specific built-in definition actually denies, rather than what its name suggests it does.

Contributions are refused here on purpose

This is the section most visitors misread. Under Contributing, the README does not describe a contribution process; it redirects. To contribute, you are told to submit your policies to the Community repo at github.com/Azure/Community-Policy. The same redirect appears in the opening paragraphs, which also point out that for custom policy samples you should look at that Community repo.

So the split is clean: built-in definitions live here because Azure publishes them, custom policies live elsewhere because they are yours. That is unusual for a repository with a LICENSE file and a samples directory, and it explains why you will not find a contribution guide for adding samples here.

Issue reporting follows the same logic. The README says support for addressing built-in definition issues is handled by Azure Customer Support, and that you should open an Azure Customer Support ticket if you believe a definition has a bug or error. There is no GitHub issue flow described for that case, which means the issues tracker in this repository is not the supported channel for the most important thing you might find wrong.

Support has moved to four other channels

The Getting Support section is worth reading carefully, because it maps four different kinds of question to four different destinations, and none of them is a pull request.

Alias requests get their own treatment, with an explanation of what an alias does. The README states that an alias enables you to restrict what values or conditions are permitted for a property on a resource, and that each alias maps to paths in different API versions for a given resource type, with the policy engine resolving the property path for the API version in question during evaluation. New aliases are requested through Azure Customer Support, and the linked definition structure page documents the commands for discovering existing aliases.

General questions go to the Microsoft Tech Community Azure Governance conversation space, the Azure Governance customer call, old issues in this repository, the StackOverflow tag, or Azure Governance Ideas for feature requests and votes. In-depth questions or anything not public go to a support ticket. Documentation corrections go somewhere else entirely: the feedback area at the bottom of the page, or an issue on the Microsoft Docs feedback repository if no feedback area exists.

The README also notes that the general Azure Policy support role of this repository has transitioned to standard Azure support channels. In other words, this repository used to be where you asked questions, and no longer is.

The Known Issues list is the most useful file here

If you take one thing from this repository, take the Known Issues section. It explains the mechanism behind policy surprises rather than just listing symptoms.

The core statement is that Azure Policy operates at a level above other Azure services, applying policy rules against PUT requests and GET responses of resource types moving between Azure Resource Manager and the owning resource provider. In a few cases the behaviour of a given resource provider is unexpected or incompatible with Azure Policy. The team works with the RP teams to close these gaps, and the notable prediction is that aliases for properties of these resource types will usually be removed once the anomalous behaviour is discovered, because the alias was papering over the problem.

That framing has a direct consequence for anyone writing a custom policy. A denial you hit today on one resource type may disappear when the alias is withdrawn, without any change to your policy. Building governance logic on an alias that currently misbehaves is a bet on an eventual removal rather than a stable fact.

The README says issues of this nature are documented here until final resolution, which is why the Known Issues section is the file to watch rather than the samples.

Reading the samples as a service index

The `samples/` tree is organised by Azure service rather than by policy concept, which makes it a lookup table rather than a tutorial. The service directories are Authorization, Automation, Compute, CosmosDB, DataLake, EventHub, General, GuestConfiguration, KeyVault, KubernetesService, Monitoring, Network, PolicyInitiatives, ResourceGroup, SQL, Storage, Tags, TextPatterns and WebApp.

That list is the top level only. Inside each directory the files are the sample policies for that service, and `samples/built-in-policy/` plus `samples/__tests__/` sit alongside the service folders. The presence of `__tests__` is the hint that the samples are validated mechanically rather than merely curated by hand.

The tests are Jest, and the setup is minimal. The `package.json` is a one-version, one-script package with no runtime dependencies at all:

"scripts": {
  "test": "jest"
},
"dependencies": {},
"devDependencies": {
  "eslint": "^7.32.0",
  "jest": "^30.2.0"
}

So the toolchain to validate samples is ESLint with the standard config plus Jest. There is no build, no bundler and nothing to publish; the artefacts are the JSON and policy files themselves. A `samples/README.template.for.set.md` template explains how the per-directory READMEs are generated, consistent with `readme.generate.md` at the root.

The repository has no GitHub releases, so there is no version tag to pin. You clone the branch you want and diff it against the current definition published by Azure.

Where this repository is the wrong place to look

Three cases stand out.

First, if you need to author a custom policy, this is the wrong repository by explicit instruction. The README sends you to Azure/Community-Policy, and the Contributing section refuses submissions here.

Second, if you are trying to get help, you are in the wrong place. The README states the support role of this repository has transitioned to standard Azure support channels, and that in-depth or non-public questions belong in a support ticket.

Third, and most quietly, if you are debugging a compliance state, remember that policy operates between Azure Resource Manager and the resource provider. That is why the Known Issues section exists at all: some misbehaviour belongs to the resource provider rather than to policy, and this repository is where the intersection is documented rather than where it gets fixed.

For the surrounding concepts the README points to external documentation rather than duplicating it, including the Azure Policy overview, how to assign policies through the portal, through Azure PowerShell and through Azure CLI, definition structure, effects, getting compliance data and remediating non-compliant resources. Those pages, not this repository, are where the mechanics of assignment live. This repository is where you check what a definition says and whether the behaviour you are seeing is listed as a known anomaly.

Editorial conclusion

Use this repository when you need to see what a built-in Azure Policy definition actually contains, when you want a working sample to copy for a specific service, or when you are debugging why a resource evaluates as non-compliant. Do not use it as an issue tracker or as a place to submit policies: the README routes both to Azure Customer Support and to the separate Azure/Community-Policy repository. Before relying on anything you find under `built-in-policies/`, compare it with the current definition published by Azure, since this repository has no GitHub releases that indicate when it drifted.

Frequently asked questions

Official sources

1. Azure/azure-policy on GitHub
2. Issues
3. License: MIT
4. README