Issues and work items

The "planning" side of GitLab — issues, work items, epics, tasks, OKRs, and the upcoming work-item type framework that consolidates all of them.

The two-track model

GitLab has historically had separate models for Issue, Epic, Task, etc. The new "work items" framework unifies them into a single polymorphic type:

• Legacy types still in active use: Issue, Epic (EE), test cases, requirements (EE).
• Work item types define the schema of each kind — base widgets like assignees, labels, milestone, dates, hierarchy, weight, health status, time tracking. Types are registered in lib/gitlab/work_items/widgets/.
• The migration is incremental — pages and APIs flip to the work-item path as each feature catches up.

Source

app/models/
├── issue.rb
├── work_item.rb (subclass of Issue currently)
├── work_items/                         # types, widgets, dates source, hierarchy
└── ...
app/services/
├── issues/                              # issue CRUD
├── work_items/                          # work-item CRUD + widget logic
├── notes/                               # comments
├── discussions/, draft_notes/
├── todo_service.rb
└── milestones/
app/workers/issuable/, work_items/
app/graphql/types/{issue,work_item,note,discussion}_type.rb
app/graphql/mutations/issues/, work_items/, notes/
ee/app/models/epic.rb                    # legacy EE epics
ee/app/services/epics/                   # being merged into work_items

Frontend: app/assets/javascripts/work_items/, app/assets/javascripts/issues/, boards/, notes/, epics/ (EE), requirements/ (EE).

Widgets

A work item's behavior is composed of widgets:

• Assignees
• Labels
• Description
• Hierarchy (parent / children)
• StartAndDueDate
• Milestone
• Iteration (EE)
• Weight (EE)
• HealthStatus (EE)
• Status (EE)
• LinkedItems
• Notifications
• Notes
• TimeTracking
• Awardable (emoji reactions)
• RolledUpDates
• LinkedResources
• many more

Each widget lives under lib/gitlab/work_items/widgets/. Widgets register their schema, mutation, and presenter pieces.

Notes (comments) and discussions

Notes are polymorphic (issue, MR, commit, snippet, etc.). The hierarchy:

• Note — single comment.
• Discussion — a sequence of notes; the first is the "root note".
• DraftNote — pending review note (MR review mode).

Service objects under app/services/notes/ and app/services/discussions/ handle creation, mention parsing (via Banzai), notification fanout, and resolved/unresolved state.

Mentions and todos

When a user is @-mentioned, app/services/todo_service.rb creates a Todo row. Todos appear in the user's todo list and drive notification emails.

Boards

app/models/board.rb, app/models/list.rb, app/services/boards/. Drag-and-drop boards over issues, with EE adding scoped/iteration boards.

Epics (EE → work items)

EE has standalone Epic plus epic boards. The work-items refactor folds epics into WorkItem with a hierarchy widget — the migration is incremental and feature-flagged.

Requirements and test cases (EE)

ee/app/models/work_items/, ee/app/services/requirements_management/. Requirements are work items with extra widgets for traceability.

OKRs

OKRs use the "objective" and "key result" work-item types defined in EE.

API

• REST: lib/api/issues.rb, lib/api/notes.rb, lib/api/work_items.rb.
• GraphQL: app/graphql/types/work_items/, app/graphql/mutations/work_items/. Widget mutations are first-class.

Related

• Source code management — MRs share the issuable framework.
• Banzai — Markdown rendering of descriptions / comments.
• Notifications — fanout from issue events.