[[_TOC_]] # Goals According to @vshushlin https://gitlab.com/gitlab-org/gitlab/-/work_items/631130#note_3944248731: * We want to validate the REST API design and use `glab` and `gitlab-triage` as test benches for it. * We also want to accelerate the REST API adoption after GA. `glab` is already used by lots of people, so converting it to REST would give us lots of users right away. # Vlad's thoughts https://gitlab.com/gitlab-org/gitlab/-/work_items/631130#note_3944248731 # Timeline | Stage | Command | API | Visibility | Notes | |-------|---------|-----|------------|-------| | 1\. Existing | `glab work-items` | GraphQL | Visible | | | 2\. Development (October 5, 2026) | `glab work-items-experimental` | REST, needs the `work_item_rest_api` flag | Hidden | | | 3\. REST API reaches GA | `glab work-items` | REST | Visible | Replace existing `work-items` with the functionality of `work-items-experimental`. | | 4\. Compatibility | `glab work-items-legacy` | GraphQL | Hidden | | | 5\. Removal | legacy command removed | | | | # Widget coverage by REST API, as of October 5 There are **33 widgets**, with the following coverage: | Widget | Read | Create | Update | Notes | |--------|------|--------|--------|-------| | description, assignees, labels, milestone, start and due date, hierarchy (parent) | :white_check_mark: | :white_check_mark: | :white_check_mark: | Children come from the `/children` endpoints. | | Premium and Ultimate: color, health status, iteration, weight, status, custom fields | :white_check_mark: | :white_check_mark: | :white_check_mark: | | | progress, verification status | :white_check_mark: | – | :white_check_mark: | | | time tracking | :white_check_mark: | – | :white_check_mark: | | | award emoji | :white_check_mark: counts only | – | :white_check_mark: add, remove, toggle | Full list from the `/award_emoji` endpoint. | | notifications | :white_check_mark: | – | :white_check_mark: | | | linked items | :white_check_mark: | :white_check_mark: | **:x:** | **Can't change links after creation.** | | development | :white_check_mark: counts | – | – | Lists come from the closing MRs, related MRs and related branches endpoints. | | designs, error tracking, legacy requirement | :white_check_mark: | – | – | Read-only. | | current user to-dos | via endpoint | – | :white_check_mark: | | | notes | via notes and discussions endpoints | – | :white_check_mark: lock and unlock only | **Can lock discussion but can't read whether it's locked.** | | email participants, linked resources | via endpoint | – | – | Read-only. | | CRM contacts | **:x:** | :white_check_mark: | :white_check_mark: | **Can set contacts but can't read them back.** | | participants, vulnerabilities, test reports, decision log, agent plan, AI session | **:x:** | – | – | Not in the REST API at all. | # Suggested Epic Children ### Stage 2: `work-items-experimental` #### Iteration 0: Decisions and spikes | \# | Item | Type | Output | Status | |----|------|------|--------|--------| | 0.1 | client-go: separate REST methods | Agreement | REST gets new methods, and the existing GraphQL ones stay unchanged. Otherwise the GraphQL `work-items` command silently moves to REST when glab updates client-go. Also agree how releases will be timed. | Done. We'll be using `work-items-experimental`. See the Timeline. | | 0.2 | **Command and output design** | Decision | The JSON format, which becomes the `work-items` format at GA. Command names and singular versus plural nouns, matched to `glab mr` and `glab issue`. Actions as commands or as `update` flags. Named flags for common widgets plus a general `--features-json` input for full coverage. | Waiting for feedback | | 0.3 | **Spike: widget and feature coverage table** (2 days) | Spike | One row per GraphQL `work-items` option and per widget, with columns for REST read, create and update, the glab command or flag, and the item that delivers it. Tracks progress, and is the parity check before the GA swap. | No action required. This epic should aim for parity with the REST API, not the GraphQL API. | | 0.4 | **Backend issue: list ignores the feature flag** | Issue in gitlab-org/gitlab | The `work-items-experimental` command will work with the `list` endpoint even when the `work-item-rest-api` is off. This doesn't break anything. | No action required | #### Iteration 1: View one work item | \# | Item | Status | |----|------|--------| | 1.1 | `get <iid>` in a project. Creates the hidden parent command and shared helpers. Base fields, text and JSON output, one generic error message that mentions the flag. | | | 1.2 | Tester guide for the hidden command, linked from the dogfooding epic: how to get the flag enabled, which commands exist, where to report problems. | | | 1.3 | `get` for groups and work item URLs in all their forms. | | | 1.4 | `get --features`, covering all 22 readable widgets. Shows "not available for this type" when a widget is left out. | | | 1.5 | Specific error messages: not found, no permission, flag off. | | #### Iteration 2: List | \# | Item | |----|------| | 2.1 | Basic `list`: state filter, default sort, page size, pagination that follows the next link without trusting short pages or expecting a total. | | 2.2 | Filters, round 1: the most used, from 0.3. | | 2.3 | Filters, round 2: the rest, including `not` and `or` filters. | | 2.4 | Premium and Ultimate filters: iteration, weight, health status, status, custom fields, verification. | | 2.5 | Sorting. | | 2.6 | Group options: ancestors, descendants, archived projects. | | 2.7 | `list --features`. | #### Iteration 3: Create, update, delete | \# | Item | |----|------| | 3.1 | `create` with title and type. | | 3.2 | `create` with common widgets: description, assignees, labels, milestone, parent, dates. | | 3.3 | `create` with links and CRM contacts. | | 3.4 | `update` title, state and confidentiality. | | 3.5 | `update` add or remove labels, set assignees. | | 3.6 | `update` clearing fields: milestone, parent, iteration, weight. Needs client-go to tell "leave unchanged" from "clear". The riskiest slice in this iteration. | | 3.7 | Premium and Ultimate widgets in create and update: color, health status, iteration, weight, status, progress, verification status. | | 3.8 | Custom fields in create and update. | | 3.9 | `delete`, with confirmation. | | 3.10 | General `--features-json` input for create and update, covering anything without a named flag. | #### Iteration 4: Comments | \# | Item | |----|------| | 4.1 | `note list`, showing threads like `glab mr note list`, using the discussions endpoint and its cursor. Option for comments only. | | 4.2 | `note get <iid> <note-id>`: on your branch. | | 4.3 | `note create`, from `-m` or standard input, with internal notes. | | 4.4 | `discussion get <iid> <discussion-id>`: one thread. | | 4.5 | `lock` and `unlock` discussion. | #### Iteration 5: Relationships | \# | Item | |----|------| | 5.1 | `child list`, with `--features`. | | 5.2 | `child add` and `child remove`, converting IIDs and references to global IDs. | | 5.3 | `child move`. | | 5.4 | `link list`, filtered by link type, with `--features`. | #### Iteration 6: Development | \# | Item | |----|------| | 6.1 | `mr list <iid>`: merge requests that close the item, and related ones. Covers two endpoints. | | 6.2 | `branch list <iid>`. Explains that group-level items have none. | #### Iteration 7: Activity | \# | Item | |----|------| | 7.1 | `emoji list`, `emoji add`, `emoji remove`. | | 7.2 | `todo list`, `todo add`, `todo done`, consistent with `glab todo`. | | 7.3 | `subscribe` and `unsubscribe`. | #### Iteration 8: Time tracking | \# | Item | |----|------| | 8.1 | `time estimate <iid> <duration>`. | | 8.2 | `time log <iid> <duration>`, with summary and date. | #### Iteration 9: Service Desk and incidents | \# | Item | |----|------| | 9.1 | `participant list <iid>`: email participants. Explains when the type doesn't support it. | | 9.2 | `resource list <iid>`: linked resources, which today means Zoom links. | #### Throughout Stage 2 | \# | Item | |----|------| | 10.1 | **Server-side gaps:** file each one in gitlab-org/gitlab, and update glab when it's fixed. | | 10.2 | **Track new endpoints**, starting with [gitlab-org/gitlab!258518](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/258518), which adds "get one note in a thread". | Once iteration 1 has set up the shared pieces, iterations 4 to 9 don't depend on each other and can run in parallel. ### Stage 3: REST API reaches GA | \# | Item | |----|------| | 11.1 | Check feature parity using the table from 0.3. Swap only when it passes. | | 11.2 | Swap: `work-items-experimental` becomes `work-items`, and the GraphQL command becomes hidden `work-items-legacy`. One MR. | | 11.3 | Keep `work-items-experimental` as a hidden alias for a release or two. | | 11.4 | Release notes, announcement and feedback issue. Explain the JSON change and point to `work-items-legacy`. Keep the feedback issue open at least 14 days. | ### Stages 4 and 5: Legacy command and removal | \# | Item | |----|------| | 12.1 | Deprecation notice for `work-items-legacy`, naming the release that removes it. | | 13.1 | Remove `work-items-legacy`, the GraphQL code and the alias. | | 13.2 | client-go: deprecate the GraphQL work item methods, if nothing else uses them. | ### Server-side gaps to file (item 10.1) **Missing actions** * Links can't be added or removed after a work item is created. * Notes can't be edited or deleted, and threads can't be replied to or resolved. * Emoji reactions only work on the work item, not on its comments. * Email participants and linked resources are read-only. **Data you can write but not read back** * CRM contacts. * Whether discussion is locked. **Not exposed at all** * Participants, vulnerabilities, test reports, decision log. Agent plan and AI session too, though that may be intentional, so ask. * **Work item types:** there's no endpoint, so glab can't list the types, including custom ones, or which widgets each supports.