Edit

Share via

Naming restrictions and conventions

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

This article describes the naming rules, conventions, and restrictions for Azure DevOps components. Naming rules, restrictions, and conventions help guarantee a consistent user experience and provide compatibility with other applications.

General considerations

Common restrictions include not exceeding the character length for a name, not containing special characters, and maintaining uniqueness of names within an object set.

  • Length restrictions count the number of Unicode characters. Surrogate characters are composed of two Unicode characters, which count against the length restriction as two characters. For more information, see About Unicode and character sets.

  • As with other operating system files, ASCII control characters 1-31 and surrogate combinations aren't allowed. For general information about the operating system restrictions applied to file names, see Naming files, paths, and namespaces.

  • For limits on the number of items you can define, see Work tracking, process, and project limits.

Important

When you use the Azure DevOps APIs rather than the user interface (UI), you can directly specify a name that might include characters restricted in the UI. To maintain consistency and prevent unintended issues, follow the UI restrictions. Validate names programmatically and handle special characters appropriately.

System reserved names

Avoid using system reserved names like the following examples:

  • AUX
  • COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, COM10
  • CON
  • DefaultCollection
  • LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9
  • NUL
  • PRN
  • SERVER, SignalR
  • Web or WEB

For more information about reserved names, see File names, paths, and namespaces.

Azure Artifacts

Azure Artifacts universal packages and feeds must conform to the following restrictions:

Restriction type Restriction
Package name - Must be lowercase.
- Must start and end with alphanumeric characters.
- Can contain only alphanumeric characters and nonconsecutive hyphens -, underscores _, or periods ..
Package version - Must be lowercase without build metadata.
Feed name - Must start and end with alphanumeric characters.
- Not case sensitive, but can't differ from another feed name only by capitalization.
- Can't start with period . or underscore _ or end with period ..
- Can't include any of the following characters: @ ~ ; { } ' + = , < > | / \ ? : & $ * " # [ ] %.

Azure Boards

Azure Boards uses work items to plan and track software development projects. Work items describe the work to be done, assign work, track status, and coordinate efforts within a team. Different types of work items, such as user stories, tasks, bugs, and issues, track different types of information. For more information, see the Azure Boards documentation.

Work item tracking objects are associated with one or more names. All objects except work item types and global lists have friendly display names, which are unique, user-visible identifiers for fields. Using friendly names ensures consistency across projects and work item types in a project collection.

Work item types and global lists are associated with reference names. The system uses the reference names internally, and you can't change them once defined.

Several elements associated with work items have restrictions, including reference names, friendly names, field names, and attachment size.

Area and iteration paths

The Area Path and Iteration Path work item fields provide a tree structure hierarchy for grouping work. Area paths group work items by product, function, or feature area. Iteration paths group work items into sprints, milestones, or time periods for addressing the work.

These multi-node fields use the backslash \ character to denote the hierarchy of nodes within the tree structure. The names you assign to child nodes must conform to the following restrictions.

Restriction type Restriction
Node length Must not contain more than 255 characters.
Reserved names - Must not consist only of a period . or two periods ...
- Must not be a system-reserved name, such as PRN, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, COM10, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, NUL, CON, or AUX. For more information about reserved names, see File Names, Paths, and Namespaces.
Special characters for nodes - Must not contain Unicode control characters.
- Must not contain any one of the following characters: \ / : * ? " < > | # $ & * +.
- Must not contain characters prohibited by the local file system. For more information about Windows character restrictions, see Naming Files, Paths, and Namespaces.
Path length Must not contain more than 4,000 Unicode characters.
Path hierarchy depth Must be fewer than 14 levels deep.

Attachments

Files attached to work items must conform to the following restrictions.

Restriction type Restriction
File size Must not exceed the maximum size:
- Default maximum size: 4,096 kilobytes.
- Absolute maximum size: 2 gigabytes.

For more information, see Change the maximum attachment size for work items.

Board column and swimlane names

A board provides a visual flow of backlog work. As work progresses from planning to completion, you update the items on the board. Each column represents a work stage, and each card represents a work item at that stage of work.

You can customize a board by adding, removing, or renaming columns and swimlanes. Columns support the flow of work across the board, and swimlanes let you manage different work as horizontal lanes on the board.

Column and swimlane names must conform to the following restrictions.

