Naming restrictions and conventions

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

Most components in Azure DevOps must follow naming restrictions and conventions. Restrictions help guarantee a consistent user experience and provide compatibility with other applications.

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

Important

When using the API, rather than user interface (UI), the API allows you to directly specify a name, which includes characters that might be restricted in the UI.

Best practices:

• Follow the UI restrictions to maintain consistency and prevent unintended issues.
• Validate names programmatically and handle any special characters appropriately.

General considerations

The length restrictions in this article get measured by the number of Unicode characters permitted. Surrogate characters are composed of two Unicode characters, which count as two characters against the length restriction. For more information, see About Unicode and Character Sets.

As with other operating system files, ASCII control characters (ASCII 1-31) and surrogate combinations are also not allowed. For general information about the operating system restrictions applied to file names, see Naming Files, Paths, and Namespaces.

Note

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

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

Universal packages must conform to the following restrictions.

Restriction type	Restriction
Package name	- Must be lowercase. - Must start and end with letters or numbers. - Must only contain letters, numbers, and nonconsecutive dashes, underscore, or periods.
Package version	Must be lowercase without build metadata.

Azure Boards

You use work items to capture information to plan and track your software development projects. With work items, you can describe the work to be done, assign work, track status, and coordinate efforts within your team. Different types of work items—such as user stories, tasks, bugs, and issues—track different types of information. For more information, see Azure Boards documentation.

All work item tracking objects are associated with one or more names. Most have friendly display names, except work item types and global lists, which are associated with reference names. A friendly name is a unique, user-visible identifier for a field. Using friendly names ensures consistency across projects and work item types in a project collection. The system uses the reference name internally and you can't change it once defined.

There are restrictions on several elements that are associated with work items, including reference and friendly names, field names, and attachment size.

Area and iteration paths

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

These multi-node fields use the backslash \ characters to denote the hierarchy of nodes within the tree structure.

The names you assign to child nodes to these fields 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.

Board column and swimlane names

Your board turns your backlog into an interactive signboard, providing a visual flow of work. As work progresses from idea to completion, you update the items on the board. Each column represents a work stage, and each card represents a user story (blue cards) or a bug (red cards) at that stage of work.

Customize your board by adding, removing, or renaming columns and swimlanes. Columns support the flow of work across the board. Swimlanes allow you to manage different classes of 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 work item fields. These fields define the information stored for work items based on the work item type. Each work item field has an associated field reference name. The field reference name uniquely identifies each field and can't be changed once assigned. For more information about out-of-box work item fields, see Work item field index.

Work item field names must conform to the following restrictions.

Restriction type	Restriction
Length	Must not contain more than 128 Unicode characters.
Uniqueness	- Field names must contain at least one alphabetic character. - Must not contain any one of the following characters: . , ; ' : ~ \ / \ * ? " & % $ ! + = () [] {} <> - |. - Must not contain leading or trailing spaces. - Must not contain two or more consecutive spaces.
Special characters	Must be unique within the organization or project collection. Work item field names are scoped to the project collection. If you rename a field name, you change it for all work items and WITs defined within all projects in the collection.

Field reference names and portability

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

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. These fields are defined in a work item type definition of the process templates.

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 Index of work item fields.

Important

• Field reference names can't be renamed. If for example, you changed the field name "Title" to "Header", the field reference name of that field remains the same. Integrations and internal representations of fields should use the field reference name instead of depending on the field name itself.
• Although you can create your own Microsoft.X field, we don't recommend that you do so, as it might impede functionality or the ability for the Configure Features wizard to successfully update a project after an upgrade.

Examples of field reference names

The following examples show valid field reference names, in various namespaces. Customers and partners can also define their own namespaces to support their custom work item types.

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	The fictitious company, Fabrikam Fiber, might define the following custom work item fields: FabrikamFiber.Common.Severity, FabrikamFiber.Common.Phase, FabrikamFiber.RiskManagement.RiskType, FabrikamFiber.RiskManagement.Resolution The fictitious software company Contoso Corporation might define the following work item fields: Contoso.Common.BusinessPriority, Contoso.Bug.FoundInPhase, Contoso.Bug.FixInPhase

Work item tags

Work item tags correspond to one or two keyword phrases to filter work tracking tools such as backlogs, boards, and queries or define 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 a line feed, paragraph separator, carriage return, or other mismatched surrogate characters.
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.

Azure Pipelines

Azure Pipeline definitions must conform to the following restrictions.

Restriction type	Restriction
Job name	- Must only contain alphanumeric characters and '_'. - Must not start with a number. - Must have a unique name. - Must not contain keywords, for example: "deployment."
Stage name	- Must only contain alphanumeric characters and '_'. - Must not start with a number. - Must not contain keywords, for example: "deployment."
Expressions	Must start with a-Z or _AND, followed by a-Z, 0-9, or _.

For more information, see Azure Pipelines documentation.

Azure Repos (Git)

Each Azure DevOps project can contain multiple Git repositories. The names you assign to Git repositories must conform to the following restrictions. For more information, see Azure Repos Git documentation. For more information on naming restrictions for other Git items such as branches and tags, see git check-ref-format.

Important

Although you can include spaces within repo names, we don't recommend that you do so.

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.

Azure Repos (TFVC)

