Custom fields

Custom fields add your own information to issues - a severity, the customer affected, a launch date, who reviews the change. Each project has its own fields. They appear on the issue page, in the issue list, in search and in the CSV export, and an AI agent reads and sets them through the MCP tools.

Adding a field

A Project Admin (or an organisation admin) adds fields in Project settings → Fields. A field has:

• A name, such as Severity. You can rename it at any time.

• A type, which never changes once the field exists:

  Type	Holds	Example
  Text	One line, up to 1,000 characters	ACME-order-4471
  Markdown	Formatted text, up to 16 KB	Steps to reproduce
  Number	A number, optionally within a range and with a set number of decimal places. Approximate: not for money or exact totals	12.5
  Integer	A whole number, optionally within a range	3
  Date	A calendar date, the same for everyone whatever their timezone	1 Oct 2026
  Date and time	A moment, shown in each reader’s timezone	1 Oct 2026, 9:30am
  Checkbox	Yes or no	Blocking
  Select	One option from a list	High
  Multi-select	Several options from a list	Web, iOS
  User	One member of the project	@alex
  Multi-user	Several members	@alex, @casey
  URL	A web address	https://example.com/spec
  Duration	Time, in the 1w 1d 1h 1m form	1h 30m

  Number fields are stored as ordinary decimal-fraction approximations, so very long decimals can differ in the last place and totals may be off by a tiny amount. Use an Integer field in whole units (cents, not dollars) or a Duration for anything that must be exact.

• A slug - the name search uses, such as severity. It is made from the name unless you choose one: lower-case letters, digits and hyphens. The slug never changes, even when you rename the field, so saved searches and history keep working. It cannot be the name of a built-in search attribute such as status or due date.

• The issue types it applies to. A Severity field can apply to Bugs only, so it does not clutter an Epic. By default a field applies to every type.

• Options, for a select or multi-select, each with a colour. Drag them into the order you want; the order is also how they sort.

• Required, a default and an empty label - see below.

A project can have up to 50 active fields. Archived fields do not count.

The Fields tab lists the fields in the order issues show them, with each one’s slug, type, the types it applies to and how many issues hold a value, and counts the active ones against the 50; at the limit, New field is disabled until you archive or delete one. Drag a field’s grip, or press Alt + ↑/↓ on it, to reorder. Click a field’s name to change it: the same dialog as New field, with the type and slug shown but fixed, and Archive and Delete at the bottom. Archived fields are listed apart, under the active ones. Everyone in the project can see the tab; only a Project Admin can change it.

The same slug in several projects

Two projects can each have a field with the same slug - say, a Severity select in both - and a search across projects then finds issues in both: severity: High. A slug always holds the same kind of value across the organisation, though, so a Severity number in a third project is refused; choose another slug for it.

Filling in fields

Fields appear in the issue’s sidebar under Fields, below the standard ones, in your chosen order, with a picker to match the type: a calendar for a date, a calendar and a time for a date and time, a searchable list for options and people, a switch for a checkbox, and the 1w 1d 1h 1m box for a duration, as for Estimation. A markdown field shows its text, and the pencil beside its name opens the editor. Multi-select and multi-user fields save when their picker closes, so choosing three options is one change. Anyone who can edit the issue (Contributor and up) can set them. People fields offer the members who can open the issue.

If a change is refused - a required field cleared, a number outside its range - the reason shows under the field and it keeps its value.

When you create an issue, the fields that apply to its type follow the standard ones, with their defaults already filled in. A required field carries a red *, and creating without it says which fields are missing. Changing the type changes the set.

Every change is recorded in the issue’s history, as Severity: High → Critical, and corrections made within a few minutes collapse into one entry, as for any other field.

Empty values, required fields and defaults

An empty field shows its empty label - No Severity unless you set another, such as Not triaged. In the issue list an empty cell shows --.