Restriction type Restriction
Length Must not contain more than 256 Unicode characters.
Uniqueness - Column names must not be the same as any other column name on the board.
- Swimlane names must not be the same as any other swimlane name on the board.
Special characters Must not contain any Unicode control characters or surrogate characters.

Field names

Each work item type contains one or more fields that define the information stored for that work item type. Each work item field has an associated field reference name that uniquely identifies the field and can't be changed once assigned. For more information about built-in work item fields, see the Work item field index.

Work item field names are scoped to the project collection. If you rename a field name, you change it for all work items and work item types defined within all projects in the collection.

Work item field names must conform to the following restrictions.

Restriction type Restriction
Length Must not contain more than 128 Unicode characters.
Uniqueness Must be unique within the organization or project collection.
Special characters - Must contain at least one alphabetic character.
- Must not contain any of the following characters: . , ; ' : ~ \ / * ? " & % $ ! + = ( ) [ ] { } < > - |.
- Must not contain leading or trailing spaces.
- Must not contain two or more consecutive spaces.

Field reference names

The work item type definition language includes the concept of a field reference name. Field reference names can help you port definitions between Team Foundation project collections and allow non-Microsoft integrations to find and refer to specific fields. These names, like namespaces in .NET Framework applications, are globally unique.

The following fields are defined in a work item type definition of the process templates:

  • The System namespace is used only to define all core system fields that are mandatory for Team Foundation system functions. You can't create your own System.X field, because it might impede functionality.

  • The Microsoft namespace is used to define work item tracking fields. Although you can create your own Microsoft.X field, it isn't recommended because it might impede functionality or the ability to successfully update a project after an upgrade.

Customers and partners can create their own field namespaces for custom work item types. For descriptions of system fields and fields defined in the default process templates, see the Index of work item fields.

Important

You can't change field reference names. For example, if you change the field name Title to Header, the field reference name of that field doesn't change. Integrations and internal representations of fields should use the field reference name instead of the field name.

Field reference name examples

The following examples show valid field reference names in various namespaces.

System namespace examples Microsoft namespace examples Other namespace examples
System.Id, System.Title, System.CreatedBy, System.CreatedDate, System.ChangedBy, System.ChangedDate, System.State, System.Reason Microsoft.VSTS.Build.FoundIn, Microsoft.VSTS.Common.Activity, Microsoft.VSTS.Common.Discipline, Microsoft.VSTS.Common.Priority, Microsoft.VSTS.CMMI.TaskType, Microsoft.VSTS.TCM.AutomationStatus, Microsoft.VSTS.TCM.TestSuiteType FabrikamFiber.Common.Severity, FabrikamFiber.Common.Phase, FabrikamFiber.RiskManagement.RiskType, FabrikamFiber.RiskManagement.Resolution

Contoso.Common.BusinessPriority, Contoso.Bug.FoundInPhase, Contoso.Bug.FixInPhase

Field help text

The system displays help text at runtime to help users know what to enter into the field. Help text is scoped to a specific work item type in a specific project.

For the Inheritance process, you specify help text for a field through the Edit field dialog, Definition tab, Description. See Add a custom field to a work item type. For the on-premises XML process, you specify help text by using the HELPTEXT element. See Add or modify a field for work tracking.

Help text that you add must conform to the following restrictions.

Restriction type Restriction
Length Must not contain more than 255 Unicode characters.

Global lists

As you define work item types, you might find that some work item fields share the same set of allowed or suggested values. A global list is a set of list item values that you can define one time and use globally across all project collections within an instance of on-premises Azure DevOps Server.

A global list defined using the GLOBALLIST element contains one or more list items specified using the LISTITEM element. For details, see Define global lists.

Global lists must conform to the following restrictions.

Restriction type Restriction
Uniqueness The global list must be unique within the Azure DevOps Server instance.
Number of items Must not be empty. The global list must contain at least one LISTITEM element.

LISTITEM names must conform to the following restrictions.

Restriction type Restriction
Length - Must not contain more than 254 Unicode characters.
- Must not be empty.
Special characters - Must not contain leading or trailing white space.
- Must not contain two consecutive spaces.
- Must not contain the backslash \ character.
Scope Since global lists are available among all projects, they must not contain elements defined at the project level, such as project-specific group account definitions.

Define a reference name when you add or create a link type or category.

