Custom fields

Custom fields add specialized information to work items, such as issues and epics, that match your specific planning needs. Configure custom fields for a group to track data points like business value, risk assessment, priority ranking, or team attributes. These fields appear in all work items across the group, its subgroups, and projects.

Custom fields help teams standardize how they record and report information across the entire workflow. This standardization creates consistency across projects and supports more powerful filtering and reporting capabilities. Choose from various field types to accommodate different data requirements and planning scenarios:

• Single-select
• Multi-select
• Number
• Text

Configure custom fields for a group

Configure custom fields for top-level groups to make them available for work items in that group, its subgroups, and projects.

Create a custom field

Create custom fields to capture the specific information your team needs to track. You can configure each field for one or more work item types, tailoring your workflow to your organization’s requirements.

Keep these limits in mind:

• A top-level group can have at most 50 active custom fields.
• A work item type can have at most 10 custom fields assigned to it.

Prerequisites:

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

To create a custom field:

1. On the left sidebar, select Search or go to and find your group. This group must be at the top level.
2. Select Settings > Issues.
3. Select Create field.
4. Complete the fields:

   • In Type, select what type the field should be:

     • Single-select
     • Multi-select
     • Number
     • Text field

     The field type cannot be changed after you create the field.

   • In Use on, select the work item types where you want this field to be available.

   • In Options (on single-select and multi-select fields), enter the possible select options. A single-select or multi-select field can have at most 50 select options.

     • Reorder options by dragging the grip icon ( ) to the left of each option.
5. Select Save.

Edit a custom field

Edit existing custom fields to reflect changing needs in your organization. You can modify a field’s name, the work item types it applies to, and the available options without losing existing data.

Prerequisites:

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

To edit a custom field:

1. On the left sidebar, select Search or go to and find your group. This group must be at the top level.
2. Select Settings > Issues.
3. Next to the field you want to edit, select Edit <field name> ( ).
4. Make changes to any of the fields.
5. Select Update.

Archive a custom field

Archive custom fields that are no longer needed while preserving their historical data. Archiving removes the field from any work items that had them.

Prerequisites:

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

To archive a custom field:

1. On the left sidebar, select Search or go to and find your group. This group must be at the top level.
2. Select Settings > Issues.
3. Next to the field you want to archive, select Archive <field name> ( ).

Unarchive a custom field

Restore a previously archived custom field when you need to use it again. Work items that had values set for this field retain the same values they had before the field was archived.

Prerequisites:

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

To unarchive a custom field:

1. On the left sidebar, select Search or go to and find your group. This group must be at the top level.
2. Select Settings > Issues.
3. Select the Archived tab to list archived fields.
4. Next to the field you want to unarchive, select Unarchive <field name> ( ).

Set custom field values for a work item

Add relevant information to work items by using the custom fields configured for your group.

Prerequisites:

• You must have at least the Planner role for the work item’s project or group.
• If you have the Guest role, you can set custom fields only when creating a work item.

1. Go to a work item.
2. On the right sidebar, find the section for the custom field you want to edit, and then select Edit.
3. Enter or select the desired value.
   • A text field value can have at most 1024 characters.
4. Select any area outside the field.

Field type selection guide

When creating custom fields, choose a field type that matches the kind of data you want to track. The right field type improves data quality and makes reporting more effective.

Single-select fields

Use single-select fields when:

• Users should choose exactly one option from a predefined list.
• The options are mutually exclusive.
• You want to enforce consistency and prevent free-form input.

Single-select fields work well for:

• Priority indicators (like High, Medium, Low)
• Category assignments
• Team assignments
• Approval states
• Priority levels

Multi-select fields

Use multi-select fields when:

• Multiple values might apply simultaneously.
• You need to track overlapping attributes.
• Items might belong to multiple categories.

Multi-select fields work well for:

• Tags or labels
• Skills required
• Affected components
• Stakeholder groups
• Feature capabilities

Number fields

Use number fields when:

• You need to collect quantitative data.
• You want to perform calculations or aggregations.
• The information needs to be sortable numerically.

Number fields work well for:

• Cost estimates
• Time estimates
• Business value scores
• Ranking or prioritization scores
• Percentage complete

Text fields

Use text fields when:

• You need to capture unique information that doesn’t fit predefined categories.
• The data is highly variable.
• You need to provide context or details.

Text fields work well for:

• Additional context
• External reference IDs
• Contact information
• Brief notes or comments
• URLs or links

Naming conventions for custom fields

Consistent naming conventions for custom fields make them easier to understand and use. Good field names improve adoption and data quality.

General guidelines

• Keep names concise but descriptive.
• Use clear, specific language that your organization understands.
• Be consistent with capitalization (title case is recommended).
• Avoid abbreviations unless they’re widely understood.
• Include the unit of measure when applicable.

Naming single-select and multi-select fields

Start with the category name, followed by a descriptor. For example:

• Risk Level instead of Risk
• Customer Segment instead of Segment
• Development Phase instead of Phase
• Approval Status instead of Status

Naming number fields

Include the unit of measurement in the field name. For example:

• Effort Points instead of Points
• Budget Estimate ($) instead of Budget
• Implementation Time (days) instead of Time
• Business Value Score instead of Value

Naming text fields

Clearly indicate what information should be entered. For example:

• External Reference ID instead of Reference
• Implementation Notes instead of Notes
• Requirements Source instead of Source

Team-specific prefixes

If multiple teams use the same GitLab instance, consider adding team prefixes to avoid confusion:

• DEV: Sprint Priority
• QA: Test Environment
• UX: Design Status
• PM: Market Segment

This approach helps teams quickly identify which fields are relevant to their work.