gitlab

Use the glab CLI for everything. The user's OAuth access token is exported as $GITLAB_TOKEN; glab reads it automatically (the token is also accepted via GITLAB_ACCESS_TOKEN and OAUTH_TOKEN for tooling compatibility). Default host is gitlab.com — for self-hosted set GITLAB_HOST or pass --hostname <host> per command.

glab --help and glab <subcommand> --help are always current.

Two ways to call glab — prefer subcommands

Style A: First-class subcommands — START HERE

glab issue, glab mr, glab repo, glab ci, glab job, glab pipeline, glab release, glab snippet, glab variable, glab label, glab milestone, glab schedule. These print formatted text by default and JSON via --output json.

Style B: Raw REST / GraphQL via glab api

glab api <path> for REST, glab api graphql -f query='…' for GraphQL. Notable flags:

• -X POST|PATCH|PUT|DELETE — override method (default GET, becomes POST when --field / --raw-field is set).
• -f key=value — magic-typed (literals true / false / null / integers become JSON types, leading @filename reads from a file).
• -F key=value — same as -f but always treats the value as a string.
• --paginate — auto-walk Link: rel="next".
• --hostname <host> — target a different GitLab host than default.
• Path placeholders: when run inside a git checkout, :fullpath / :branch / :user are auto-populated from the repo. From a generic shell, encode the path manually (see recipes).

Recipes

List open issues on a project

glab issue list --repo OWNER/PROJECT --opened --output json
glab issue list --repo OWNER/PROJECT --assignee=@me --output json

View an issue with comments

glab issue view 42 --repo OWNER/PROJECT --comments
glab issue view 42 --repo OWNER/PROJECT --output json

Create / comment / close an issue

glab issue create --repo OWNER/PROJECT --title "Bug: foo" --description "Repro steps…" --label bug
glab issue note 42 --repo OWNER/PROJECT --message "Acknowledged."
glab issue close 42 --repo OWNER/PROJECT

List MRs assigned to / authored by me

glab mr list --repo OWNER/PROJECT --assignee=@me --opened --output json
glab mr list --repo OWNER/PROJECT --author=@me --opened

View an MR with diff and CI pipeline

glab mr view 99 --repo OWNER/PROJECT
glab mr diff 99 --repo OWNER/PROJECT
glab ci view --repo OWNER/PROJECT --branch <BRANCH>

Approve / merge / leave a note on an MR

glab mr approve 99 --repo OWNER/PROJECT
glab mr note 99 --repo OWNER/PROJECT --message "Looks good — ready when CI is green."
glab mr merge 99 --repo OWNER/PROJECT --squash --remove-source-branch

Read a file from the default branch (raw bytes)

# URL-encode the project path AND the file path because both contain '/'.
PROJECT=$(printf '%s' 'OWNER/PROJECT' | jq -sRr @uri)
FILE=$(printf '%s' 'src/main.go' | jq -sRr @uri)
glab api "projects/${PROJECT}/repository/files/${FILE}/raw?ref=main"

List the latest pipelines on a branch

glab ci list --repo OWNER/PROJECT --status running,success,failed
glab ci view --repo OWNER/PROJECT --branch main
glab ci trace --repo OWNER/PROJECT <JOB_ID>     # stream a job log

Search across a group's issues

glab api "groups/GROUP_PATH_OR_ID/issues?state=opened&search=keyword" \
  --paginate \
  | jq '.[] | {iid, title, project: .references.full, web_url}'

GraphQL example: project metadata + open MR count

glab api graphql -f query='
  query($path: ID!) {
    project(fullPath: $path) {
      name webUrl
      mergeRequests(state: opened) { count }
    }
  }' -f path=OWNER/PROJECT

Notes

• --repo OWNER/PROJECT accepts OWNER/PROJECT, GROUP/SUBGROUP/PROJECT, full HTTPS URL, or git URL. The project path goes verbatim (no URL encoding) for --repo, but does need jq @uri encoding when used inside a glab api path.
• For self-hosted GitLab the user must have authorized the connection with the right host. A 404 on a project you know exists usually means the connection is pointing at gitlab.com when the project lives elsewhere — surface that hint to the user.
• Many glab commands have an --output flag that takes text (default) or json. glab issue list and glab mr list additionally have --output-format (details / ids / urls) which is a separate, list-only formatter. Pass the long flag --output json to avoid the short-flag confusion (-O vs -F).