Restriction type Restriction
Length Must not contain more than 70 Unicode characters.
Uniqueness - Must not be the same as any other field reference name within the project collection.
- Must not be identical to any other field reference name after the system processes the names to replace all periods . with underscores _. For example, the field reference names My._Field and My..Field would both process as the same name: My__Field.
Special characters - Can use alphanumeric characters, underscores, hyphens, and periods.
- Can't contain consecutive hyphens --.
- Must contain at least one period ., but can't start or end with a period.
- Can't start with a numeral or underscore _.

Work item query names

You can use work item queries to list work items based on field criteria you specify. For more information, see About managed queries.

Restriction type Restriction
Length Must not contain more than 255 Unicode characters.
Special characters - Can't be empty.
- Must not contain any one of the following characters: / \ < > * ? " + | :.
Uniqueness - Must be contained in a folder and be named uniquely within the folder.

Work item tag names

Work item tags consist of one or two keywords that filter or define work tracking tools such as backlogs, boards, and queries. For more information, see Add work item tags to categorize and filter lists and boards.

Tag names must conform to the following restrictions.

Restriction type Restriction
Length - Must not contain more than 400 Unicode characters.
- Must not be null or empty.
Special characters - Must not contain separator characters , or ;.
- Must not contain Unicode control or format characters such as line feeds, paragraph separators, carriage returns, or other mismatched surrogate characters.

Azure Pipelines

Azure Pipeline objects must conform to the following naming restrictions.

Object type Restriction
Expressions - Must start with a lowercase or uppercase alphabetic character or underscore, followed by lowercase or uppercase alphabetic characters, numerals, or underscores _.
Variables - Must contain only alphanumeric characters, periods ., and underscores _.
- Can't begin with the reserved prefixes endpoint, input, secret, path, or securefile, case insensitive.
Stages - Stage name must contain only alphanumeric characters and underscores _.
- Name must not start with a numeral.
Jobs and deployment jobs - Job name must contain only alphanumeric characters and underscores _.
- Name must not start with a numeral.
- Name can't contain keywords like deploy.
Matrix job strategy - Matrix configuration name must contain only alphanumeric characters and underscores _.
- Name must start with an alphabetic character.
- Maximum length: 100 characters.
Build resource - Alias or name of build artifact must contain only alphanumeric characters, hyphens -, and underscores _.
Container resources - Container ID must contain only alphanumeric characters, hyphens -, and underscores _.
Package resources - Package artifact alias must contain only alphanumeric characters, hyphens -, and underscores _.
Pipeline resources - Pipeline ID must contain only alphanumeric characters, hyphens -, and underscores _.
Repository resources - Repository alias must contain only alphanumeric characters, hyphens -, and underscores _.
Webhook resources - Webhook name must contain only alphanumeric characters, hyphens -, and underscores _.
Steps - Step name ID must contain only alphanumeric characters, hyphens -, and underscores _.

For more information, see the Azure Pipelines documentation.

Azure Repos

Azure Repos repositories can be Git-based or Team Foundation Version Control (TFVC)-based.

Each Azure DevOps project can contain multiple Git repositories. For more information, see the Azure Repos Git documentation.

Git repository names must conform to the following restrictions.

Restriction type Restriction
Length Must not contain more than 64 Unicode characters.
Uniqueness Must not be identical to any other Git repo name in the project.
Special characters - Must not contain any Unicode control characters or surrogate characters.
- Must not contain the following printable characters: \ / : * ? " < > ; # $ * { } , + = [ ] |.
- Must not start with an underscore _.
- Must not start or end with a period ..
- Must not be a system reserved name.
- Important: Although you can include spaces within repo names, it isn't recommended.

For information on naming restrictions for other Git items such as branches and tags, see git check-ref-format.

Computer names

The computer name where you install Azure DevOps is associated with the name of the server. Both the operating system and Active Directory impose certain restrictions on computer names, as described in the following articles:

Team Foundation Build

Team Foundation Build lets you manage all the aspects of the build process on a single computer. By using Team Foundation Build, you can synchronize sources, compile the application, run associated unit tests, perform code analysis, release builds on a file server, and publish build reports.

Build computer

Team Foundation Build is a separate installation from the Azure DevOps Server application tier, data tier, or Visual Studio client. You can choose a separate computer or install the build side-by-side on the client computer or servers.

