doc/user/work_items/custom_fields.md
{{< details >}}
{{< /details >}}
{{< history >}}
custom_fields_feature.
Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated.custom_fields_feature removed.{{< /history >}}
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:
Configure custom fields for top-level groups to make them available for work items in that group, its subgroups, and projects.
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:
Prerequisites:
To create a custom field:
In Type, select what type the field should be:
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.
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:
To edit a custom field:
<field name> ({{< icon name="pencil" >}}).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:
To archive a custom field:
<field name> ({{< icon name="archive" >}}).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:
To unarchive a custom field:
<field name> ({{< icon name="redo" >}}).Add relevant information to work items by using the custom fields configured for your group.
Prerequisites:
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.
Use single-select fields when:
Single-select fields work well for:
High, Medium, Low)Use multi-select fields when:
Multi-select fields work well for:
Use number fields when:
Number fields work well for:
Use text fields when:
Text fields work well for:
Consistent naming conventions for custom fields make them easier to understand and use. Good field names improve adoption and data quality.
Start with the category name, followed by a descriptor. For example:
Risk Level instead of RiskCustomer Segment instead of SegmentDevelopment Phase instead of PhaseApproval Status instead of StatusInclude the unit of measurement in the field name. For example:
Effort Points instead of PointsBudget Estimate ($) instead of BudgetImplementation Time (days) instead of TimeBusiness Value Score instead of ValueClearly indicate what information should be entered. For example:
External Reference ID instead of ReferenceImplementation Notes instead of NotesRequirements Source instead of SourceIf multiple teams use the same GitLab instance, consider adding team prefixes to avoid confusion:
DEV: Sprint PriorityQA: Test EnvironmentUX: Design StatusPM: Market SegmentThis approach helps teams quickly identify which fields are relevant to their work.