Policy type settings

Article
08/04/2016

TFS 2017 | TFS 2015 | TFS 2013

Note

Looking for REST APIS that support TFS 2018 or later versions? See the Azure DevOps REST API Reference.

api-version = 2.0-preview.1

This API in preview. Learn more

If you haven't already, look at the information on getting started with these APIs.

Required reviewers policy

Policy type ID = fd2167ab-b0be-447a-8ec8-39368250530e

This policy adds required or optional reviewers to a pull request when certain filename patterns are present in the pull request. If the policy is set up such that isBlocking is true, then these reviewers will be marked as "required" on the pull request and all must sign off before the pull request can be committed. If isBlocking is false, the reviewers listed here will simply be added to the pull request, and the review can be committed even if one or all of them did not approve the changes.

Settings

{
    "requiredReviewerIds": [{guid}, ...],
    "filenamePatterns": [{string}, ...],
    "addedFilesOnly": {bool},
    "message":{string},
    "scope": [{git-ref-scope}, ...]
}

Parameter	Type	Notes
requiredReviewerIds	Array of GUID	IDs of reviewers to approve before the pull request is completed.
filenamePatterns	Array of string	A list of filename patterns that, when matched, will trigger this policy. Use `` as a wildcard matching zero or more characters (including `.`), e.g. `.txt` or `/my/protected/path/*`
addedFilesOnly	bool	If `true`, only files new to the target branch will trigger the policy. If `false`, edits will also trigger the policy
message	string	If set, this message will be displayed in the pull request overview activity when the reviewers are added by this policy
scope	Array of Git ref scope	Determines what Git refs (e.g. branches) this policy applies to. To enforce the policy, direct pushes to these refs from Git clients will be rejected. Use pull requests to update refs within the scope of this policy.

Example

This example request will alter a required reviewers policy so that it:

Protects the branch master and all branches starting with releases/ in all repositories, and additionally the adventureworks branch in a specified repository
Triggers when a pull request contains files matching API*.cs or in the folder sql/tables
Adds two required reviewers when triggered
Rejects the pull request if any of the required reviewers have not approved it
Prevents the pull request from being completed if it does not comply with policy (isBlocking is true)

Sample request

PUT https://mytfsserver/DefaultCollection/fabrikam-fiber-git/_apis/policy/configurations/17?api-version=2.0-preview

{
  "isEnabled": true,
  "isBlocking": true,
  "type": {
    "id": "fd2167ab-b0be-447a-8ec8-39368250530e"
  },
  "settings": {
    "requiredReviewerIds": [
      "1d1dad71-f27c-4370-810d-838ec41efd41",
      "13272ea3-92ef-46d1-b77e-608ebbf3428b"
    ],
    "filenamePatterns": [
      "*/API*.cs",
      "sql/tables/*"
    ],
    "addedFilesOnly": false,
    "scope": [
      {
        "repositoryId": null,
        "refName": "refs/heads/master",
        "matchKind": "exact"
      },
      {
        "repositoryId": null,
        "refName": "refs/heads/releases/",
        "matchKind": "prefix"
      },
      {
        "repositoryId": "49c1d4d0-be28-4f20-9e0a-4ecfafc39257",
        "refName": "refs/heads/adventureworks",
        "matchKind": "exact"
      }
    ]
  }
}

Sample response

