Edit

Share via

Set Git repository settings and policies

  • Article

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

There are several ways to customize your Azure Repos Git repositories by using branch and repository settings and policies. This article discusses repository-level settings and policies.

  • Repository settings and policies configure global options for all Git repositories for a project or organization, or for individual repositories.

    This article discusses server-side repository settings and policies. To learn about client-side Git preferences, see Git preferences and settings in Visual Studio.

  • Branch policies cover branch-specific controls.

    Branch policies include options like requiring a pull request, a successful build, or a code review before changes can merge into a branch. For more information, see Branch policies and settings.

  • Repository and branch security permissions control user assignments.

    These permissions control who can read, write, contribute to pull requests, and take other specific actions. For more information, see Set permissions for a repository.

Summary of all repository and branch settings and policies

You can configure settings and policies for all repositories in a project, for individual repositories, and for branches of repositories. In the browser, you configure all these settings and policies through Project settings > Repositories.

Note

You can set several branch settings and policies with the Azure CLI using az repos policy.

The following tables summarize the settings and policies you can enable and configure for Git repositories and branches.

All Repositories Settings

The following table summarizes the settings you can enable and configure for all new Git repositories in a project or in an organization.

Setting

Default

Description

Default branch name for new repositories

Off

Initialize new repositories with the default branch name you specify. You can change the default branch for a particular repository anytime. If you don't enable this feature, repositories initialize with a default branch named main.

Allow users to manage permissions for their created branches

On

Let users manage permissions for their created branches in all new repositories.

Repository settings

The following table summarizes the settings you can enable or configure for each individual Git repository.

Setting

Default

Description

Forks

On

Allow users to create forks from the repository.

Commit mention linking

On

Automatically create links for work items mentioned in a commit comment.

Commit mention work item resolution

On

Allow mentions in commit comments to close work items. Requires Azure DevOps Server 2020.1 update or later version.

Work item transition preferences

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 the repository, which requires Contribute permission to vote on pull requests.

Disable Repository

On

Disable access to the repository, including builds and pull requests, but keep the repository discoverable with a warning.

Searchable branches

On

Specify up to five more branches to participate in code search, which by default only applies to the default branch. Requires the Code Search extension installed and enabled.

Repository policies or options

The following table summarizes the policies or options you can set for either all or individual repositories. Policies set for All Repositories set the default for individual repositories added at a later date.

Policy or Option

Default

Description

Commit author email validation

Off

Block pushes with a commit author email that doesn't match the specified patterns. This setting requires Azure DevOps Server 2020.1 or later version.

File path validation

Off

Block pushes from introducing file paths that match the specified patterns. This setting requires Azure DevOps Server 2020.1 or later version.

Case enforcement

Off

Avoid case-sensitivity conflicts by blocking pushes that change name casing on files, folders, branches, and tags.

Reserved names

Off

Block pushes that introduce files, folders, or branch names that include platform reserved names or incompatible characters.

Maximum path length

Off

Block pushes that introduce paths that exceed the specified length.

Maximum file size

Off

Block pushes that contain new or updated files larger than the selected 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. When you set any policy on a branch, the following policies are automatically enforced:

  • Pull requests are required to update the branch.
  • The branch can't be deleted.

Note

Branch policies are applied to Pull Requests based on the target branch of the Pull Request. Branch policies should not be set on temporary branches that will be deleted after a pull request. Adding branch policies to temporary branches will cause automatic branch deletion to fail.

Policy

Default

Description

Require a minimum number of reviewers

Off

Require approval from a specified number of reviewers on pull requests.

Check for linked work items

Off

Encourage traceability by checking for linked work items on pull requests.

Check for comment resolution

Off

Check to see that all comments have been resolved on pull requests.

Limit merge types or Enforce a merge strategy

Off

Control branch history by limiting the available types of merge when pull requests are completed.

Build Validation

Off

Add, enable, or disable one or more policies to validate code by pre-merging and building pull request changes.

Status Checks or
Require approval from additional or external services

Off

Add, enable, or disable one or more policies to require other services to post successful status to complete pull requests.

Automatically included reviewers

Off

Add, enable, or disable one or more policies to designate code reviewers to automatically include when pull requests change certain areas of code.