Team Foundation version control (TFVC) provides a central repository for files and the commands that are required to manage those files across a team. It also provides customizable check-in policies, branching, merging, shelving, and many other features. For more information, see Azure Repos TFVC documentation

Version control paths must conform to the following restrictions. See also Optimize your workspace.

Restriction type	Restriction
Server source control folder path length	- Must not contain more than 259 Unicode characters for a single folder or file name. - Must not contain more than 388 Unicode characters for a directory. - Must not contain more than 399 Unicode characters for a combined directory and file name.
Local folder path length	- Must not contain more than 248 Unicode characters for a directory. - Must not contain more than 260 Unicode characters for a combined directory and file name.
Web portal and REST-specific length restrictions	Must not contain more than 215 Unicode characters for a combined project name, directory, and file name.

In the web portal and REST API, certain operations have a more restrictive path length than Visual Studio and TF.exe clients. These operations include Edit, Rename, and Delete, and occur because the web portal/REST uses a randomly generated workspace for concurrency when pending the changes.

TFVC files

The version control system stores many different types of files. Set up Team Foundation version control on your dev machine provides details on how to add existing Visual Studio projects or solutions.

Files and folders you add to Team Foundation version control must conform to the following restrictions.

Restriction type	Restriction
Files and folders	- Names must not contain the following printable characters: \ / : * ? " < > ;. - Folders must not be outside the mapped directory for the active workspace.
File names	- Must not begin with a $. - Must not contain the following printable characters: \ / : * ? " < > ; |.

TFVC labels

In Team Foundation version control (TFVC), a label is a name applied to a specific set of revisions. You can attach labels to a set of unrelated files in version control, which lets you retrieve the files or act upon them as a group. The following table describes the restrictions put on label names.

Restriction type	Restriction
Length	Must not contain more than 64 Unicode characters.
Special characters	- Can't end with a space ( ) or period .. - Must not contain the following printable characters: \ / : * ? " < > ; @ |.

TFVC Shelvesets

Shelvesets enable you to set aside temporarily a batch of pending changes and then, as an option, remove the pending changes from your workspace. Later, you can restore the changes in a shelveset to your workspace or put them into another user's workspace.

Shelveset names must conform to the following restrictions.

Restriction type	Restriction
Length	Must not contain more than 64 Unicode characters.
Special characters	Must not contain the following printable characters: \ / : * ? " < > & ; |.

TFVC workspaces

A workspace is a client-side copy of the files and folders in Team Foundation version control (TFVC). When you create multiple workspaces, you can have different versions of the same version control folder on a client computer. Create and work with workspaces provides more details.

Workspace names must conform to the following restrictions.

Restriction type	Restriction
Length	Must not contain more than 64 Unicode characters.
Special characters	- Must not end with a space ( ). - Must not contain the following printable characters: \ / : * ? " < > ; |.

Organization names

Important

Adhere to the following guidelines when you create an 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
• Ensure that your organization doesn't exceed 50 Unicode characters
• End with a letter or number

If you use any of the disallowed characters, you get the following error message: 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 have access to after connecting to a project.

Note

Terminology: Both "process" and "process template" refer to an interdependent set of files used to create a project. For more information, see About processes and process templates, which describes the differences among the three default processes available to you.

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 GB (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 project collection, the SharePoint Web application that supports the collection, or the instance of SQL Server Reporting Services that supports the collection.
Reserves 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

With Azure DevOps security groups, you can apply certain rights or permissions to a group of users.

On-premises groups might consist of Active Directory group accounts, Azure DevOps security groups, Windows user accounts, Windows group accounts, or any mixture of these types. 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. - Collection-level group accounts must not match any other name of a group account in the 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 .. - Must not include commas ,.

Team names

Team names identify a group of individuals or groups that collectively 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. However, there aren't any restrictions on using the same team name in different projects within a 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 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 people added to a project or project collection. User accounts might correspond to entries within Active Directory, Microsoft Entra ID, Windows server group.

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

Restriction type	Restriction
Account name length	Must not contain more than 256 Unicode characters.
Uniqueness	Must not match any other user account added to the 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 commas ,. - Must not include the following Unicode categories: LineSeparator, ParagraphSeparator, Control, Format, OtherNotAssigned.

Wiki page and file names

Each wiki page corresponds to a file within the wiki Git repo. Names you assign to a wiki page title must conform to the following restrictions.

Restriction type	Restriction
File name	The fully qualified page path shouldn't exceed 235 characters.
Uniqueness	Page titles are case sensitive and must be unique within the wiki hierarchy.
Special characters	- Must not contain any Unicode control characters or surrogate characters. - Must not contain the following printable characters: / \ #. - Must not start or end with a period ..
File size	Must not exceed the maximum of 18 MB.
Attachment file size	Must not exceed the maximum of 19 MB.

Special characters in Wiki page titles

You can specify page titles which contain one or more of these special characters : < > * ? | -. For example, you can name a Markdown file as "FAQ?" or "Set-up guide". The characters have the following URI encoded strings:

Character	Encoded string
:	%3A
<	%3C
>	%3E
*	%2A
?	%3F
|	%7C
-	%2D
"	%22

Related articles

• Azure Artifacts count and size limits
• Work tracking, process, and project limits
• Customize work tracking objects to support your team's processes
• Customize a process template