GitLabgitlab-org

cli

main
ply6 git calls33 ms98 KiB5 cachedprotocol v2
96 lines3.6 KiBRaw

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

By default, glab connects to GitLab.com. To use a GitLab Self-Managed or GitLab Dedicated instance instead, change your configuration. You can also configure glab for instances that present a client or self-signed certificate.

Set a default instance

When outside a Git repository, glab uses gitlab.com by default. For glab to default to your GitLab Self-Managed or GitLab Dedicated instance when you are not in a Git repository, change the host configuration settings. Use this command, changing gitlab.example.com to the domain name of your instance:

shell
glab config set -g host gitlab.example.com

When you sign in with glab auth login, glab sets host to that instance for you if host is still gitlab.com and you have no gitlab.com token. Otherwise, it asks first, or in a non-interactive run prints the command to run.

Setting this configuration enables you to perform commands outside a Git repository while using your GitLab Self-Managed or GitLab Dedicated instance. For example:

  • glab repo clone group/project
  • glab issue list -R group/project

If you don't set a default domain name, you can declare one for the current command with the GITLAB_HOST environment variable, like this:

  • GITLAB_HOST=gitlab.example.com glab repo clone group/project
  • GITLAB_HOST=gitlab.example.com glab issue list -R group/project

When inside a Git repository, glab uses that repository's GitLab host by default. For example, glab issue list lists all issues of the current directory's Git repository.

Use mTLS certificates

To use a mutual TLS (Mutual Transport Layer Security) certificate with glab, edit your global configuration file (~/.config/glab-cli/config.yml) to provide connection information:

yaml
hosts:
    git.your-domain.com:
        api_protocol: https
        api_host: git.your-domain.com
        token: xxxxxxxxxxxxxxxxxxxxxxxxx
        client_cert: /path/to/client.crt
        client_key: /path/to/client.key
        ca_cert: /path/to/ca-chain.pem
  • ca_cert is optional for mTLS support if you use a publicly signed server certificate.
  • token is not required if you use a different authentication method.
  • client_cert and client_key can be PEM or DER files.

To use a PKCS#12 bundle (.p12 or .pfx) that holds both the certificate and the key, set client_cert to the bundle, leave client_key unset, and set the bundle's password:

shell
glab config set --host git.your-domain.com client_cert /path/to/client.p12
glab config set --host git.your-domain.com client_cert_password <password>

If the host uses the operating system keyring (use_keyring: true), glab stores client_cert_password in the keyring. You can also set it with the GLAB_CLIENT_CERT_PASSWORD environment variable.

Use self-signed certificates

To configure the GitLab CLI to support GitLab Self-Managed and GitLab Dedicated instances with self-signed certificates, either:

  • Disable TLS verification with:

    shell
    glab config set skip_tls_verify true --host gitlab.example.com
  • Add the path to the self signed CA:

    shell
    glab config set ca_cert /path/to/server.pem --host gitlab.example.com
1---
2title: Connect to your GitLab instance
3stage: AI Clients
4group: Developer Clients
5info: To determine the technical writer assigned to the Stage/Group associated with this page, see <https://handbook.gitlab.com/handbook/marketing/product-and-technical-marketing/technical-writing/#assignments>
6---
8{{< details >}}
10- Tier: Free, Premium, Ultimate
11- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
13{{< /details >}}
15By default, `glab` connects to GitLab.com. To use a GitLab Self-Managed or GitLab Dedicated
16instance instead, change your configuration. You can also configure `glab` for instances that
17present a client or self-signed certificate.
19## Set a default instance
21When outside a Git repository, `glab` uses `gitlab.com` by default. For `glab` to default
22to your GitLab Self-Managed or GitLab Dedicated instance when you are not in a Git repository, change the host
23configuration settings. Use this command, changing `gitlab.example.com` to the domain name
24of your instance:
26```shell
27glab config set -g host gitlab.example.com
28```
30When you sign in with `glab auth login`, `glab` sets `host` to that instance for you if `host`
31is still `gitlab.com` and you have no `gitlab.com` token. Otherwise, it asks first, or in a
32non-interactive run prints the command to run.
34Setting this configuration enables you to perform commands outside a Git repository while
35using your GitLab Self-Managed or GitLab Dedicated instance. For example:
37- `glab repo clone group/project`
38- `glab issue list -R group/project`
40If you don't set a default domain name, you can declare one for the current command with
41the `GITLAB_HOST` environment variable, like this:
43- `GITLAB_HOST=gitlab.example.com glab repo clone group/project`
44- `GITLAB_HOST=gitlab.example.com glab issue list -R group/project`
46When inside a Git repository, `glab` uses that repository's GitLab host by default. For example,
47`glab issue list` lists all issues of the current directory's Git repository.
49## Use mTLS certificates
51To use a mutual TLS (Mutual Transport Layer Security) certificate with `glab`, edit your global
52configuration file (`~/.config/glab-cli/config.yml`) to provide connection information:
54```yaml
55hosts:
56 git.your-domain.com:
57 api_protocol: https
58 api_host: git.your-domain.com
59 token: xxxxxxxxxxxxxxxxxxxxxxxxx
60 client_cert: /path/to/client.crt
61 client_key: /path/to/client.key
62 ca_cert: /path/to/ca-chain.pem
63```
65- `ca_cert` is optional for mTLS support if you use a publicly signed server certificate.
66- `token` is not required if you use a different authentication method.
67- `client_cert` and `client_key` can be PEM or DER files.
69To use a PKCS#12 bundle (`.p12` or `.pfx`) that holds both the certificate and the key, set
70`client_cert` to the bundle, leave `client_key` unset, and set the bundle's password:
72```shell
73glab config set --host git.your-domain.com client_cert /path/to/client.p12
74glab config set --host git.your-domain.com client_cert_password <password>
75```
77If the host uses the operating system keyring (`use_keyring: true`), `glab` stores
78`client_cert_password` in the keyring. You can also set it with the `GLAB_CLIENT_CERT_PASSWORD`
79environment variable.
81## Use self-signed certificates
83To configure the GitLab CLI to support GitLab Self-Managed and GitLab Dedicated instances with
84self-signed certificates, either:
86- Disable TLS verification with:
88 ```shell
89 glab config set skip_tls_verify true --host gitlab.example.com
90 ```
92- Add the path to the self signed CA:
94 ```shell
95 glab config set ca_cert /path/to/server.pem --host gitlab.example.com
96 ```
Diagnostics6 git calls · 33 ms
CallStatusSizeTime033 ms
discover200185 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
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 KiB · hit2 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=HIT
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
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=3
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
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit5 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=5
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=5
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:02001.7 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=1744
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=5e4007a5673eb3bf5d0d7f1a1463c3b2ca3fb3bd
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=1744
git.pkt.payload.max=1717
git.sideband.band1.bytes=1717
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=1717
git.pack.trailer=3f1b9ccc7756e8941d6705e8187c87fd922113e6
Open pack map
fetch2001.5 KiB · hit24 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=24
git.response.bytes=1510
git.response.cache=HIT
git.response.duration_ms=24
git.fetch.wants=f8d45790016f37b7851daabfc09de5beec8eb90c
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=1510
git.pkt.payload.max=1483
git.sideband.band1.bytes=1483
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
a5e122ad2aca7fd8
Request
6beaa659…
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