A default is filled in on every new issue that does not set the field. A required field must have a value when an issue is created, and cannot be cleared afterwards. If it has a default, the default counts. Issues that existed before the field became required keep their empty value until someone clears the field or a type change makes it apply. A checkbox is never empty - unticked is No - so it cannot be required.

Changing an issue’s type

When an issue changes to a type a field does not apply to, the field disappears from the issue, but its value is kept. Change the type back and the value returns. A field that is required for the new type must be filled in (or takes its default) as part of the change.

Searching

Search by the slug, with values that match the field’s type:

severity: High, Critical
severity: -Low
platforms: iOS
reviewer: me
launch: 2026-10-01 .. 2026-10-31
deploy-at: {This week}
budget: 100 .. 500
budget: {-5}
review-time: 1h ..
blocking: Yes
summary-line: order-4471

• Options match by name, and take part in the # shortcut: #High finds issues whose priority, status, type, tag, sprint or a select field is High.
• Text, markdown and URL fields match any part of the text.
• Numbers compare exactly or in a range. A leading - excludes a value, so a negative number goes in braces: budget: {-5}.
• Checkboxes take Yes or No.
• Empty is the field’s empty label, in braces when it has spaces: severity: {No Severity}; has: severity and has: -severity also work.
• A value that names nothing - severity: Huge - is an error that lists the valid options.

Sort by any field except text, markdown and URL fields: sort by: severity desc, launch. Selects sort in their option order, people by username.

The issue list can group by a select, multi-select, user, multi-user or checkbox field, with counts that follow the search. Its Columns menu lists the project’s fields under Custom fields (across projects, the fields of the issues on screen); a saved view keeps the columns chosen with it, and clicking a sortable field’s header sorts by it. When there are more columns than fit, the list scrolls sideways.

Changing and removing fields

• Renaming an option changes it on every issue at once.
• Archiving an option keeps it on the issues that have it, but it can no longer be chosen.
• Deleting an option that some issues use asks where to move them - another option - and records the change in each issue’s history. To keep those values instead, archive the option.
• Archiving a field hides it from issues and pickers and stops changes to it, but keeps every value, and you can still search by it. Unarchive it to bring it back.
• Deleting a field asks for confirmation, naming how many issues hold a value, and permanently removes every value it holds. The entries it left in issue histories stay.

Adding, changing and deleting fields and options is recorded in the organisation’s audit log.

Time tracking: Estimation, Spent time and work item attributes

In Project settings → Time tracking:

• Estimation field. By default the built-in Estimation. Choose a duration field instead and that field becomes the estimate: setting the estimate fills it, the issue’s estimate-against-spent comparison and the sprint’s remaining work read it, and so does estimation: in search, and the sidebar’s Estimation row takes its name. Switching back restores the built-in estimates.
• Spent time field. By default the built-in Spent time. Choose a duration field and it shows the time logged on the issue and its subtasks; it cannot be edited by hand.
• Work item attributes. Work type is built in and cannot be removed. Add your own - Billable with Yes and No, say - each with its values and a one-letter badge. Select an attribute in the table to change its values beside it. When someone logs time, they pick a value for each beside Type, and the Spent time tab shows each value’s letter next to the work type’s. Deleting a value that time entries use asks where to move them; deleting an attribute removes it from every entry. Work item attributes are not searched.

A field chosen as the Estimation or Spent time cannot be archived; deleting it returns the project to the built-in.

Exporting

The CSV export can include any custom field as a column, alongside the standard ones. Options and people are written by name, several separated by commas, durations as 1d 4h and checkboxes as true or false.

For API and agent users

Values are set with custom_fields on creating or updating an issue, keyed by slug or field name: {"Severity": "High", "Platforms": ["Web", "iOS"], "Reviewer": "@alex"}; null clears one. An agent uses list_custom_fields, create_custom_field, update_custom_field, delete_custom_field and set_field_values, or passes custom_fields to create_issue, update_issue and bulk_update_issues. Every argument is named, never an internal number - see the tool reference.