Prerequisites

  • To configure policies, you must be a member of the Project Administrators security group, or have repository-level Edit policies permissions. For more information, see Set Git repository permissions.
  • To configure policies, you must be a member of the Project Administrators security group, or have repository-level Edit policies permissions. For more information, see Set Git repository permissions.

View and edit settings and policies

You can configure settings for all repositories across an organization or project, or for individual repositories. You can configure policies for all repositories, for individual repositories, or for specified branches across repositories. For information about setting branch policies, see Branch policies.

Note

It's best to configure repository settings either at the project level or for individual repositories, but not both. If you configure settings at more than one level, the system honors the most restrictive setting. Configuring settings at only one level reduces confusion and Git performance issues.

To configure repository settings and policies through the web portal, open Project settings> Repositories from your web browser.

  1. To view or modify settings or policies for all Git repositories, open the All Repositories page and choose Settings or Policies.

    Screenshot that shows repository Settings for All Repositories

    To configure settings and policies for a specific repository, select the Repositories tab, choose the repository, and then choose the Settings or Policies tab.

    Screenshot that shows repository Settings for the Fabrikam repository.

  2. The following screenshot shows the Settings tab selected. You can define these settings for all Git repositories or for an individual repository.

    Screenshot that shows the repo project Settings tab selected.

  3. The following screenshot shows the Policies tab selected. You can define these policies for all Git repositories or for an individual repository.

    Screenshot that shows the repo 'Policies' tab selected.

  1. From your web browser, open the project and choose Project settings, Repositories, and select your repository.

    Screenshot of the 'Project Settings' for your repository.

  2. To view and configure repository settings, select Options or Policies.

    The following screenshot shows Options for all repositories:

    Screenshot of the Options for all repositories.

    The following screenshot shows Options for the Fabrikam repositories:

    Screenshot of Options for the Fabrikam repository.

Default branch name

You can set a default repository branch name at the organization or project level. The organization-level setting takes effect for all new repositories across all projects in the organization. The project-level setting affects all new repositories in a project, and supersedes any name set at the organization level.

You can:

  • Choose any legal branch name to use when a repository is initialized.
  • Change the default name anytime to affect all future repositories.
  • Change the default branch name for any particular repository anytime.

If you don't enable the default branch name feature, repositories initialize with the Azure Repos default branch name main.

To set a default branch name at the organization level:

  1. On your Azure DevOps organization page, select Organization settings at lower left, and then select Repositories in the left navigation.
  2. On the All Repositories page, set Default branch name for new repositories to On, and then enter a default branch name.

Screenshot that shows the organization-level setting for Default branch name for new repositories.

To set a default branch name at the project level:

  1. On your Azure DevOps project page, select Project settings at lower left, and then select Repositories in the left navigation.
  2. On the Settings tab of the All Repositories page, set Default branch name for new repositories to On, and then enter a default branch name.

Screenshot that shows the project-level setting for Default branch name for new repositories.

Note

The Default branch name for new repositories setting requires Azure DevOps Server 2020.1 or later version.

Branch permission management

You can control who can manage permissions for repository branches by setting a permission management setting for all Git repositories or for individual repositories. If you enable the Allow users to manage permissions for their created branches setting at the All Repositories level, all new project repositories are configured to let users manage permissions for their created branches.

To manage this setting:

  1. On your Azure DevOps project page, select Project settings at lower left, and then select Repositories in the left navigation.
  2. On the Settings tab of the All Repositories page, set Allow users to manage permissions for their created branches to On or Off.

Screenshot that shows the project-level Allow users to manage permissions for their created branches setting.

To enable or disable this setting for individual repositories:

  1. Select Project Settings > Repositories, and then select a repository.
  2. On the Settings tab of the <Repository name> page, set Permissions management to On or Off.

Screenshot that shows the Permissions management repository setting.

Gravatar images

This setting enables or disables the use of Gravatar images for users outside your enterprise.

Gravatar images is an organization-level setting.

  1. On your Azure DevOps organization page, select Organization settings at lower left, and then select Repositories in the left navigation.
  2. On the All Repositories page, set Gravatar images to On or Off.

Screenshot that shows the organization-level setting for Gravatar images.

Gravatar images is a project-level setting for All Repositories.

  1. On your Azure DevOps project page, select Project settings at lower left, and then select Repositories in the left navigation.
  2. On the Settings tab of the All Repositories page, set Gravatar images to On or Off.

