Configurable work item types

Customize work item types to match your planning workflows. Create new types with names and icons, and control which types are available in your projects. A work item type configuration cascades to all projects.

New types are available at the project level only. Their widgets and hierarchy restrictions match those of issues. You can associate new types with custom fields and status lifecycles. You can also filter by work item type in work item lists, saved views, and issue boards.

Limits and naming rules

You can have a maximum of 40 work item types in a top-level group or organization, including types provided by GitLab. Type names must be unique in a namespace or organization and no more than 48 characters. A type cannot share a name with another type, including archived and disabled types. Vulnerability, merge request, commit, pipeline, alert, review, diff, report, and sha are reserved names that cannot be used.

When you rename a type (for example, rename Feature to Enhancement), the original name is available for a new type. You can rename a type back to its original name if that name has not been taken.

This conversion continues to return Global IDs in the format: gid://gitlab/WorkItems::/<type identifier> to maintain compatibility with existing customer automations.

Each work item type has one of the following states:

Create a work item type

Create a work item type with a name and icon to represent a specific category of work.

Prerequisites:

• On GitLab.com: You must have at least the Maintainer role for the top-level group.
• On GitLab Self-Managed: You must be an instance administrator or organization owner.

To create a work item type:

1. Go to the work items settings:
   • On GitLab.com: In the top bar, select Search or go to and find your top-level group. In the left sidebar, select Settings > Work items.
   • On GitLab Self-Managed: In the upper-right corner, select Admin. In the left sidebar, select Settings > Work items.
2. In the Work item types section, select New type.
3. Enter a name for the type.
4. Select an icon.
5. Optional. Select Enable for new projects to automatically enable this type in any new projects created under the group. Existing projects are not affected.
6. Select Save.

Edit a work item type

Update the name or icon of an existing work item type.

Prerequisites:

• On GitLab.com: You must have at least the Maintainer role for the top-level group.
• On GitLab Self-Managed: You must be an instance administrator or organization owner.
• The type must not be locked or archived.

To edit a work item type:

1. Go to the work items settings:
   • On GitLab.com: In the top bar, select Search or go to and find your top-level group. In the left sidebar, select Settings > Work items.
   • On GitLab Self-Managed: In the upper-right corner, select Admin. In the left sidebar, select Settings > Work items.
2. In the Work item types section, find the type you want to edit.
3. Select Edit name and icon.
4. Update the name, icon, or both.
5. Select Save.

Archive a work item type

Archive a work item type to remove it from all lists, filters, and creation flows. Archived types remain in the system, and existing work items of that type are not affected.

Prerequisites:

• On GitLab.com: You must have at least the Maintainer role for the top-level group.
• On GitLab Self-Managed: You must be an instance administrator or organization owner.

To archive a work item type:

1. Go to the work items settings:
   • On GitLab.com: In the top bar, select Search or go to and find your top-level group. In the left sidebar, select Settings > Work items.
   • On GitLab Self-Managed: In the upper-right corner, select Admin. In the left sidebar, select Settings > Work items.
2. In the Work item types section, find the type you want to archive.
3. Select Archive.
4. In the confirmation dialog, select Archive.

Archived types are visible only at the top-level group or organization level in the Archived tab. They are not visible at the subgroup or project level.

Unarchive a work item type

Restore an archived work item type to make it available again.

Prerequisites:

• On GitLab.com: You must have at least the Maintainer role for the top-level group.
• On GitLab Self-Managed: You must be an instance administrator or organization owner.
• The total number of active types must be below the maximum of 40.

To unarchive a work item type:

1. Go to the work items settings:
   • On GitLab.com: In the top bar, select Search or go to and find your top-level group. In the left sidebar, select Settings > Work items.
   • On GitLab Self-Managed: In the upper-right corner, select Admin. In the left sidebar, select Settings > Work items.
2. In the Work item types section, select the Archived tab.
3. Find the type you want to restore.
4. Select Unarchive.
5. In the confirmation dialog, select Unarchive.

Type availability controls

Control which work item types are available in your projects. Type availability has three layers:

• Type customization in projects: A switch at the top-level group or organization that allows or prevents projects from customizing type availability. Disabled by default.
• Per-type availability for all projects: Enable or disable a specific type across all descendant projects.
• Per-project availability: Individual projects can enable or disable types for their own scope.

Allow type customization in projects

Control the ability for projects to customize which types are available.

Prerequisites:

• On GitLab.com: You must have at least the Maintainer role for the top-level group.
• On GitLab Self-Managed: You must be an instance administrator or organization owner.

To toggle type customization:

1. Go to the work items settings:
   • On GitLab.com: In the top bar, select Search or go to and find your top-level group. In the left sidebar, select Settings > Work items.
   • On GitLab Self-Managed: In the upper-right corner, select Admin. In the left sidebar, select Settings > Work items.
2. In the Type customization in projects section, select Enable or Disable.

When you disable type customization, all types are treated as enabled in all projects regardless of previous visibility settings. Per-project overrides are preserved but ignored. Re-enabling type customization restores the previous configuration.

Enable or disable a type for all projects

Control the availability of a specific type across all descendant projects at once. This removes any per-project overrides for that type.

Prerequisites:

• On GitLab.com: You must have at least the Maintainer role for the top-level group.
• On GitLab Self-Managed: You must be an instance administrator or organization owner.

To enable or disable a type for all projects:

1. Go to the work items settings:
   • On GitLab.com: In the top bar, select Search or go to and find your top-level group. In the left sidebar, select Settings > Work items.
   • On GitLab Self-Managed: In the upper-right corner, select Admin. In the left sidebar, select Settings > Work items.
2. In the Work item types section, find the type.
3. From the type actions menu, select Enable for all projects or Disable for all projects.

Enable or disable a type in a project

Control which types are available in a specific project.

Prerequisites:

• You must have at least the Maintainer role for the project.

To enable or disable a type in a project:

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select Settings > Work items.
3. In the Enabled work item types section, find the type.
4. Toggle the type on or off.

When you disable a type in a project, the type cannot be used to create new work items in that project. Existing work items of that type are not affected.