GitLabgitlab-org

cli

main
ply5 git calls24 ms103 KiB3 cachedprotocol v2
442 lines19 KiBRaw

Contributing Guide

Developer Certificate of Origin + License

Contributions to this repository are subject to the Developer Certificate of Origin.

All Documentation content that resides under the docs/ directory of this repository is licensed under Creative Commons: CC BY-SA 4.0.

This notice should stay as the first item in the CONTRIBUTING.md file.


Thank you for your interest in contributing to the GitLab CLI! This guide details how to contribute to this extension in a way that is easy for everyone. These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this document in a merge request.

Please do:

  • Check existing issues to verify that the bug or feature request has not already been submitted.
  • Open an issue if things aren't working as expected.
  • Open an issue to propose a significant change.
  • Open an issue to propose a feature.
  • Open a merge request to fix a bug.
  • Open a merge request to fix documentation about a command.
  • Open a merge request for an issue and leave a comment claiming it.

Please avoid:

  • Opening merge requests for issues marked blocked.
  • Opening merge requests that only add or edit files in docs/source/. These files are auto-generated from Go source by make gen-docs and are overwritten on every release. Instead, update the documentation fields in the relevant cobra.Command definition. For guidance, see the CLI documentation style guide.

Code of Conduct

We want to create a welcoming environment for everyone who is interested in contributing. Visit our Code of Conduct page to learn more about our commitment to an open and welcoming environment.

Maintainership

GitLab team members who want to review or maintain the CLI can follow the reviewer and maintainer guide.

Getting Started

Reporting Issues

Create a new issue from the "Default" template and follow the instructions in the template.

Dependency management

Go and Node.js dependencies are managed automatically by Renovate, which opens merge requests as upstream releases become available. Updates are merged on our normal review cadence rather than immediately, to give us time to verify compatibility.

Every CI/CD pipeline also runs GitLab Advanced SAST, Dependency Scanning, and Secret Detection. Vulnerabilities in our direct dependencies surface automatically in the project's Vulnerability Report.

Reporting a vulnerability

If you believe you've found a security vulnerability in glab, follow the process in the security policy. Do not open a public issue.

If you're relaying output from a container-image scanner (Trivy, Grype, and similar), please first verify that the vulnerability is actually reachable from glab code. The Go team provides govulncheck, a separate tool that performs analysis of call-graph reachability:

shell
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...

Image scanners frequently flag module-level CVEs in transitive Go dependencies that the CLI never imports. For example sub-packages of golang.org/x/image or golang.org/x/net.

These findings are not actionable on their own, but a govulncheck report that shows a reachable symbol is.

Your First Code Contribution?

Read about the contribution process in development_process.md. This document explains how we review and release changes.

If your merge request is trivial (fixing typos, fixing a bug with 20 lines of code), create a merge request.

If your merge request is large, create an issue first. See Reporting Issues and Proposing Features. In the issue, the project maintainers can help you scope the work and make you more efficient.

Developing with Workspaces

GitLab Workspaces are fully enabled for the CLI project, providing a complete development environment in your browser.

Benefits of using Workspaces:

  • Zero setup: No requirement to install Go, dependencies, or clone the repository locally.
  • Pre-configured environment: All development tools and dependencies are ready to use.
  • Immediate development: Start coding, running tests, or making edits right away.
  • New contributor onboarding: A great way for new contributors to start without local machine setup.
  • MR-based development: Open a Workspace directly from a merge request for testing and reviews.
  • No context switching: Make changes during code reviews without switching to your local machine.

For more information see, Creating a workspace.

Building the project

Prerequisites:

Build with: make or go build -o bin/glab ./cmd/glab/main.go

Run the new binary as: ./bin/glab

Go version updates

glab follows the GitLab Go upgrade guide:

  • .tool-versions and GO_VERSION in .gitlab-ci.yml pin the exact toolchain. Patch upgrades, including security fixes, change only these two.
  • The go directive in go.mod is the minimum version for building from source, and always uses patch 0. Bump it only when moving the toolchain to a new minor version, usually from the glab issue in the Go upgrade epic.