Gravatar images is a project-level setting for All Repositories.

  1. On your Azure DevOps project page, select Project settings at lower left, and then select Repositories in the left navigation.
  2. On the Settings tab of the All Repositories page, set Gravatar images to On or Off.

Enable forks

This repository setting controls whether users can create new server-side forks. Disabling this setting doesn't remove existing forks.

  1. From Project Settings, select Repositories in the left navigation.
  2. On the Repositories tab of the All Repositories page, select a repository.
  3. On the Settings tab of the <Repository name> page, set Forks to On or Off.

Screenshot that shows the Forks repository setting.

Work item linking settings

These repository settings manage work item linking.

  1. Select Project Settings > Repositories, and then select a repository.
  2. On the Settings tab of the <Repository name> page, turn the settings On or Off.

Screenshot that shows the work item linking repository settings.

Commit mention linking

When enabled, commit messages containing # followed by a valid work item ID automatically link the commit to that work item. Disable this setting if the repository previously used a different account or service. Those repositories might have commit messages with # mentions that don't match the work item IDs in the current account.

Commit mention work item resolution

Enable this setting to automatically complete work items when linked pull requests complete. This setting also allows specifying other work item transition states in pull request commit messages. For more information, 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. For more information, 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 remembers each user's last choice. Teams that want to discourage users from completing work items with their pull requests can disable this setting. Users must then opt in to completing work items each time they complete a pull request.

Strict Vote Mode setting

In certain situations, users who aren't contributors to a repository can submit a pull request and cause it to be merged, depending on policies. To prevent this possibility, enable Strict Vote Mode to change the required permission to vote on repository pull requests to Contribute. Enabling this setting is recommended if you rely on user forks in Azure Repos.

  1. Select Project Settings > Repositories, and then select a repository.
  2. On the Settings tab of the <Repository name> page, set Strict Vote Mode to On or Off.

Screenshot that shows the Strict Vote Mode repository setting.

Disable repository setting

Enabling this setting disables access to the repository, including builds and pull requests, but keeps the repository discoverable with a warning.

  1. Select Project Settings > Repositories, and then select a repository.
  2. On the Settings tab of the <Repository name> page, under Disable Repository, set Disable Repository to On or Off.

Screenshot that shows the Disable Repository setting.

Searchable branches setting

By default, code search in files applies only to the default branch. You can add up to five more branches to search.

Important

To search code in repositories, you must install the Marketplace Code Search extension. If you don't see Searchable Branches in the repository Settings tab, make sure you have the extension installed.

To add branches for code search:

  1. Select Project Settings > Repositories, and then select a repository.
  2. On the Settings tab of the <Repository name> page, select the + in Searchable Branches.
  3. Select a branch to include in search, and then select Add branch.

Screenshot that shows the Searchable Branches repository setting.

Cross-repo branch policies

You can set policies on a specific branch name, or on the default branch, across all repositories in a project. For example, you could require two minimum reviewers for all pull requests in every main branch for all project repositories.

To set policies to protect specific or default branch names across a project:

  1. From Project Settings, select Repositories in the left navigation.

  2. On the All Repositories page, select the Policies tab.

  3. Select the plus sign + in Branch Policies at the bottom of the page.

  4. On the Add branch protection screen, select Protect the default branch of each repository, or Protect current and future branches matching a specified pattern.

    If you select the second option, enter the branch name to protect. An informational message lets you know how many current branches are affected. Keep in mind that branch name (or the pattern you entered) is case-sensitive. The branch doesn't have to exist yet to protect the branch name.

  5. Select Create.

    Screenshot that shows enabling cross-repo branch policies.

  6. On the Cross-Repository policies for <branch name> page, set the policies you want for the protected branches. For more information about branch policies, see Branch policies.

    Screenshot that shows cross-repo branch policy settings.

Commit author email validation policy

This policy blocks commits to a repository by commit authors whose email addresses don't match a pattern.

  1. Select Project Settings > Repositories, and select a repository if you want to configure only that repository.

  2. On the Policies tab of the All Repositories or <Repository name> page, under Repository Policies, set Commit author email validation to On or Off.

  3. If you turn on the policy, specify the email address or addresses to match.

    You can specify exact email addresses or use wildcards. Use ; as a separator for multiple email patterns. Email patterns prefixed with ! are excluded. Order is important.

Screenshot that shows the Commit author email validation policy setting.

