> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit-dev.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Issue types

> Shape each project's work with types, permissions, and hierarchy rules

Issue types define what kind of work an [issue](/concepts/issues) represents. Each project has its own catalog, and every type can have a distinct name, icon, color, description, workflow, hierarchy rules, templates, and fields.

## Starter catalog

Orbit supplies 16 system types as a starting point:

| Type           | Intended use                                    |
| -------------- | ----------------------------------------------- |
| Task           | A unit of work to complete                      |
| Feature        | A new capability or request                     |
| Story          | User-facing functionality                       |
| Bug            | Something that is not working as expected       |
| Epic           | A large body of work made up of smaller issues  |
| Spike          | A time-boxed investigation                      |
| Chore          | Maintenance without direct user impact          |
| Improvement    | An enhancement to something that already exists |
| Incident       | An active production problem                    |
| Security       | A security concern or vulnerability             |
| Infrastructure | Infrastructure or tooling work                  |
| Research       | Open-ended exploration or analysis              |
| Experiment     | A trial used to validate a hypothesis           |
| Documentation  | Documentation work                              |
| Design         | Visual, layout, or interaction design work      |
| AI Task        | Work intended for an AI agent                   |

System types are project-specific. Editing one changes it only in the selected project.

## Top-level and sub-issue types

An issue type can be available for top-level issues, sub-issues, or both.

* **Task**, **Feature**, **Story**, **Bug**, and **Epic** are top-level types by default.
* The remaining starter types are sub-issue-only by default.
* Types that allow children can be limited to specific child types.

The quick-add row for top-level issues only offers types configured for top-level use. When adding a sub-issue, Orbit also checks the parent type's hierarchy rules.

## Configure hierarchy

Turn on **Allows sub-issues** in a type's general settings before configuring its hierarchy. Then open the hierarchy action for that type and choose which other types it accepts as children.

If you leave every child type unselected, the parent accepts any issue type. Selecting one or more types limits the picker to those choices. An issue cannot be its own parent, use a parent from another project, or be moved beneath one of its own descendants.

Create a child from the **Sub-issues** section on a parent issue. Enter a title, choose one of the allowed types, and press Enter. The child appears in the panel and uses the selected type's starting status, default template, and Medium priority.

On a child issue, the page header shows its ancestor path so you can navigate back up the hierarchy. List renders available parents and children as an indented tree; use the chevron beside a parent to collapse or expand its visible descendants.

<Note>
  List builds its tree from the current page of results. If a parent is on another paginated page, its child appears as a top-level row on the page you are viewing.
</Note>

## Restrict who can create a type

Owners and Admins can limit a type to selected built-in roles: Owner, Admin, Member, or Viewer. If no roles are selected, anyone who already has permission to create issues can use the type.

These restrictions add to the normal **Create issues** permission; they do not replace it.

## Manage issue types

Open **Settings → Workspace → Issue types**, then select a project. From the catalog you can:

* create a custom type with a name, icon, color, and optional description;
* choose whether it supports children or can be used at the top level;
* select built-in roles that may create it;
* edit custom and system types when you have the relevant permission;
* configure its [workflow](/guides/workflows), hierarchy, templates, and fields.

Owners and Admins can normally create, edit, and delete issue types. Custom roles can receive the view, create, edit, and delete permissions independently.

## Require built-in fields

In a type's general settings, you can require **Description**, **Assignee**, **Labels**, **Start date**, **End date**, or **Priority**. Orbit checks those values when an issue of that type is created. If someone later edits a required field, they cannot clear it.

<Warning>
  The current **New issue** and **Add sub-issue** rows collect only a title and type, while always supplying Medium priority. A required description or labels can be satisfied by the automatically applied template, but required assignee or date values cannot be entered in these rows.
</Warning>

## Add custom fields

Use a type's fields action to add information beyond the built-in issue properties. Custom fields appear in the issue sidebar and can use these formats:

| Field type | Use it for                       |
| ---------- | -------------------------------- |
| Short text | A short free-form value          |
| Long text  | Notes or longer answers          |
| Number     | A numeric value                  |
| Date       | A calendar date                  |
| Choice     | One value from a configured list |
| Checkbox   | A yes-or-no value                |
| Link       | A URL                            |

Give each field a unique label within the type. For a Choice field, enter the available options as a comma-separated list. You can also add a hint that appears while a non-checkbox field is empty and mark a field as required.

<Warning>
  A required custom field must be provided when the issue is created, but the current inline creation rows do not expose custom fields. Keep custom fields optional if people need to create that type from Orbit's current UI.
</Warning>

## Create templates

Templates give new issues of a type a reusable starting description and labels. A template can also store a default priority. Open the type's templates action to create, edit, or delete templates.

Orbit lists templates by name and marks the first one **Applied by default**. When a new issue does not specify another template, that first template supplies any description or labels not already provided. References to labels that no longer exist in the project are ignored.

The current quick-add rows always submit Medium priority, so a stored template priority does not replace it. Change the priority from the issue page after creation when needed.

Template descriptions support markdown and the same [image uploads](/guides/rich-text-editing#images-in-comments-and-templates) as issue descriptions.

## Deleting a type

System types can be edited but cannot be deleted. A custom type can be deleted only when no issues use it, so reassign its issues to another type first.

<Warning>
  Deleting a custom issue type cannot be undone. Check its workflow, templates, fields, hierarchy rules, imports, and automations before removing it.
</Warning>