Your on-premises build computer must conform to the following restrictions.

Restriction type Restriction
Disk space Must contain sufficient space for the build because insufficient space leads to failed builds.
Build directory Must be a local path such as C:\BuildDirectory.
Drop location directory Must be a UNC path such as \server\share*.
Drop location permissions Each generated build must be put in a new directory in the drop folder.
- The Team Foundation Server Service account, for example Domain\TFSSERVICE, must have Full Control access to the UNC drop location.
- The UNC drop location must be a shared folder.
Team Foundation Build Service account If you change the TFS Service account after the initial installation, you must make sure that:
- The account is a member of the Build Services group.
- The account has read/write permissions to the temporary folders and the ASP.NET temporary folder.
- The account has Full Control permission to the build directory and drop location.
Firewall If the build computer is firewall enabled, make sure that the program tfsbuildservice is in the exceptions list.

Build types

Build types are the conditions for building a single solution or a set of solutions in a project. To run a build, you can create a new build type or use an existing build type.

Build type names must conform to the following restrictions.

Restriction type Restriction
Uniqueness Must not be the same as any other build type name in the project.
Special characters Must not contain the dollar-sign $ character.

Build quality

The build quality lets you attach a quality level or completion state to a completed build. For a list of the default build quality values, see Rate the quality of a completed build. Team Foundation Build also lets you create new values for the build quality type.

Build quality names must conform to the following restrictions.

Restriction type Restriction
Length Must not contain more than 256 Unicode characters.
Uniqueness Must not be the same as any other build quality name on the Team Foundation Build computer.

Project collection names

The project collection is the organizing structure you use to define and control a group of projects for Azure DevOps Server. The project collection identifies a group of projects and their resources. The project collection name is also part of the connection string used to connect team members to projects.

The default collection name assigned to a project collection corresponds to DefaultCollection. For more information, see Manage project collections.

Project collection names must conform to the following restrictions.

Restriction type Restriction
Length Must not contain more than 64 Unicode characters.
Uniqueness - Must not be identical to any other collection name in your on-premises deployment.
- If your deployment includes SharePoint Products or SQL Server Reporting Services, their names can't be identical to the name and full path of an existing SharePoint site, report server, or Reporting Services website.
Special characters - Must not contain any Unicode control characters or surrogate characters.
- Must not contain the following printable characters: \ / : * ? " < > ; # $ * { } , + = [ ] |.
- Must not contain an ellipsis ... or a double period ...
- Must not start with an underscore _.
- Must not start or end with a period ..
Must not be a system reserved name.

Organization names

The organization is the organizing structure you use to define and control a group of projects for Azure DevOps Services. The organization identifies a group of projects and their resources.

Important

Follow these guidelines when you create your organization name:

  • Use only letters from the English alphabet
  • Start your organization name with a letter or number
  • Use letters, numbers, or hyphens after the initial character
  • Keep your organization name under 50 Unicode characters
  • End with a letter or number

If you use any disallowed characters, the following error message displays: VS850015: The specified name is not allowed to be used: {Organization name}.

Process and process templates

A process defines the building blocks of the work item tracking system and other subsystems that you can access after connecting to a project. Both process and process template refer to an interdependent set of files used to create a project. For information about the default processes, see About processes and process templates.

Processes that you define or customize must conform to the following restrictions.

Restriction type Restriction
Length Must not contain more than 256 Unicode characters.
Uniqueness - Must be unique across Azure DevOps. If you upload a template with the same name as an existing template, the existing template is overwritten.
Process template file size Must not exceed 2 gigabytes.

Project names

A project establishes a repository for source code and a place for teams to plan, track progress, and collaborate. The name of the project is part of the connection string used to connect team members to projects.

Names you assign to projects that you create must conform to the following restrictions.

Restriction type Restriction
Length Must not contain more than 64 Unicode characters.
Uniqueness Must not be identical to any other name in the organization, project collection, or SharePoint Web application or SQL Server report for the collection.
Reserved names - Must not be a system reserved name.
- Must not be one of the hidden segments used for IIS request filtering like App_Browsers, App_code, App_Data, App_GlobalResources, App_LocalResources, App_Themes, App_WebResources, bin, or web.config.
Special characters - Must not contain any Unicode control characters or surrogate characters.
- Must not contain the following printable characters: \ / : * ? " ' < > ; # $ * { } , + = [ ] |.
- Must not start with an underscore _.
- Must not start or end with a period ..