File path validation policy

You can set a policy that prevents commits to a repository from file paths that match a pattern.

  1. Select Project Settings > Repositories, and select a repository if you want to configure only that repository.

  2. On the Policies tab of the All Repositories or <Repository name> page, under Repository Policies, set File path validation to On or Off.

  3. If you turn on the policy, specify the path or paths to block.

    You can specify exact paths and wildcards. Exact paths begin with /. You can also specify multiple paths by using ; as a separator. Paths prefixed with ! are excluded. Order is important.

Screenshot that shows the File path validation policy setting.

Case enforcement policy

Git is case-sensitive, meaning that a file called Foo.txt is different from a file called foo.txt. However, Windows and macOS default to case-insensitive file systems, meaning that Foo.txt and foo.txt are the same name. This discrepancy can cause problems if someone on a case-insensitive system pushes files, folders, branches, or tags that differ only by letter case. For more information, see Git Cross-Platform Compatibility.

If most of your contributors are on Windows or macOS, it's best to enable the Case enforcement policy. 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 considered the same file. This setting affects files, folders, branches, and tags.

This setting prevents contributors from introducing case-only differences. The setting avoids case-sensitivity conflicts by blocking pushes that change name casing on files, folders, branches, and tags. The user has to rewrite their unpushed history to fix the problem, then try the push again.

This setting won't fix a repository that already contains objects that differ only by case. It's best to fix such issues before turning on the policy. Rename files and folders or re-create branches and tags to use non-conflicting names.

To set case enforcement policy:

  1. Select Project Settings > Repositories, and select a repository if you want to configure only that repository.
  2. On the Policies tab of the All Repositories or <Repository name> page, under Repository Policies, set Case enforcement to On or Off.

Screenshot that shows the Case enforcement policy setting.

Reserved names policy

Not all filenames are allowed on the three major OS file systems: Windows, macOS, and Linux. Commits to a shared repository might contain file or folder names that are invalid on one or more platforms. If invalid files or folders are fetched and checked out on these platforms, working directories can become corrupted. For more information, see Git Cross-Platform Compatibility.

You can enable or disable policies to place restrictions on file and folder names. The Reserved names setting blocks pushes to a repository that contain file or folder names that are invalid on all platforms. To see what names are invalid, see Git Cross-Platform Compatibility.

To set the reserved names policy:

  1. Select Project Settings > Repositories, and select a repository if you want to configure only that repository.
  2. On the Policies tab of the All Repositories or <Repository name> page, under Repository Policies, set Reserved names to On or Off.

Screenshot that shows the Reserved names policy setting.

Maximum path length policy

Not all path lengths are allowed on the three major OS file systems: Windows, macOS, and Linux. Commits to a shared repository might 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're invalid, working directories can become corrupted. For more information, see Git Cross-Platform Compatibility.

The Maximum path length setting blocks pushes that contain files or directories with path lengths that are invalid on any platform. To see what path lengths are invalid, see Git Cross-Platform Compatibility. When you enable this setting, the default maximum value is 248, because that maximum length is 100% supported across all three major platforms.

You can modify the maximum path value. For example, if you only have macOS or Linux developers in your organization, you might choose to set the maximum length to the value that's supported on both platforms, 1016. You might also choose to set a lower maximum path value to enforce your organization's directory-naming conventions.

To set the maximum path length policy:

  1. Select Project Settings > Repositories, and select a repository if you want to configure only that repository.
  2. On the Policies tab of the All Repositories or <Repository name> page, under Repository Policies, set Maximum path length to On or Off.
  3. If you turned on the setting, enter a maximum path length.

Screenshot that shows the Maximum path length policy setting.

Maximum file size policy

Large files checked into Git remain in the repository indefinitely, increasing clone times and disk usage. For guidance on managing large files, see Manage and store large files in Git.

The Maximum file size policy setting blocks 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, the push is blocked. The user must rewrite their unpushed history to remove the large file and try the push again.

To configure Maximum file size policy:

  1. Select Project Settings > Repositories, and select a repository if you want to configure only that repository.
  2. On the Policies tab of the All Repositories or <Repository name> page, under Repository Policies, set Maximum file size to On or Off.
  3. If you turned on the setting, select a maximum file size.

Screenshot that shows the Maximum file size policy setting.

Next steps

Improve code quality with branch policies