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.

• Overview of PolicyVault
  • What does PolicyVault do?
    • Pull Request Policies
  • How does PolicyVault work?
  • Configure Azure DevOps to use PolicyVault
  • Configure branch policies
    • Add Pull Request Status Checks
    • Supported policy identifiers

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.

Configure Azure DevOps to use PolicyVault

1. 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.
2. Install the PolicyVault extension from the Visual Studio Marketplace.
3. Grant PolicyVault application access to your Azure DevOps account.
   1. Navigate to users settings in Azure DevOps https://dev.azure.com/{organization}/_settings/users.
   2. Type PolicyVault in the search box and select the PolicyVault application.
   3. Select Basic in Access level.
   4. Select projects that you want to grant permissions to in Add to projects.
   5. Select Project Readers in Azure DevOps Groups.
   6. Click Add button:
      
4. Configure Service Hooks for each project that you want to use PolicyVault.
   1. Navigate to https://dev.azure.com/{organization}/{project}/_settings/serviceHooks and click + Create New Subscription.
      
   2. Select PolicyVault service and click Next.
      
   3. Select Pull request created event in Trigger on this type of event and click Next.
      
   4. Test the connection and click Close.
      
      
   5. Click Finish to save the subscription.
      
   6. 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.

Configure branch policies

Add Pull Request Status Checks

To configure branch policies in your Azure DevOps project, follow the steps below:

1. 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.
2. Navigate to Git repository branch policies.
3. Scroll down to the Status Checks section and click + sign on the right.
4. Select Enter genre/name separately checkbox.
5. Put policy identifier in the Genre field. See list of supported identifiers below.
6. Put work item query name or id in the Name field. Use full name including the folder path relative to the project.
7. 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.

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.