Skip to content

issue tracking

Jump to bottom
Jörn Guy Süß edited this page Feb 16, 2026 · 1 revision

GitHub gives you several orthogonal mechanisms to organise “tickets” (Issues and PRs). Since you explicitly mentioned state, labels, and custom fields, I’ll structure this around those, and add the adjacent concepts that usually matter when designing a coherent workflow.

1. Ticket state (Issue lifecycle)

Open / Closed (core state)

At the most fundamental level, every GitHub Issue has a binary state:

  • Open
  • Closed

This state is universal, searchable, and drives many automations (notifications, metrics, etc.). There is no built‑in multi‑state workflow at the Issue level beyond this. [github.blog]

Implication:
If you want richer lifecycle states (e.g. Backlog → In Progress → Review → Done), you must model them using Projects, labels, or issue types, not the open/closed flag alone.

2. Issue Types (structured classification)

GitHub now supports Issue Types (generally available since 2025), such as:

  • Bug
  • Feature
  • Task
  • Custom types (org/repo configurable)

Issue types provide a first‑class, structured classification of work, distinct from labels. They integrate with Projects and search (e.g. type:Bug). [github.blog]

When to use

  • To distinguish what kind of work an issue represents
  • As a stable taxonomy across repositories

When not to

  • For workflow state (that’s better handled via Projects)

3. Labels (lightweight, repository‑local metadata)

Labels are the oldest and most flexible organisational mechanism:

  • Free‑form, colour‑coded tags
  • Repository‑scoped
  • Can represent status, priority, domain, team, risk, etc.

Examples:

  • status:blocked
  • priority:high
  • area:fhir
  • tech:terraform

Labels are fully searchable and appear directly on issues and PRs. Changes are recorded in the issue timeline. [bing.com]

Strengths

  • Very flexible
  • Easy to automate (GitHub Actions)
  • Visible everywhere

Limitations

  • No enforced schema
  • No ordering or single‑select constraint
  • Can become messy without conventions

Rule of thumb

Use labels for cross‑cutting concerns and facets, not as your primary workflow engine.

4. GitHub Projects (the real workflow engine)

Modern GitHub Projects (v2) is where structured ticket organisation really happens.

A Project can include:

  • Issues
  • Pull Requests
  • Draft items

Projects support multiple views (table, board, roadmap) and are backed by fields. [docs.github.com]

5. Custom Fields (project‑level, strongly typed)

Custom fields exist at the Project level, not the Issue itself.

Supported field types include:

  • Text
  • Number
  • Date
  • Single‑select (dropdown with enforced options)
  • Iteration (sprints)
  • Issue Type (built‑in)
  • Parent / sub‑issue progress

[docs.github.com]

Typical uses

  • Status (Backlog / In Progress / Review / Done)
  • Priority (P0–P3)
  • Sprint / Iteration
  • Risk level
  • OKR linkage

Important architectural detail

Custom field values are not first‑class Issue fields. They live on the Project item.

As a result:

  • Changes to custom fields do not automatically appear in the Issue timeline [devactivity.com]
  • They are not visible unless the issue is viewed in a Project context

This is a deliberate design choice and often surprises teams coming from Jira/Azure DevOps.

6. Status modelling: your main design choice

GitHub does not enforce a single way to model “status”. Common patterns are:

A. Project single‑select field (recommended)

  • Field: Status
  • Values: Backlog, In Progress, Review, Done

✅ Strongly typed
✅ Board and table views
❌ Project‑scoped only

B. Labels as status

  • status:in-progress, status:blocked, etc.

✅ Visible everywhere
✅ Timeline tracking
❌ No enforcement (multiple statuses possible)

C. Hybrid (very common)

  • Project field for primary workflow
  • Labels for exceptions and signals (blocked, needs‑info)

7. Sub‑issues and hierarchy

GitHub now supports sub‑issues:

  • Parent issue represents a feature/epic
  • Child issues represent tasks

Progress can be visualised via built‑in progress fields in Projects. [github.blog]

This reduces the need for external epic tooling.

8. What GitHub deliberately does not offer

It’s useful to be explicit about the boundaries:

  • ❌ No mandatory workflow transitions
  • ❌ No per‑issue custom fields outside Projects
  • ❌ No validation rules across fields
  • ❌ No native history tracking for project field changes [devactivity.com]

These gaps are often filled with:

  • GitHub Actions
  • Webhooks + API
  • Conventions rather than enforcement

9. Practical mapping (summary table)

Need Best GitHub Mechanism
Open vs done Issue open/closed
Work classification Issue Types
Priority / domain tags Labels
Workflow state Project single‑select field
Sprint planning Iteration field
Structured planning data Custom Project fields
Epic → task Parent / sub‑issues

If you want, next we can:

  • Map a Jira‑style workflow onto GitHub with minimal friction
  • Design a label + project field convention that stays sane at scale
  • Compare GitHub Projects vs Azure DevOps Boards for your use case

Just tell me which angle you want to go deeper on.

🦶🦶🦶🦶 This footer is almost everywhere 🦶🦶🦶🦶

Clone this wiki locally