scripts/check-go-version.sh enforces these rules in CI.

Git hooks with Lefthook (optional)

This project supports Lefthook for managing Git hooks. Lefthook helps catch issues before pushing to CI by running checks locally.

Quick setup
  1. Install development tools using mise:

    bash
    # Install mise if you don't have it
    curl https://mise.run | sh
    
    # Install all development tools (includes lefthook)
    make bootstrap
    
    # Enable git hooks
    lefthook install

    This installs all tools defined in .tool-versions: Go, golangci-lint (includes gofumpt and goimports formatters), shellcheck, markdownlint-cli2, vale, lychee, rumdl, Node.js, lefthook, and commitlint dependencies.

Available hooks
  • pre-commit: Formats and lints Go code (golangci-lint with gofumpt/goimports), lints shell scripts (shellcheck), auto-fixes Markdown formatting (markdownlint), checks and regenerates documentation if command files changed (blocks commit until docs are staged)
  • commit-msg: Validates commit messages follow conventional commits format
  • pre-push: Runs documentation validation (markdownlint, rumdl, vale, lychee) on changed files
Graceful degradation

If a required tool is not installed, the hook will display a warning and skip that check. This means you can install lefthook immediately and add tools incrementally. All validation also runs in CI, so nothing is missed.

Skipping hooks

If you need to skip hooks temporarily:

bash
# Skip all hooks for one commit
LEFTHOOK=0 git commit -m "message"

# Skip all hooks for one push
LEFTHOOK=0 git push

# Skip specific hook
LEFTHOOK_EXCLUDE=pre-push git push

Running tests

Run tests with: go test ./... or make test.

There are some integration tests that perform real API requests to https://gitlab.com. If the environment variables GITLAB_TEST_HOST and GITLAB_TOKEN_TEST are not set, the integration tests will fail in CI if being run in the gitlab-org/cli project. They will be skipped locally or in forks if either GITLAB_TEST_HOST or GITLAB_TOKEN_TEST is unset. Integration tests use the _Integration test suffix and use the _integration_test.go file suffix.

GITLAB_TEST_HOST is set to https://gitlab.com in CI.

GITLAB_TOKEN_TEST must be a personal access token and requires the api scope. To ensure the glab duo feature is functioning correctly, the token's user must have a GitLab Duo seat.

Proposing Features

Create a new issue from the "Feature Request" template and follow the instructions in the template.

Designing a new feature

The Design Command-Line Tools People Love presentation by Carolyn Van Slyck provides some great guidance on things to consider when implementing a CLI tool. We recommend the entire presentation, but the following points are especially important in the context of the GitLab CLI.

Grammar

GitLab CLI commands use a noun-first, verb-second grammatical structure, like glab ci list. Also, these verbs are shared by various commands, and have expected behavior as a result:

  • create - Used when creating a singular object. For example, glab mr create creates a new merge request.
  • list - Used by commands that output more than one object at a time. For example, glab ci list returns a list of all running pipelines.
  • get - Used by commands that output a singular object at a time. For example, glab ci get --pipeline-id 1 returns the pipeline with the specified ID.
  • update - Used by commands that update one object at a time. For example, glab mr update 1 --title "new title" updates the title of the merge request with ID 1.
  • delete - Used when deleting one or more objects at time. For example, glab ci delete 1,2,3 deletes the pipelines with IDs 1, 2, and 3.

Features generally have some or all of these commands. However, some features do not map well to the listed commands. In situations like these, it's okay to create or use separate verbs that make the most sense for the feature.

Command Structure

Commands in this repository follow the OpenShift guidelines with the following differences:

  • xxxOptions structs are private. No need to export them.
  • xxxOptions structs are called just options to avoid repeating the package name.
  • Methods and fields on options are not exported.
  • Only implement the necessary methods out of complete, validate and run.
  • Options struct constructor is optional and should be named newOptions - unexported and does not repeat the package name.
