feat(work-items): add glab work-items get using the work items REST API

Description

Adds glab work-items get, which shows one work item using the work items REST API:

glab work-items get <iid> [-R <project>] [-F json] [--web]
  • Shows a work item in a project: title, type, state, author, labels, assignees, milestone, start and due dates, parent, comment count and description.
  • -F json prints the work item as JSON, as the REST API returns it.
  • --web opens the work item in a browser.

Choosing the API

GLAB_WORK_ITEMS_API_MODE glab work-items get
unset or graphql (default) Error explaining that the command uses the REST API and how to enable it, before any request
rest Work items REST API, through client.WorkItemsREST.GetWorkItem. Requires the work_item_rest_api feature flag.
anything else Error naming the valid values, before any request

The setting is the new work_items_api_mode config key, so glab config set work_items_api_mode rest works too. It is listed in the configuration and environment variable docs. The default stays graphql, so the other work-items commands can adopt the setting later without changing their current behaviour.

get adds no GraphQL functionality, and the existing work-items commands are unchanged.

This is item 1.1 in the epic gitlab-org#23916. Design decisions are in #8582.

Notes for reviewers

  • client-go: uses WorkItemsRESTService from gitlab-org/api/client-go!3078 (merged), released in client-go v3.22.0. main already uses that version, so this MR doesn't change go.mod.
  • No GraphQL fallback: an earlier version of this MR converted GraphQL results to the REST representation. Nested objects could only be partly filled, so JSON output showed zero values that looked like real data, such as allows_scoped_labels: false. It was removed in favour of a clear error in GraphQL mode.
  • get, not view: #8582 proposed view to match glab issue view, but CONTRIBUTING.md says get is the standard verb for showing one object, so this uses get.
  • Error details: the feature flag hint is part of the error message itself rather than cmdutils.WrapError details, because ExitError.Details isn't printed anywhere.
  • Out of scope (later items in the epic): groups, references and URLs; a --features flag; specific messages per error type; comments; using the API mode in the other work-items commands.

Resolves #8585

How has this been tested?

  • Unit tests with the client-go mocks, in REST mode: text output, missing values, JSON output (including that every field is requested), --repo, API errors, invalid and missing IIDs, and --web.
  • Unit tests for the API mode: the default GraphQL mode fails without an API call, GLAB_WORK_ITEMS_API_MODE=rest set as an environment variable, and an invalid value.
  • The lefthook pre-push checks pass, including golangci-lint against origin/main, check-generated, check-args and the docs checks.
  • Ran against a local GDK with work_item_rest_api enabled: REST mode sends one GET /api/v4/namespaces/:id/-/work_items/:iid.

Screenshots (if appropriate):

$ glab work-items get 44 -R gitlab-org/gitlab-test
ERROR
This command uses the work items REST API. Set GLAB_WORK_ITEMS_API_MODE=rest, or the work_items_api_mode configuration key, to use it. The REST API requires the work_item_rest_api feature flag.

$ GLAB_WORK_ITEMS_API_MODE=rest glab work-items get 44 -R gitlab-org/gitlab-test
title:	Debug me
type:	Task
state:	open
author:	root
labels:	-
assignees:	-
milestone:	-
start date:	-
due date:	-
parent:	-
comments:	1
--
hi

$ GLAB_WORK_ITEMS_API_MODE=soap glab work-items get 44 -R gitlab-org/gitlab-test
ERROR
Invalid work items API mode "soap" (GLAB_WORK_ITEMS_API_MODE or work_items_api_mode): must be "graphql" or "rest".
Edited by Phil Wong

Merge request reports

Loading
Loading