Labels let you tag issues with flexible metadata. Categories group related labels together for cleaner organization.
Labels are simple name-color tags that you attach to issues. Each label can optionally belong to a category and have a sort order within that category.
| Property | Description |
|---|---|
| Name | Display name (unique within category, 1-50 chars) |
| Color | Hex color for visual distinction (e.g., #ff4444) |
| Category | Optional grouping (e.g., "priority", "area", "state") |
| Sort Order | Display order within the category (lower = first) |
Categories group related labels. For example:
Labels without a category appear in an "Uncategorized" group. You can filter labels by category using the ?category= query parameter on the API.
Labels are managed per-organization (or per-user in personal mode):
A common pattern is creating a "state" category for operational labels that track where an issue is in your development process:
Category: state
- needs-design
- needs-review
- needs-testing
- ready-to-deploy
- blocked-externalThese complement the built-in status field and let you add richer workflow context without custom statuses.