Precedent

When designing a feature, consider the existing ecosystem. It may be helpful to ask, "What's the most popular CLI tool in this domain?". The answer can help you decide the terminology used, a preference for a flag instead of a positional argument, and many more things. For example:

  • When working on a Kubernetes-related feature, kubectl design patterns might play a big role designing feature's command set.
  • When working on GitLab-specific features, use the current documentation and command list for design patterns.

Considering the context of use helps create a unifying experience that feels natural to users who work with other tooling in the same domain space.

Human-readable output

Design with human readable output as the default. The go-humanize module helps transform various types into a human-friendly version. See the module's documentation for a complete listing of the transformations supported.

Submitting a merge request

  1. Create a new branch: git checkout -b my-branch-name
  2. Make your change, add tests, and ensure tests pass
  3. Submit a merge request

Formatting your code

We use golangci-lint to lint and format the code in this project. The linter configuration can be seen in the .golangci.yml file for this project.

Additional details about code style and format are in the go guide.

Documenting commands

CLI documentation is generated from Go source files by make gen-docs. All documentation content must be authored in the cobra.Command definition fields (Short, Long, Example, and flag descriptions), not in the generated files in docs/source/.

For documentation structure, language conventions, and guidance on experimental and beta features, see the GitLab CLI (glab) documentation style guide.

Deprecation messages

When you deprecate a flag, command, or runtime warning, the message format follows specific conventions that depend on whether the message is emitted directly by glab or wrapped by Cobra.

For format and examples, see deprecation messages.

Commit Messages

Each commit message consists of a header, a body, and a footer. The header has a special format that includes a type, a scope, and a description:

plaintext
<type>(<scope>): <description>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Each line in the commit message should be no longer than 72 characters.

Message Header

The message header is mandatory, and should be a single line that contains a succinct description of the change containing a type, an optional scope, and a description. Ideally, it should not be more than 50 characters in length.

Following these conventions results in a clear changelog for every version.

It's generally a good idea to follow the conventions for your MR's title as well as for commit messages. This way, if your merge request is squashed upon merge, the maintainer can use its title as the final commit message, creating a properly-formatted history.

If your MR contains multiple commits but only one logical change, the Squash commits when merge request is accepted option (enabled by default in this project) will allow GitLab to use the MR title as the commit message.

<type>