Security groups

You can use Azure DevOps security groups to apply certain rights or permissions to a group of users. Groups might consist of Microsoft Entra ID or Active Directory accounts, Azure DevOps security groups, Windows user or group accounts, or a combination. For more information, see Add Active Directory / Microsoft Entra users or groups to a built-in security group.

Security groups must conform to the following restrictions.

Restriction type Restriction
Security group account name length Must not contain more than 256 Unicode characters.
Uniqueness - Project-level group accounts must not match any other group name in the same project.
- Organization or collection-level group accounts must not match any other name of a group account in the organization or project collection.
Reserved group names Must not be named with a $NAMESPACE at either the project or the server level.
Special characters - Must not contain any Unicode control characters or surrogate characters.
- Must not contain the following printable characters: , / \ [ ] : < > + = ; ? * |.
- Must not include nonprintable characters in the ASCII value range of 1-31.
- Must not end in a period ..

Team names

Team names identify a group of individuals or groups that work together as a team in a project. Team members use this name to connect to the team or to query against members defined for a team. Team names must conform to conventions that allow them to be rendered as part of a valid URL.

Each team name must be unique within a single project, but there are no restrictions on using the same team name in different projects within an organization or project collection. For more information, see Add another team or a hierarchy of teams.

Team names must conform to the following restrictions.

Restriction type Restriction
Length Must not contain more than 64 Unicode characters.
Uniqueness Must not be identical to any other team name in the project.
Reserved names Must not be a system reserved name.
Special characters - Must not contain any Unicode control characters or surrogate characters.
- Must not contain the following printable characters: \ / : * ? " < > ; # $ * { } , + = [ ] |.
- Must not contain an ellipsis ... or a double period ...
- Must not start with an underscore _.
- Must not start or end with a period ..

User account names

User accounts identify users added to a project or project collection. User accounts might correspond to entries within Active Directory, Microsoft Entra ID, or Windows server group.

To add user accounts to a project, see Add users to a project or team. User accounts that you add to an organization or collection must conform to the following restrictions.

Restriction type Restriction
Account name length Must not contain more than 256 Unicode characters.
Uniqueness Must not match any other user account in the organization or project collection.
Reserved group names Must not be named with a $NAMESPACE at either the project or the server level.
Special characters - Must not include the following printable characters: , " / \ [ ] : < > + = ; ? * |.
- Must not include nonprintable characters in the ASCII value range of 1-31.
- Must not end in a period . or a dollar sign $.
- Must not include the following Unicode categories: LineSeparator, ParagraphSeparator, Control, Format, OtherNotAssigned.

Wiki page and file names

Each wiki page corresponds to a file in the wiki Git repository. The following restrictions apply to page file names and the file size:

  • File name: When choosing a name for the page file, keep in mind that the fully qualified path to the file should be 235 characters or less. The full path to the page consists of the repo URL, the folder path to the page file, and the page file name. For example, https://github.com/ExampleWiki/Contributors/Code/How-to-add-code-to-the-project.md.

  • Uniqueness: The page file name must be unique within its folder location in the wiki repo hierarchy. The name is case sensitive.

  • Special characters: The page file name has restrictions about the following special characters:

    • No Unicode control characters or surrogate characters
    • No printable characters: forward slash /, back slash \, hash #
    • No period . symbol at the start or end of the name

  • File size: The maximum page file size is 18 MB.

  • Attachment file size: The maximum size for any attachment to a page file is 19 MB.

Allowed special characters

Several special characters are allowed in a page file name, such as the colon : and hyphen -. For example, you might name a Markdown file as FAQ:0525 or Setup-Guide.

Important

To avoid errors in page syntax and browser navigation, don't use the space character ( ) in page file names. If you name your page files based on the page title, replace any spaces in the page title with a hyphen (-) in the file name.

The following table lists the special characters allowed in wiki page file names and the corresponding URI encoded string:

Character Symbol URI string
Colon : %3A
Left angle bracket < %3C
Right angle bracket > %3E
Asterisk (wildcard) * %2A
Question mark ? %3F
Pipe | %7C
Hyphen (dash) - %2D
Double quote " %22

For example, the file name FAQ:0525 is encoded as FAQ%3A0525.

Related content

  • Last updated on