Overview of PolicyVault
PolicyVault.io is a cloud-based service that enhances the Azure DevOps experience by providing additional ways of managing and enforcing policies.
The service is currently in preview and is free to use.
What does PolicyVault do?
PolicyVault provides the following capabilities:
Pull Request Policies
- Work Item is in Query - This policy allows you to enforce that a pull request must contain work items that match a specified query. This is useful for ensuring that pull requests are associated with work items that are in a specific state, or have a specific field set. There are few very common usage examples:
- Ensure that a pull request is associated with a work item of the specific type.
- Ensure that a pull request is associated with a work item that is in the "In Progress" state.
- Ensure that a pull request is associated with a work item that has an "Assigned To" field set.
- Ensure that a pull request is associated with a work item that has an "Effort" field set.
- Work Item is not in Query - This policy allows you to enforce that a pull request must not contain work items that match a specified query. This is useful for ensuring that pull requests are not associated with work items that are in a specific state, or have a specific field set. There are few very common usage examples:
- Ensure that a pull request is not associated with a work item that is in the "New" state.
- Ensure that a pull request is not associated with a work item that has no parent, or has a parent of a specific type.
How does PolicyVault work?
PolicyVault is a cloud-based service that is integrated with Azure DevOps. It is designed to be used in conjunction with the Azure DevOps Status Check Branch policies feature.
When a pull request is created or updated, PolicyVault is notified and evaluates the pull request against the policies that have been configured. If the pull request does not meet the requirements of the policy, the corresponding quality check is marked as failed.
- On-board to PolicyVault and grant consent to your Entra Tenant. This will allow PolicyVault to access your Azure DevOps account and evaluate pull requests against the policies that have been configured.
- Install the PolicyVault extension from the Visual Studio Marketplace.
- Grant PolicyVault application access to your Azure DevOps account.
- Navigate to users settings in Azure DevOps
https://dev.azure.com/{organization}/_settings/users
.
- Type
PolicyVault
in the search box and select the PolicyVault
application.
- Select
Basic
in Access level
.
- Select projects that you want to grant permissions to in
Add to projects
.
- Select
Project Readers
in Azure DevOps Groups
.
- Click
Add
button:
![Grant PolicyVault application access to your Azure DevOps account](https://policyvault.gallerycdn.vsassets.io/extensions/policyvault/azure-devops/0.10.14.0/1725121097798/images/add-user.png)
- Configure Service Hooks for each project that you want to use PolicyVault.
- Navigate to
https://dev.azure.com/{organization}/{project}/_settings/serviceHooks
and click + Create New Subscription
.
![Add Service Hook Step 1](https://policyvault.gallerycdn.vsassets.io/extensions/policyvault/azure-devops/0.10.14.0/1725121097798/images/add-service-hook-1.png)
- Select
PolicyVault
service and click Next
.
![Add Service Hook Step 2](https://policyvault.gallerycdn.vsassets.io/extensions/policyvault/azure-devops/0.10.14.0/1725121097798/images/add-service-hook-2.png)
- Select
Pull request created
event in Trigger on this type of event
and click Next
.
![Add Service Hook Step 3](https://policyvault.gallerycdn.vsassets.io/extensions/policyvault/azure-devops/0.10.14.0/1725121097798/images/add-service-hook-3.png)
- Test the connection and click
Close
.
![Add Service Hook Step 4.1](https://policyvault.gallerycdn.vsassets.io/extensions/policyvault/azure-devops/0.10.14.0/1725121097798/images/add-service-hook-4-1.png)
![Add Service Hook Step 4.2](https://policyvault.gallerycdn.vsassets.io/extensions/policyvault/azure-devops/0.10.14.0/1725121097798/images/add-service-hook-4-2.png)
- Click
Finish
to save the subscription.
![Add Service Hook Step 5](https://policyvault.gallerycdn.vsassets.io/extensions/policyvault/azure-devops/0.10.14.0/1725121097798/images/add-service-hook-5.png)
- Repeat steps 1-5 for
Pull request updated
event.
That is it! You are now ready to start using PolicyVault to manage and enforce policies in your Azure DevOps projects.
Add Pull Request Status Checks
To configure branch policies in your Azure DevOps project, follow the steps below:
- Prepare work item queries in your Azure DevOps project. You can use existing queries or create new ones. Queries can be created in the
Queries
section of your project. Story queries in the Shared Queries
folder that is accessible to all users.
- Navigate to Git repository branch policies.
- Scroll down to the
Status Checks
section and click +
sign on the right.
- Select
Enter genre/name separately
checkbox.
- Put policy identifier in the
Genre
field. See list of supported identifiers below.
- Put work item query name or id in the
Name
field. Use full name including the folder path relative to the project.
- Optionally, expand
Advanced
section and put meaningful name in the Default display name
field. That name will be displayed in the pull request status checks.
![Configure branch policies](https://policyvault.gallerycdn.vsassets.io/extensions/policyvault/azure-devops/0.10.14.0/1725121097798/images/add-query-policy.png)
Note: You can add multiple policies to the same branch. Each policy will be evaluated separately and will be displayed as a separate status check in the pull request. You can also configure cross-repository policies for your project in https://dev.azure.com/{organization}/{project}/_settings/repositories?_a=policies
Supported policy identifiers
Table below lists supported policy identifiers and their descriptions.
Genre identifier |
Description |
PolicyVault.WorkItemQuery.NotInQuery |
Ensure that a pull request is not associated with work items that match a specified query. |
PolicyVault.WorkItemQuery.InQuery |
Ensure that a pull request is associated with work items that match a specified query. |