Policy Configurations - Get

Service:: Git

API Version:: 7.2-preview.1

Retrieve a list of policy configurations by a given set of scope/filtering criteria.

Azure Repos uses two types of policies to protect your code:

Repository policies (push policies) check every push to your repository. They validate things like file size limits, path restrictions, or commit requirements. When someone pushes code that violates these rules, the push gets rejected - no matter which branch they're pushing to.

Branch policies (PR policies) protect specific branches by requiring pull requests. When you set a branch policy on main, for example, nobody can push directly to main anymore. They must create a pull request instead, which can then require reviews, builds, or other checks to pass first.

How Policies Work with Your Project Structure

Both types of policies can be defined at different levels in your project hierarchy. A policy defined at the project level affects all repositories in that project. A policy defined at the repository level affects just that repository. A branch policy can even be defined at the project level to protect all branches with the same name - like protecting all main branches across your entire project with one policy.

Branch Patterns and Wildcards

Branches in Git follow a folder-like structure. You might have branches like:

refs/heads/main
refs/heads/releases/1.0.0
refs/heads/releases/2.0.0
refs/heads/features/new-login

You can create policies for specific branches or for groups of branches using wildcards. When you create a policy for refs/heads/releases/*, it protects all branches in the releases "folder" - both the ones that exist now and any new release branches you create later. This pattern matching works recursively, so refs/heads/releases/* also covers branches like refs/heads/releases/v1/hotfix.

This helps you set up consistent protection without creating the same policy over and over. For example, you can require two reviewers for all release branches with just one policy.

Understanding Policy Inheritance

When you query for policies, this endpoint shows you what policies are actually enforcing rules at your specified scope. This includes policies inherited from higher levels. For example, if you query for policies on a specific branch, you get:

Branch policies for that exact branch
Branch policies with wildcards that match your branch
Repository policies for that repo
Any applicable project-level policies

Everything that protects that branch shows up in your results.

How to Query for Policies

The repositoryId and refName parameters let you focus on specific parts of your project. Here's what you get with different combinations:

Both repositoryId and refName specified:

When refName is a specific branch name: You see all policies affecting that specific branch. This includes exact branch policies, wildcard branch policies that match, repository policies for that repo, and any project-level policies.
When refName is ~all: You see every policy that affects any branch in that repository. This special value gives you the same results as if you called this API once for every single branch in the repo and then combined all the results (removing duplicates). You get all branch-specific policies, all wildcard policies, all repository policies, and all inherited project-level policies that apply to this repository. This helps you see the complete picture of what protects all your branches without making multiple API calls.

Only repositoryId specified: You see policies that apply to the repository as a whole - repository policies and inherited project-level repository policies. Branch policies aren't included because they don't affect the whole repository.

Neither parameter specified: You see only project-level repository policies. Branch policies defined at the project level aren't included, even though they exist at the project level. This happens because branch policies need a branch context to be meaningful - without specifying a repository or branch name, the API only returns policies that apply to repositories as a whole.

Only refName specified: You see project-level branch policies for branches with that name (like all main branch policies defined at project level), plus project-level repository policies.

You can add the policyType parameter to filter for a specific type of policy, such as "Minimum number of reviewers" or "File size restriction". This parameter accepts the policy type ID and filters the results to show only that specific policy type.

Common Scenarios

"What protects my main branch?" - Use repositoryId + refName=refs/heads/main
"What protects all my release branches?" - Use repositoryId + refName=refs/heads/releases/*
"Show me every policy that affects any branch in this repository" - Use repositoryId + refName=~all
"What repository policies apply to this repo?" - Use repositoryId only
"What file size limits apply to this repository?" - Use repositoryId with the policyType for file size restrictions
"What project-wide repository policies do we have?" - Don't specify repositoryId or refName
"Which policies apply to develop branches across all repositories?" - Use refName=refs/heads/develop

GET https://dev.azure.com/{organization}/{project}/_apis/git/policy/configurations?api-version=7.2-preview.1

With optional parameters:

GET https://dev.azure.com/{organization}/{project}/_apis/git/policy/configurations?repositoryId={repositoryId}&refName={refName}&policyType={policyType}&$top={$top}&continuationToken={continuationToken}&api-version=7.2-preview.1

URI Parameters

Name	In	Required	Type	Description
organization	path	True	string	The name of the Azure DevOps organization.
project	path	True	string	Project ID or project name
api-version	query	True	string	Version of the API to use. This should be set to '7.2-preview.1' to use this version of the api.
$top	query		integer (int32)	The maximum number of policy configurations to return in a single response - useful for limiting result size when dealing with projects that have many policies.
continuationToken	query		string	A token returned in the x-ms-continuationtoken response header from a previous request when not all results were returned - use this token to retrieve the next page of results in the dataset.
policyType	query		string (uuid)	The type ID of a specific policy to filter by (e.g., "Minimum number of reviewers" or "File size restriction") - when specified, returns only policies of this particular type rather than all policy types.
refName	query		string	The branch reference to query policies for (e.g., "refs/heads/main" for a specific branch or "~all" to get all policies affecting any branch in the repository) - determines which branch-specific policies are included in the results.
repositoryId	query		string (uuid)	The unique identifier of a specific repository to query policies for - when provided, returns policies that apply to this repository including inherited project-level policies.

Responses

Name	Type	Description
200 OK	PolicyConfiguration[]	successful operation Headers x-ms-continuationtoken: string

Name

Type

Description

200 OK

PolicyConfiguration[]

successful operation

Headers

x-ms-continuationtoken: string

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name	Description
vso.code	Grants the ability to read source code and metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to search code and get notified about version control events via service hooks.

Definitions

Name	Description
IdentityRef
PolicyConfiguration	The full policy configuration with settings.
PolicyTypeRef	Policy type reference.
ReferenceLinks	The class to represent a collection of REST reference links.

IdentityRef

Object

Name	Type	Description
_links	ReferenceLinks	This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.
descriptor	string	The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations.
directoryAlias	string	Deprecated - Can be retrieved by querying the Graph user referenced in the "self" entry of the IdentityRef "_links" dictionary
displayName	string	This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.
id	string
imageUrl	string	Deprecated - Available in the "avatar" entry of the IdentityRef "_links" dictionary
inactive	boolean	Deprecated - Can be retrieved by querying the Graph membership state referenced in the "membershipState" entry of the GraphUser "_links" dictionary
isAadIdentity	boolean	Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsAadUserType/Descriptor.IsAadGroupType)
isContainer	boolean	Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsGroupType)
isDeletedInOrigin	boolean
profileUrl	string	Deprecated - not in use in most preexisting implementations of ToIdentityRef
uniqueName	string	Deprecated - use Domain+PrincipalName instead
url	string	This url is the full route to the source resource of this graph subject.