Git repository settings and policies
Azure Repos | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018
You can customize your Azure DevOps Git repositories using repository and policy settings. Global options for entire repositories are configured by repository settings. There are also user-specific and branch-specific controls, covered by permissions and branch policies respectively.
This article covers server-side repository settings. You may also want to learn about client-side Git preferences.
Note
The feature documented in this article requires TFS 2018 Update 2 or later version.
For branch-specific settings, review branch policies. These include options like requiring a pull request, a successful build, or a code review. For user-specific settings, review permissions. Permissions allow you to control who can read, write, contribute to pull requests, and other specific actions.
Summary of all repository and branch settings
You can configure various settings and policies for all repositories, for individual repositories, and for individual branches of a repository. These are all set through Project Settings.
Note
We recommend you configure repository settings either at the project level or for each individual repo, but not both. If set at both level, the system honors the most restrictive setting. Configuring these settings at only one level removes this complexity and prevents a decrease in Git performance.
All repository settings
The following table summarizes the settings you can enable and configure for all Git repositories that are created for a project.
Setting
Default
Description
Off
When enabled, new repositories are initialized with the name of the branch that you specify. You can change the default branch for a particular repository at any time. The default branch name is main.
Allow users to manage permissions for their created branches
On
New repositories are configured to allow users to manage permissions for their created branches.
Individual repository settings
The following table summarizes the settings you can enable and configure to customize for each Git repository.
Setting
Default
Description
On
Allow users to create forks from the repository.
On
Automatically create links for work items mentioned in a commit comment.
On
Allow mentions in commit comments to close work items.
On
Remember user preferences for completing work items with pull requests.
Permissions management
On
Allow users to manage permissions for the branches they created
Strict Vote Mode
On
Enable Strict Vote Mode for repository which requires Contribute permission to vote in Pull Requests.
Disable Repository
On
Disable access to to the repository (including builds, pull requests, etc) but keep the repository discoverable with a warning.
Searchable branches
On
Specify up to 5 additional branches to participate in code search, which by default only applies to the default branch.
Repository policies
The following table summarizes the policies you can define to customize a repository or define to initialize all new repositories with these settings.
Policy
Default
Description
Off
Block pushes with a commit author email that does not match the specified patterns.
Off
Block pushes from introducing file paths that match the specified patterns.
Off
Avoid case-sensitivity conflicts by blocking pushes that change name casing on files, folders, branches, and tags.
Off
Block pushes that introduce files, folders, or branch names that include platform reserved names or incompatible characters.
Off
Block pushes that introduce paths that exceed the specified length.
Off
Block pushes that contain new or updated files larger than this limit.
Branch policies
The following table summarizes the policies you can define to customize a branch. For more information on configuring these settings, see Improve code quality with branch policies.
Policy
Default
Description
Off
Require approval from a specified number of reviewers on pull requests.
Off
Encourage traceability by checking for linked work items on pull requests
Off
Check to see that all comments have been resolved on pull requests.
Off
Control branch history by limiting the available types of merge when pull requests are completed.
Off
Add one or more policies to validate code by pre-merging and building pull request changes. Can also enable or disable policies.
Off
Add one or more policies to require other services to post successful status to complete pull requests. Can also enable or disable policies.
Off
Add one or more policies to designate code reviewers to automatically include when pull requests change certain areas of code. Can also enable or disable policies.
Prerequisites
- To set branch policies, you must be a member of the Project Administrators security group or have the repository-level permissions set: Edit policies. To learn more, see Set Git repository permissions.
- If this is your first time using
az reposcommands, see Get started with Azure DevOps CLI.
- To set branch policies, you must be a member of the Project Administrators security group or have the repository-level permissions set: Edit policies. To learn more, see Set Git repository permissions.
View and edit repository settings
From your web browser, open the project for your organization in Azure DevOps and choose Project settings, Repositories, and select your repository.
Select Settings to view and configure your repository settings.
Select Policies to view and configure project level and cross-repo policies.
From your web browser, open the project and choose Project settings, Repositories, and select your repository.
Select Options and Policies to view and configure your repository settings.
From your web browser, open the project and choose the gear icon, Version Control, and select your repository.
Select options to view and configure your repository settings.
From your web browser, open the project and choose the gear icon, Version Control, and select your repository.
Select Options to view and configure your repository settings.
Default branch name preference
You can choose any legal branch name to use when a repository is initialized, or change it later if necessary. You can access the setting in two ways:
Organization settings - From the DevOps page, select your project > Organization settings > Repositories, turn on Default branch name for new repositories, and type your default branch name.
Project settings - From the project page, select Project settings > Repositories > Settings, turn on Default branch name for new repositories, and type your default branch name.
If you don't enable this feature, your repositories will be initialized with the Azure Repos default name, main.
Cross-repo branch policy administration
You can set policies on a specific branch or the default branch across all repositories in their project. For example, an admin could require two minimum reviewers for all pull requests made into every main branch across every repository in their project. You can find the Add branch protection feature in the Repos Project Settings.
Forks
Controls whether users are able to create new server-side forks. Disabling this setting will not alter existing forks.
From Project Settings>Repository>Settings, you can enable or disable Forks.
Work item linking
From Project Settings>Repository>Settings, you can configure settings that manage work item linking.
Setting
Description
Commit mention linking
When enabled, commit messages containing "#" followed by a valid work item ID will automatically link the commit to the mentioned work item. Disable this setting when pushing a repository previously contained by a different account or service. Those repositories may have #mentions that don't match the work item IDs in the current account.
Commit mention work item resolution
Enable this setting to automatically complete those work items when you successfully complete the PR. Or, you can specify the workflow state to transition the work item to upon merging the PR. To learn more, see Auto-complete work items with pull requests.
Commit mention work item resolution
Enable this setting to automatically complete those work items when you successfully complete the PR. To learn more, see Auto-complete work items with pull requests.
Work item transition preferences
By default, the option to complete linked work items during pull request completion will remember each user's last choice. Some teams may have different approaches to closing work items, such as at a standup meeting, and may want to discourage users from completing work items with their pull requests. By disabling this setting, users must opt-in to completing work items for each pull request.
Commit author email validation
You can set a push policy to prevent commits from being pushed to a repository for which the commit author email does not match the provided pattern.
From Project Settings>Repository>Policies, you can enable or disable Commit author email validation.
You can specify exact emails or use wildcards. Multiple email patterns should use ";" as a separator. Email patterns prefixed with "!" are excluded. Order is important.
File path validation
You can set a policy to prevent commits from being pushed to a repository based on file paths. The file path validation policy will block pushes that match the provided pattern.
Case enforcement
Git is case-sensitive, meaning that a file called "Foo.txt" is different from a file called "foo.txt". Windows and macOS default to case-insensitive file systems, meaning that "Foo.txt" and "foo.txt" are the same name. This can cause problems for users if someone on a case-insensitive system pushes files, folders, branches, or tags that only differ by letter case.
If most of your users are on Windows or macOS, we recommend turning on the Case enforcement setting. Case enforcement switches the server from its default case-sensitive mode, where “File.txt” and “file.txt” are distinct, to a Windows and macOS-friendly mode where “File.txt” and “file.txt” are the same file. This setting affects files, folders, branches, and tags. It also prevents contributors from accidentally introducing case-only differences. Enabling case enforcement is recommended when most of your contributors are running Windows or macOS.
It will block the introduction of new files, folders, branches, or tags that would cause such a conflict. The user will have to rewrite their unpushed history to fix the problem, then try the push again.
This setting will not fix a repository which already contains objects that only differ by case. We recommend fixing such issues before turning the policy on. You can rename files and folders or re-create branches and tags using new, non-conflicting names.
From Project Settings>Repository>Policies, you can enable or disable Case enforcement.
Note
The Case enforcement policy requires TFS 2018.2 or later version.
Reserved names and Maximum path length
Not all files names are allowed on the three major OS file systems (Windows, macOS, and Linux). Developers can push commits to a shared repository that may contain files or folders with names that are invalid on one or more platforms. Working directory can become corrupted if invalid files or folders are fetched and checked out on a platform.
From Project Settings>Repository>Policies, you can enable or disable two policies to place restrictions on file names and file paths: Reserved names and Maximum path length.
The Reserved names setting will block pushes to your repository that contain files or folders names that are invalid on any platform. See what names are invalid
Also, not all path lengths are allowed on the three major OS file systems (Windows, macOS, and Linux). Developers can push commits to a shared repository that may contain files or directories with path lengths that are invalid on one or more platforms. If these files or directories are fetched and checked out on a platform where they are invalid then the working directory can become corrupted.
The Maximum path length setting will block pushes to your repository that contain files or directories with path names that are invalid on any platform. See what path lengths are invalid. When enabled, a default value of 248 is selected because that is the highest max length that is 100% supported across all three major platforms.
The max path value can be modified. For example, if you only have macOS or Linux developers in your organization, then you may optionally choose to set it to highest value that is 100% supported on both platforms (1016). You may also optionally choose to set a lower max path value if you wish to enforce certain directory & naming conventions for your organization.
Maximum file size
Large files checked into Git remain in the repository forever, dragging down clone times and increasing disk usage. We have suggestions for helping you manage large files.
The Maximum file size policy setting gives administrators a way to block files over a certain size from entering the repository. If a push contains a new or updated file larger than the limit configured in this setting, that push will be blocked. The user will have to rewrite their unpushed history to remove the large file and try the push again.
From Project Settings>Repository>Policies, you can enable or disable Maximum file size and set the maximum
Note
The Maximum file size policy requires TFS 2018.2 or later version.