This describes the kind of change that this commit is providing

  • feat: A new feature (adding a new component, providing new variants for an existing component, etc.).
  • fix: A bug fix (correcting a styling issue, addressing a bug in a component's API, etc.). When updating non-dev dependencies, mark your changes with the fix: type.
  • docs: Documentation-only changes.
  • style: Changes that do not affect the meaning of the code (whitespace, formatting, missing semicolons, etc). Not to be used for UI changes as those are meaningful changes, consider using feat: of fix: instead.
  • refactor: A code change that neither fixes a bug nor adds a feature.
  • perf: A code change that improves performance.
  • test: Adding missing tests or correcting existing tests.
  • build: Changes that affect the build system.
  • ci: Changes to our CI/CD configuration files and scripts.
  • chore: Other changes that don't modify source or test files. Use this type when adding or updating dev dependencies.
  • revert: Reverts a previous commit.

Each commit type can have an optional scope to specify the place of the commit change: type(scope):. It is up to you to add or omit a commit's scope. When a commit affects a specific component, use the component's PascalCase name as the commit's scope. For example:

plaintext
feat(statusbar): automatically switch pipelines
<scope>

Scope can be anything specifying the place of the commit change. For example events, kafka, userModel, authorization, authentication, loginPage, etc

<description>

This is a very short description of the change

  • use imperative, present tense: “change” not “changed” nor “changes”
  • don't capitalize the first letter
  • no dot (.) at the end

Message Body

Just as in the description, use imperative, present tense: “change” not “changed” nor “changes.” Include motivation for the change and contrast it with previous behavior.

More info on writing good Git commit messages

Finished, fixed or delivered stories should be listed on a separate line in the footer prefixed with "Finishes", "Fixes" , or "Delivers" keyword like this:

[(Finishes|Fixes|Delivers) #ISSUE_ID]

Message Example

shell
feat(kafka): implement exactly once delivery

- ensure every event published to kafka is delivered exactly once
- implement error handling for failed delivery

Delivers #065
shell
fix(login): allow provided user preferences to override default preferences

- This allows the preferences associated with a user account to
override and customize the default app preferences like theme or timezone.

Fixes #025

Linting

We use the following logic to lint your MR's commit messages:

mermaid
graph TD
A{Are there multiple commits?} --no--> B[Commit must be valid]
A --yes--> C
C{Is MR set to be squashed?} --no--> D[Every commit must be valid]
C --yes--> E[MR title must be valid]

Creating a Workspace

To create a workspace:

  1. Go to the CLI project or any merge request.
  2. In the upper-right corner, select Code.
  3. Select Open in Workspace.
  4. Complete the form. The form is pre-filled with cluster agent configuration, project reference, and Devfile.
  5. Select Create workspace.

Wait until the workspace status is Running, then select Open workspace to launch your development environment.

After your workspace is running, you can start developing:

bash
# Build the CLI binary
make

# Run the CLI
./bin/glab

# Run unit tests
make test

# Format and lint code
make lint

For workspace-specific issues:

Debugging

The project includes a .vscode/launch.json file that you can use in Visual Studio Code when debugging the code. Add the command line arguments in the args array otherwise you will see the default --help output. Make sure you don't commit this file when pushing your changes.

1# Contributing Guide
3## Developer Certificate of Origin + License
5Contributions to this repository are subject to the [Developer Certificate of Origin](https://docs.gitlab.com/legal/developer_certificate_of_origin/).
7All Documentation content that resides under the [`docs/` directory](docs/README.md) of this
8repository is licensed under Creative Commons:
9[CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
11_This notice should stay as the first item in the CONTRIBUTING.md file._
13---
15Thank you for your interest in contributing to the GitLab CLI! This guide details how to contribute
16to this extension in a way that is easy for everyone. These are mostly guidelines, not rules.
17Use your best judgement, and feel free to propose changes to this document in a merge request.
19Please do:
21- Check existing issues to verify that the bug or feature request has not already been submitted.
22- Open an issue if things aren't working as expected.
23- Open an issue to propose a significant change.
24- Open an issue to propose a feature.
25- Open a merge request to fix a bug.
26- Open a merge request to fix documentation about a command.
27- Open a merge request for an issue and leave a comment claiming it.
29Please avoid:
31- Opening merge requests for issues marked `blocked`.
32- Opening merge requests that only add or edit files in `docs/source/`. These files are
33 auto-generated from Go source by `make gen-docs` and are overwritten on every release.
34 Instead, update the documentation fields in the relevant `cobra.Command` definition.
35 For guidance, see the [CLI documentation style guide](https://docs.gitlab.com/development/documentation/cli_styleguide/).
37## Code of Conduct
39We want to create a welcoming environment for everyone who is interested in contributing. Visit our [Code of Conduct page](https://about.gitlab.com/community/contribute/code-of-conduct/) to learn more about our commitment to an open and welcoming environment.
41## Maintainership
43GitLab team members who want to review or maintain the CLI can follow the
44[reviewer and maintainer guide](docs/maintainer.md).
46## Getting Started
48### Reporting Issues
50Create a [new issue from the "Default" template](https://gitlab.com/gitlab-org/cli/-/issues/new?issuable_template=Default) and follow the instructions in the template.
52### Dependency management
54Go and Node.js dependencies are managed automatically by Renovate, which opens
55[merge requests](https://gitlab.com/gitlab-org/cli/-/merge_requests/?sort=created_date&state=opened&label_name%5B%5D=maintenance%3A%3Adependency&first_page_size=100) as upstream releases become available.
56Updates are merged on our normal review cadence rather than immediately, to
57give us time to verify compatibility.
59Every CI/CD pipeline also runs GitLab Advanced SAST, Dependency Scanning, and
60Secret Detection. Vulnerabilities in our direct dependencies surface
61automatically in the project's Vulnerability Report.
63### Reporting a vulnerability
65If you believe you've found a security vulnerability in `glab`, follow the
66process in the [security policy](SECURITY.md). Do not open a public issue.
68If you're relaying output from a container-image scanner (Trivy, Grype, and
69similar), please first verify that the vulnerability is actually reachable
70from `glab` code. The Go team provides
71[`govulncheck`](https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck), a
72separate tool that performs analysis of call-graph reachability:
74```shell
75go install golang.org/x/vuln/cmd/govulncheck@latest
76govulncheck ./...
77```
79Image scanners frequently flag module-level CVEs in transitive Go dependencies that
80the CLI never imports. For example sub-packages of `golang.org/x/image` or `golang.org/x/net`.
82These findings are not actionable on their own, but a
83`govulncheck` report that shows a reachable symbol is.
85### Your First Code Contribution?
87Read about the contribution process in [`development_process.md`](docs/development_process.md). This document explains how we review and release changes.
89If your merge request is trivial (fixing typos, fixing a bug with 20 lines of code), create a merge request.
91If your merge request is large, create an issue first. See [Reporting Issues](#reporting-issues) and [Proposing Features](#proposing-features). In the issue, the project maintainers can help you scope the work and make you more efficient.
93### Developing with Workspaces
95[GitLab Workspaces](https://docs.gitlab.com/user/workspace/) are fully enabled for the CLI project,
96providing a complete development environment in your browser.
98Benefits of using Workspaces:
100- Zero setup: No requirement to install Go, dependencies, or clone the repository locally.
101- Pre-configured environment: All development tools and dependencies are ready to use.
102- Immediate development: Start coding, running tests, or making edits right away.
103- New contributor onboarding: A great way for new contributors to start without local machine setup.
104- MR-based development: Open a Workspace directly from a merge request for testing and reviews.
105- No context switching: Make changes during code reviews without switching to your local machine.
107For more information see, [Creating a workspace](#creating-a-workspace).
109### Building the project
111Prerequisites:
113- Go, at the version in [`go.mod`](https://gitlab.com/gitlab-org/cli/-/blob/main/go.mod?ref_type=heads#L3) or later.
114 CI and releases build with the version in [`.tool-versions`](https://gitlab.com/gitlab-org/cli/-/blob/main/.tool-versions).
116Build with: `make` or `go build -o bin/glab ./cmd/glab/main.go`
118Run the new binary as: `./bin/glab`
120### Go version updates
122glab follows the [GitLab Go upgrade guide](https://docs.gitlab.com/development/go_guide/go_upgrade/):
124- `.tool-versions` and `GO_VERSION` in `.gitlab-ci.yml` pin the exact toolchain. Patch upgrades,
125 including security fixes, change only these two.
126- The `go` directive in `go.mod` is the minimum version for building from source, and always uses
127 patch `0`. Bump it only when moving the toolchain to a new minor version, usually from the glab issue
128 in the Go upgrade epic.
130`scripts/check-go-version.sh` enforces these rules in CI.
132### Git hooks with Lefthook (optional)
134This project supports [Lefthook](https://github.com/evilmartians/lefthook) for managing Git hooks. Lefthook helps catch issues before pushing to CI by running checks locally.
136#### Quick setup
1381. Install development tools using [mise](https://mise.jdx.dev/):
140 ```bash
141 # Install mise if you don't have it
142 curl https://mise.run | sh
144 # Install all development tools (includes lefthook)
145 make bootstrap
147 # Enable git hooks
148 lefthook install
149 ```
151 This installs all tools defined in `.tool-versions`: Go, golangci-lint (includes gofumpt and goimports formatters), shellcheck, markdownlint-cli2, vale, lychee, rumdl, Node.js, lefthook, and commitlint dependencies.
153#### Available hooks
155- **pre-commit**: Formats and lints Go code (golangci-lint with gofumpt/goimports), lints shell scripts (shellcheck), auto-fixes Markdown formatting (markdownlint), checks and regenerates documentation if command files changed (blocks commit until docs are staged)
156- **commit-msg**: Validates commit messages follow [conventional commits](https://www.conventionalcommits.org/) format
157- **pre-push**: Runs documentation validation (markdownlint, rumdl, vale, lychee) on changed files
159#### Graceful degradation
161If a required tool is not installed, the hook will display a warning and skip that check. This means you can install lefthook immediately and add tools incrementally. All validation also runs in CI, so nothing is missed.
163#### Skipping hooks
165If you need to skip hooks temporarily:
167```bash
168# Skip all hooks for one commit
169LEFTHOOK=0 git commit -m "message"
171# Skip all hooks for one push
172LEFTHOOK=0 git push
174# Skip specific hook
175LEFTHOOK_EXCLUDE=pre-push git push
176```
178### Running tests
180Run tests with: `go test ./...` or `make test`.
182There are some integration tests that perform real API requests to `https://gitlab.com`.
183If the environment variables `GITLAB_TEST_HOST` and `GITLAB_TOKEN_TEST` are not set, the integration tests will fail in CI if
184being run in the `gitlab-org/cli` project. They will be skipped locally or in forks if either `GITLAB_TEST_HOST` or `GITLAB_TOKEN_TEST`
185is unset.
186Integration tests use the `_Integration` test suffix and use the `_integration_test.go` file suffix.
188`GITLAB_TEST_HOST` is set to `https://gitlab.com` in CI.
190`GITLAB_TOKEN_TEST` must be a
191[personal access token](https://docs.gitlab.com/user/profile/personal_access_tokens/) and requires the `api` scope.
192To ensure the `glab duo` feature is functioning correctly, the token's user must have a GitLab Duo seat.
194### Proposing Features
196Create a [new issue from the "Feature Request" template](https://gitlab.com/gitlab-org/cli/-/issues/new?issuable_template=Feature%20Request) and follow the instructions in the template.
198### Designing a new feature
200The
201[Design Command-Line Tools People Love presentation](https://www.youtube.com/watch?v=eMz0vni6PAw)
202by Carolyn Van Slyck provides some great guidance on things to consider when implementing
203a CLI tool. We recommend the entire presentation, but the following points are especially
204important in the context of the GitLab CLI.
206#### Grammar
208GitLab CLI commands use a noun-first, verb-second grammatical structure, like
209`glab ci list`. Also, these verbs are shared by various commands, and have
210expected behavior as a result:
212- `create` - Used when creating a singular object. For example, `glab mr create`
213 creates a new merge request.
214- `list` - Used by commands that output more than one object at a time. For example,
215 `glab ci list` returns a list of all running pipelines.
216- `get` - Used by commands that output a singular object at a time. For example,
217 `glab ci get --pipeline-id 1` returns the pipeline with the specified ID.
218- `update` - Used by commands that update one object at a time. For example,
219 `glab mr update 1 --title "new title"` updates the title of the merge request with ID `1`.
220- `delete` - Used when deleting one or more objects at time. For example, `glab ci delete 1,2,3`
221 deletes the pipelines with IDs `1`, `2`, and `3`.
223Features generally have some or all of these commands. However, some features do not
224map well to the listed commands. In situations like these, it's okay to create or
225use separate verbs that make the most sense for the feature.
227#### Command Structure
229Commands in this repository follow the
230[OpenShift guidelines](https://github.com/openshift/origin/blob/master/docs/cli_hacking_guide.adoc)
231with the following differences:
233- `xxxOptions` structs are private. No need to export them.
234- `xxxOptions` structs are called just `options` to avoid repeating the package name.
235- Methods and fields on `options` are not exported.
236- Only implement the necessary methods out of `complete`, `validate` and `run`.
237- Options struct constructor is optional and should be named `newOptions` - unexported and does not repeat the package name.
239#### Precedent
241When designing a feature, consider the existing ecosystem. It may be helpful to ask,
242_"What's the most popular CLI tool in this domain?"_. The answer can help you decide
243the terminology used, a preference for a flag instead of a positional argument, and
244many more things. For example:
246- When working on a Kubernetes-related feature, `kubectl` design patterns
247 might play a big role designing feature's command set.
248- When working on GitLab-specific features, use the current documentation and
249 command list for design patterns.
251Considering the context of use helps create a unifying experience that feels natural
252to users who work with other tooling in the same domain space.
254#### Human-readable output
256Design with human readable output as the default. The
257[`go-humanize`](https://github.com/dustin/go-humanize) module helps transform
258various types into a human-friendly version. See the module's documentation for
259a complete listing of the transformations supported.
261### Submitting a merge request
2631. Create a new branch: `git checkout -b my-branch-name`
2641. Make your change, add tests, and ensure tests pass
2651. Submit a merge request
267### Formatting your code
269We use [`golangci-lint`](https://golangci-lint.run/) to lint and format
270the code in this project. The linter configuration can be seen in the
271[.golangci.yml file for this project](https://gitlab.com/gitlab-org/cli/-/blob/main/.golangci.yml).
273Additional details about code style and format are in the
274[go guide](https://docs.gitlab.com/development/go_guide/#code-style-and-format).
276### Documenting commands
278CLI documentation is generated from Go source files by `make gen-docs`. All documentation
279content must be authored in the `cobra.Command` definition fields (`Short`, `Long`, `Example`,
280and flag descriptions), not in the generated files in `docs/source/`.
282For documentation structure, language conventions, and guidance on experimental and beta
283features, see the [GitLab CLI (glab) documentation style guide](https://docs.gitlab.com/development/documentation/cli_styleguide/).
285### Deprecation messages
287When you deprecate a flag, command, or runtime warning, the message format
288follows specific conventions that depend on whether the message is emitted
289directly by glab or wrapped by Cobra.
291For format and examples, see [deprecation messages](https://docs.gitlab.com/development/documentation/cli_styleguide/#deprecations).
293## Commit Messages
295Each commit message consists of a **header**, a **body**, and a **footer**. The header has a special format that includes a **type**, a **scope**, and a **description**:
297```plaintext
298<type>(<scope>): <description>
299<BLANK LINE>
300<body>
301<BLANK LINE>
302<footer>
303```
305Each line in the commit message should be no longer than 72 characters.
307### Message Header
309The message header is mandatory, and should be a single line that contains a succinct description of the change containing a type, an optional scope, and a description. Ideally, it should not be more than 50 characters in length.
311Following these conventions results in a clear changelog for every version.
313It's generally a good idea to follow the conventions for your MR's title as well as for commit messages. This way, if your merge request is squashed upon merge, the maintainer can use its title as the final commit message, creating a properly-formatted history.
315If your MR contains multiple commits but only one logical change, the [Squash commits when merge request is accepted](https://docs.gitlab.com/user/project/merge_requests/squash_and_merge/) option (enabled by default in this project) will allow GitLab to use the MR title as the commit message.
317#### `<type>`
319This describes the kind of change that this commit is providing
321- **feat:** A new feature (adding a new component, providing new variants for an existing component, etc.).
322- **fix:** A bug fix (correcting a styling issue, addressing a bug in a component's API, etc.).
323 When updating non-dev dependencies, mark your changes with the `fix:` type.
324- **docs:** Documentation-only changes.
325- **style:** Changes that do not affect the meaning of the code
326 (whitespace, formatting, missing semicolons, etc). _Not_ to be used for UI changes as those are
327 meaningful changes, consider using `feat:` of `fix:` instead.
328- **refactor:** A code change that neither fixes a bug nor adds a feature.
329- **perf:** A code change that improves performance.
330- **test:** Adding missing tests or correcting existing tests.
331- **build:** Changes that affect the build system.
332- **ci:** Changes to our CI/CD configuration files and scripts.
333- **chore:** Other changes that don't modify source or test files. Use this type when adding or
334 updating dev dependencies.
335- **revert:** Reverts a previous commit.
337Each commit type can have an optional scope to specify the place of the commit change: `type(scope):`. It is up to you to add or omit a commit's scope. When a commit affects a specific component, use the component's PascalCase name as the commit's scope. For example:
339```plaintext
340feat(statusbar): automatically switch pipelines
341```
343#### `<scope>`
345Scope can be anything specifying the place of the commit change. For example events, kafka, userModel, authorization, authentication, loginPage, etc
347#### `<description>`
349This is a very short description of the change
351- `use imperative, present tense: “change” not “changed” nor “changes”`
352- `don't capitalize the first letter`
353- `no dot (.) at the end`
355### Message Body
357Just as in the description, use imperative, present tense: “change” not “changed” nor “changes.” Include motivation for the change and contrast it with previous behavior.
359#### More info on writing good Git commit messages
361- [Writing Git commit messages](http://365git.tumblr.com/post/3308646748/writing-git-commit-messages)
362- [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
364### Message Footer
366Finished, fixed or delivered stories should be listed on a separate line in the footer prefixed with "Finishes", "Fixes" , or "Delivers" keyword like this:
368`[(Finishes|Fixes|Delivers) #ISSUE_ID]`
370### Message Example
372```shell
373feat(kafka): implement exactly once delivery
375- ensure every event published to kafka is delivered exactly once
376- implement error handling for failed delivery
378Delivers #065
379```
381```shell
382fix(login): allow provided user preferences to override default preferences
384- This allows the preferences associated with a user account to
385override and customize the default app preferences like theme or timezone.
387Fixes #025
388```
390### Linting
392We use the following logic to lint your MR's commit messages:
394```mermaid
395graph TD
396A{Are there multiple commits?} --no--> B[Commit must be valid]
397A --yes--> C
398C{Is MR set to be squashed?} --no--> D[Every commit must be valid]
399C --yes--> E[MR title must be valid]
400```
402### Creating a Workspace
404To create a workspace:
4061. Go to the CLI project or any merge request.
4071. In the upper-right corner, select **Code**.
4081. Select **Open in Workspace**.
4091. Complete the form. The form is pre-filled with cluster agent configuration, project reference,
410 and Devfile.
4111. Select **Create workspace**.
413Wait until the workspace status is **Running**, then select **Open workspace** to launch your
414development environment.
416After your workspace is running, you can start developing:
418```bash
419# Build the CLI binary
420make
422# Run the CLI
423./bin/glab
425# Run unit tests
426make test
428# Format and lint code
429make lint
430```
432For workspace-specific issues:
434- See the [GitLab Workspaces documentation](https://docs.gitlab.com/user/workspace/).
435- Reach out in the Slack `#f_workspaces` channel.
436- Create an issue in the [Workspace User Feedback Epic](https://gitlab.com/groups/gitlab-org/-/epics/12601).
438## Debugging
440The project includes a `.vscode/launch.json` file that you can use in Visual Studio Code when debugging the code.
441Add the command line arguments in the `args` array otherwise you will see the default `--help` output.
442Make sure you don't commit this file when pushing your changes.
Diagnostics5 git calls · 24 ms
CallStatusSizeTime024 ms
discover200185 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=59849
git.response.cache=UPDATING
git.response.duration_ms=2
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetchtree:0 · deepen 1020032 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=19
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetch2007.6 KiB · hit19 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=7815
git.response.cache=HIT
git.response.duration_ms=19
git.fetch.wants=53fecc75bfb9f73ee4c8a468d9a964e6ed7e25d5
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=7815
git.pkt.payload.max=7788
git.sideband.band1.bytes=7788
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e10aac5e59910d
Request
71c31ba6…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format