March 19, 2026

GitLab Work Items Explained: The Biggest Data Model Change in Years

GitLab is replacing Issues. Not deprecating them overnight, not adding a warning banner - quietly migrating every Issue, Epic, Task, OKR, and Test Case into a unified object type called Work Items.

If you build on the GitLab API, this affects you. If you use GitLab daily, this changes how your data is structured under the hood. Here’s what’s happening, why it matters, and what it means for tools like 99issues.

What’s actually changing

Today, GitLab treats Issues, Epics, Tasks, OKRs, and Test Cases as separate entities. Separate database tables. Separate API endpoints. Separate UI patterns. An Issue has fields that an Epic doesn’t, and vice versa.

Work Items collapse all of these into one base object type. The distinction between an Issue and an Epic is no longer structural - it’s defined by which widgets are attached.

Think of it like this: every Work Item shares the same foundation. What makes an Issue different from an Epic is the set of widgets snapped onto it - Labels, Dates, Health Status, Progress, Hierarchy, Weight, and more.

Work Item (base)
  + Labels widget       → categorize
  + Dates widget        → schedule
  + Health widget       → track status
  + Progress widget     → % complete
  + Hierarchy widget    → parent/child relationships
  + Weight widget       → estimation

An Issue might have Labels, Dates, and Weight. An Epic gets Labels, Dates, Health, and a Hierarchy widget for child items. Same base, different configuration.

Why this matters

This isn’t a cosmetic change. It’s a fundamental shift in how GitLab models work.

Flexible by default. Today, if you want a new work tracking type, GitLab has to build it from scratch - new tables, new API, new UI. With Work Items, it’s just a new combination of existing widgets. This means GitLab can ship new work types faster and with less complexity.

Unified API. Instead of hitting /issues, /epics, and /tasks separately, everything goes through the Work Items API. One query pattern for all types. One set of filtering rules. One pagination model.

Hierarchy without hacks. Parent-child relationships between Epics and Issues have always been somewhat bolted on. Work Items make hierarchy a first-class widget - any work item type can be a parent or child of any other, without special-case code.

You can already see this in production. Navigate to any GitLab project and look at the sidebar: Work Items is now a top-level nav entry under Plan. Open any Issue and check the breadcrumb - it reads Work Items / #12345. The migration is already underway.

What breaks

Every tool built on the old Issues API will need to adapt. The legacy /issues endpoint still works today, but the underlying data model is shifting. Tools that hardcode object types, assume separate API paths for epics vs. issues, or don’t understand widgets will eventually hit problems.

Here’s the split:

Legacy approach: - Built on the /issues endpoint - Separate epics API - Hardcoded object types - No widget awareness

Work Items native: - Unified work_items API - Widget-based data model - Type-agnostic queries - Future-proof by design

The GraphQL API already exposes Work Items with their widget structure. If you’re building something new against GitLab, this is the API to target.

How 99issues handles this

We’re building 99issues on the Work Items architecture from day one.

Not wrapping the legacy Issues endpoint. Not patching around the old Epics API. 99issues queries Work Items directly, understands the widget model, and renders each work item type based on its actual widget configuration - not a hardcoded template.

This means when GitLab ships a new work item type or adds a new widget, 99issues doesn’t need an update to display it correctly. The data model is already flexible enough to handle it.

It also means the hierarchy between Epics and Issues (and whatever comes next) works natively. No special cases, no separate code paths, no API gymnastics.

What to watch

GitLab is rolling this out incrementally. A few things to keep an eye on:

The /issues endpoint isn’t going away tomorrow. But new features will land on Work Items first. If you’re starting a new integration, build against Work Items.
Epics are already Work Items. On GitLab.com, Epics have been migrated. They show up in the Work Items list, have the widget sidebar, and respond to the Work Items API.
The widget list will grow. Expect new widgets for things like time tracking, custom fields, and approvals. The architecture is designed for extensibility.

The Work Items transition is GitLab’s biggest infrastructure bet in years. Whether you’re building tools, managing projects, or just triaging issues on your phone - this is the foundation everything will run on.

99issues is ready for it.