{
  "createdBy": {
    "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
    "displayName": "Normal Paulk",
    "uniqueName": "fabrikamfiber16@hotmail.com",
    "url": "https://mytfsserver/DefaultCollection/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
    "imageUrl": "https://mytfsserver/DefaultCollection/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
  },
  "createdDate": "2015-02-23T12:51:06.85754Z",
  "isEnabled": true,
  "isBlocking": true,
  "isDeleted": false,
  "settings": {
    "requiredReviewerIds": [
      "1d1dad71-f27c-4370-810d-838ec41efd41",
      "13272ea3-92ef-46d1-b77e-608ebbf3428b"
    ],
    "filenamePatterns": [
      "*/API*.cs",
      "sql/tables/*"
    ],
    "addedFilesOnly": false,
    "message": null,
    "scope": [
      {
        "refName": "refs/heads/master",
        "matchKind": "Exact",
        "repositoryId": null
      },
      {
        "refName": "refs/heads/releases/",
        "matchKind": "Prefix",
        "repositoryId": null
      },
      {
        "refName": "refs/heads/adventureworks",
        "matchKind": "Exact",
        "repositoryId": "49c1d4d0-be28-4f20-9e0a-4ecfafc39257"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/_apis/policy/configurations/17"
    },
    "type": {
      "href": "https://mytfsserver/DefaultCollection/1be3fc5b-c58c-4173-8fd7-6647d11eccd1/_apis/policy/types/fd2167ab-b0be-447a-8ec8-39368250530e"
    }
  },
  "revision": 2,
  "id": 17,
  "url": "https://mytfsserver/DefaultCollection/_apis/policy/configurations/17",
  "type": {
    "id": "fd2167ab-b0be-447a-8ec8-39368250530e",
    "url": "https://mytfsserver/DefaultCollection/1be3fc5b-c58c-4173-8fd7-6647d11eccd1/_apis/policy/types/fd2167ab-b0be-447a-8ec8-39368250530e",
    "displayName": "Required reviewers"
  }
}

Minimum approval count policy

Policy type ID = fa4e907d-c16b-4a4c-9dfa-4906e5d171dd

Requires that a specified minimum number of reviewers have to approved a pull request before it can be completed.

Settings

{
    "minimumApproverCount": {integer},
    "creatorVoteCounts": {bool},
    "allowDownvotes": {bool},
    "scope": [{git-ref-scope}, ...]
}

Parameter	Type	Notes
minimumApproverCount	integer	The number of people who must approve the pull request before it can be completed
creatorVoteCounts	boolean	If `false`, the vote of the person who created the pull request does not count toward the minimum approver count
allowDownvotes	boolean	If `true`, the pull request is allowed to be completed even if one of the votes is a 'reject' or 'wait for author' as long as there are enough approvers. If `false`, the pull request will be blocked if any down vote is cast, regardless of whether the minimum number of approvals is met.
scope	Array of Git ref scope	Determines what Git refs (e.g. branches) this policy applies to. To enforce the policy, direct pushes to these refs from Git clients will be rejected. Use pull requests to update refs within the scope of this policy.

Example

This example adds an approval count policy that:

Protects the main branch in all repositories in the project
Rejects the pull request if there is not at least one reviewer who has approved the pull request
Does not count the user who created the pull request
Does not block the pull request from being completed (isBlocking is false)
- The web interface warns the user on completion if the pull request does not comply with the policy

Sample request

POST https://mytfsserver/DefaultCollection/fabrikam-fiber-git/_apis/policy/configurations?api-version=2.0-preview

{
  "isEnabled": true,
  "isBlocking": false,
  "type": {
    "id": "fa4e907d-c16b-4a4c-9dfa-4906e5d171dd"
  },
  "settings": {
    "minimumApproverCount": 1,
    "creatorVoteCounts": false,
    "scope": [
      {
        "repositoryId": null,
        "refName": "refs/heads/master",
        "matchKind": "exact"
      }
    ]
  }
}

Sample response

{
  "createdBy": {
    "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
    "displayName": "Normal Paulk",
    "uniqueName": "fabrikamfiber16@hotmail.com",
    "url": "https://mytfsserver/DefaultCollection/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
    "imageUrl": "https://mytfsserver/DefaultCollection/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
  },
  "createdDate": "2015-02-23T12:51:06.8887894",
  "isEnabled": true,
  "isBlocking": false,
  "settings": {
    "minimumApproverCount": 1,
    "creatorVoteCounts": false,
    "scope": [
      {
        "refName": "refs/heads/master",
        "matchKind": "Exact",
        "repositoryId": null
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/_apis/policy/configurations/18"
    },
    "type": {
      "href": "https://mytfsserver/DefaultCollection/1be3fc5b-c58c-4173-8fd7-6647d11eccd1/_apis/policy/types/fa4e907d-c16b-4a4c-9dfa-4906e5d171dd"
    }
  },
  "revision": 1,
  "id": 18,
  "url": "https://mytfsserver/DefaultCollection/_apis/policy/configurations/18",
  "type": {
    "id": "fa4e907d-c16b-4a4c-9dfa-4906e5d171dd",
    "url": "https://mytfsserver/DefaultCollection/1be3fc5b-c58c-4173-8fd7-6647d11eccd1/_apis/policy/types/fa4e907d-c16b-4a4c-9dfa-4906e5d171dd",
    "displayName": "Minimum approval count"
  }
}

Build policy

Policy type ID = 0609b952-1397-4640-95ec-e00a01b2c241

Requires that the merged result of a pull request builds successfully using a specified build definition before the pull request can be completed.

Settings

{
    "buildDefinitionId": {integer},
    "queueOnSourceUpdateOnly": {bool},
    "validDuration": {double},
    "manualQueueOnly":{bool},
    "displayName":{bool},
    "scope": [{git-ref-scope}, ...]
}

Parameter	Type	Notes
buildDefinitionId	integer	ID of a build definition to use for validation. The system will automatically queue the build once the candidate merge commit is ready.
queueOnSourceUpdateOnly	boolean	If `true`, the build will only be queued when the pull request source branch gets updated.
validDuration	double	If `true` & `queueOnSourceUpdateOnly` has to also be set to `true`, the build will only be queued when the pull request source branch gets updated but will expire after the number of minutes specified
manualQueueOnly	boolean	If `true`, the build will not be queued automatically when the pull request is created or updated. Users will be given the option to manually queue the build from the UX when they desire.
displayName	string	If set, this string is used as the policy name. Default is "Build".
scope	Array of Git ref scope	Determines what Git refs (e.g. branches) this policy applies to. To enforce the policy, direct pushes to these refs from Git clients will be rejected. Use pull requests to update refs within the scope of this policy.

Example

This example adds a build policy that:

Protects branches beginning with features/ in all repositories
Automatically queues a build using a specified definition once the merged code is available
Rejects the pull request if the build has not completed successfully
Does not block the pull request from being completed (isBlocking is false)
- The web interface warns the user on completion if the pull request does not comply with the policy

Sample request

POST https://mytfsserver/DefaultCollection/fabrikam-fiber-git/_apis/policy/configurations?api-version=2.0-preview

{
  "isEnabled": true,
  "isBlocking": false,
  "type": {
    "id": "0609b952-1397-4640-95ec-e00a01b2c241"
  },
  "settings": {
    "buildDefinitionId": 5,
    "scope": [
      {
        "repositoryId": null,
        "refName": "refs/heads/features/",
        "matchKind": "prefix"
      }
    ]
  }
}

Sample response

{
  "createdBy": {
    "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
    "displayName": "Normal Paulk",
    "uniqueName": "fabrikamfiber16@hotmail.com",
    "url": "https://mytfsserver/DefaultCollection/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
    "imageUrl": "https://mytfsserver/DefaultCollection/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
  },
  "createdDate": "2015-02-23T12:51:06.935666",
  "isEnabled": true,
  "isBlocking": false,
  "settings": {
    "buildDefinitionId": 5,
    "scope": [
      {
        "refName": "refs/heads/features/",
        "matchKind": "Prefix",
        "repositoryId": null
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/_apis/policy/configurations/19"
    },
    "type": {
      "href": "https://mytfsserver/DefaultCollection/1be3fc5b-c58c-4173-8fd7-6647d11eccd1/_apis/policy/types/0609b952-1397-4640-95ec-e00a01b2c241"
    }
  },
  "revision": 1,
  "id": 19,
  "url": "https://mytfsserver/DefaultCollection/_apis/policy/configurations/19",
  "type": {
    "id": "0609b952-1397-4640-95ec-e00a01b2c241",
    "url": "https://mytfsserver/DefaultCollection/1be3fc5b-c58c-4173-8fd7-6647d11eccd1/_apis/policy/types/0609b952-1397-4640-95ec-e00a01b2c241",
    "displayName": "Build"
  }
}

Work item linking policy

Policy type ID = 40e92b44-2fe1-4dd6-b3d8-74a9c21d0c6e

Requires that at least one work item is associated with a pull request before it can be completed.

Settings

{
    "scope": [{git-ref-scope}, ...]
}

Parameter	Type	Notes
scope	Array of Git ref scope	Determines what Git refs (e.g. branches) this policy applies to. To enforce the policy, direct pushes to these refs from Git clients will be rejected. Use pull requests to update refs within the scope of this policy.

Example

This example adds a work item policy that:

Protects the main branch in all repositories in the project
Rejects the pull request if there is not at least one work item associated with the pull request
Does not block the pull request from being completed (isBlocking is false)
- The web interface warns the user on completion if the pull request does not comply with the policy

Sample request

POST https://mytfsserver/DefaultCollection/fabrikam-fiber-git/_apis/policy/configurations?api-version=2.0-preview

{
  "isEnabled": true,
  "isBlocking": false,
  "type": {
    "id": "40e92b44-2fe1-4dd6-b3d8-74a9c21d0c6e"
  },
  "settings": {
    "scope": [
      {
        "repositoryId": null,
        "refName": "refs/heads/master",
        "matchKind": "exact"
      }
    ]
  }
}

Sample response

{
  "createdBy": {
    "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
    "displayName": "Normal Paulk",
    "uniqueName": "fabrikamfiber16@hotmail.com",
    "url": "https://mytfsserver/DefaultCollection/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
    "imageUrl": "https://mytfsserver/DefaultCollection/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
  },
  "createdDate": "2015-02-23T12:51:06.935666",
  "isEnabled": true,
  "isBlocking": false,
  "settings": {
    "scope": [
      {
        "refName": "refs/heads/master",
        "matchKind": "Exact",
        "repositoryId": null
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/_apis/policy/configurations/19"
    },
    "type": {
      "href": "https://mytfsserver/DefaultCollection/1be3fc5b-c58c-4173-8fd7-6647d11eccd1/_apis/policy/types/40e92b44-2fe1-4dd6-b3d8-74a9c21d0c6e"
    }
  },
  "revision": 1,
  "id": 19,
  "url": "https://mytfsserver/DefaultCollection/_apis/policy/configurations/19",
  "type": {
    "id": "40e92b44-2fe1-4dd6-b3d8-74a9c21d0c6e",
    "url": "https://mytfsserver/DefaultCollection/1be3fc5b-c58c-4173-8fd7-6647d11eccd1/_apis/policy/types/40e92b44-2fe1-4dd6-b3d8-74a9c21d0c6e",
    "displayName": "Work item linking"
  }
}

Merge strategy policy

Policy type ID = fa4e907d-c16b-4a4c-9dfa-4916e5d171ab

Requires that a pull request uses a specific merge strategy when completed.

Settings

{
    "useSquashMerge": {bool},
    "scope": [{git-ref-scope}, ...]
}

Parameter	Type	Notes
useSquashMerge	boolean	If `true` pull requests are forced to use squash merge when merging. If `false` pull requests are forced to use merge when merging.
scope	Array of Git ref scope	Determines what Git refs (e.g. branches) this policy applies to. To enforce the policy, direct pushes to these refs from Git clients will be rejected. Use pull requests to update refs within the scope of this policy.

Example

This example adds a merge strategy policy that:

Ensures all pull requests going into master are squash merged

Sample request

POST https://mytfsserver/DefaultCollection/fabrikam-fiber-git/_apis/policy/configurations?api-version=2.0-preview

{
  "isEnabled": true,
  "isBlocking": true,
  "type": {
    "id": "fa4e907d-c16b-4a4c-9dfa-4916e5d171ab"
  },
  "settings": {
    "useSquashMerge": true,
    "scope": [
      {
        "repositoryId": "1d1dad71-f27c-4370-810d-838ec41efd41",
        "refName": "refs/heads/master",
        "matchKind": "exact"
      }
    ]
  }
}

Sample response

{
  "createdBy": {
    "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
    "displayName": "Normal Paulk",
    "uniqueName": "fabrikamfiber16@hotmail.com",
    "url": "https://mytfsserver/DefaultCollection/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
    "imageUrl": "https://mytfsserver/DefaultCollection/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
  },
  "createdDate": "2015-02-23T12:51:06.935666",
  "isEnabled": true,
  "isBlocking": true,
  "settings": {
    "useSquashMerge": true,
    "scope": [
      {
        "refName": "refs/heads/master",
        "matchKind": "Exact",
        "repositoryId": "1d1dad71-f27c-4370-810d-838ec41efd41"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/_apis/policy/configurations/19"
    },
    "type": {
      "href": "https://mytfsserver/DefaultCollection/1be3fc5b-c58c-4173-8fd7-6647d11eccd1/_apis/policy/types/fa4e907d-c16b-4a4c-9dfa-4916e5d171ab"
    }
  },
  "revision": 1,
  "id": 19,
  "url": "https://mytfsserver/DefaultCollection/_apis/policy/configurations/19",
  "type": {
    "id": "fa4e907d-c16b-4a4c-9dfa-4916e5d171ab",
    "url": "https://mytfsserver/DefaultCollection/1be3fc5b-c58c-4173-8fd7-6647d11eccd1/_apis/policy/types/fa4e907d-c16b-4a4c-9dfa-4916e5d171ab",
    "displayName": "Require a merge strategy"
  }
}

Git ref scope

Describes that a policy should apply to specified Git refs according to a pattern

json
{
    "repositoryId": {guid-or-null},
    "refName": {string},
    "matchKind": "prefix|exact"
}

Parameter	Type	Notes
repositoryId	guid or null	The ID of the repository the scope applies to, or null for all repositories in the project. Must always be specified, even if null
refName	string	The ref name to select with the scope. Include the `refs/heads/` prefix.
matchKind	enum { Prefix, Exact }	Determines how refName is matched against Git ref names. Comparison is always case-sensitive.

Share via

Policy type settings

Required reviewers policy

Settings

Example

Sample request

Sample response

Minimum approval count policy

Settings

Example

Sample request

Sample response

Build policy

Settings

Example

Sample request

Sample response

Work item linking policy

Settings

Example

Sample request

Sample response

Merge strategy policy

Settings

Example

Sample request

Sample response

Git ref scope

Additional resources