python-gitlab provides a :command:`gitlab` command-line tool to interact with GitLab servers.

This is especially convenient for running quick ad-hoc commands locally, easily interacting with the API inside GitLab CI, or with more advanced shell scripting when integrating with other tooling.

gitlab allows setting configuration options via command-line arguments, environment variables, and configuration files.

For a complete list of global CLI options and their environment variable equivalents, see :doc:`/cli-objects`.

With no configuration provided, gitlab will default to unauthenticated requests against GitLab.com.

With no configuration but running inside a GitLab CI job, it will default to authenticated requests using the current job token against the current instance (via CI_SERVER_URL and CI_JOB_TOKEN environment variables).

When you provide configuration, values are evaluated with the following precedence:

1. Explicitly provided CLI arguments,
2. Environment variables,
3. Configuration files:
   1. explicitly defined config files:
      1. via the --config-file CLI argument,
      2. via the PYTHON_GITLAB_CFG environment variable,
   2. user-specific config file,
   3. system-level config file,
4. Environment variables always present in CI (CI_SERVER_URL, CI_JOB_TOKEN).

Additionally, authentication will take the following precedence when multiple options or environment variables are present:

1. Private token,
2. OAuth token,
3. CI job token.

gitlab looks up 3 configuration files by default:

The PYTHON_GITLAB_CFG environment variable An environment variable that contains the path to a configuration file. /etc/python-gitlab.cfg System-wide configuration file ~/.python-gitlab.cfg User configuration file

You can use a different configuration file with the --config-file option.

The configuration file uses the INI format. It contains at least a [global] section, and a specific section for each GitLab server. For example:

The default option of the [global] section defines the GitLab server to use if no server is explicitly specified with the --gitlab CLI option.

The [global] section also defines the values for the default connection parameters. You can override the values in each GitLab server section.

Global options Option Possible values Description

ssl_verify	True, False, or a str	Verify the SSL certificate. Set to False to disable verification, though this will create warnings. Any other value is interpreted as path to a CA_BUNDLE file or directory with certificates of trusted CAs.
timeout	Integer	Number of seconds to wait for an answer before failing.
api_version	4	The API version to use to make queries. Only 4 is available since 1.5.0.
per_page	Integer between 1 and 100	The number of items to return in listing queries. GitLab limits the value at 100.
user_agent	str	A string defining a custom user agent to use when gitlab makes requests.

You must define the url in each GitLab server section.

Only one of private_token, oauth_token or job_token should be defined. If neither are defined an anonymous request will be sent to the Gitlab server, with very limited permissions.

We recommend that you use Credential helpers to securely store your tokens.

GitLab server options Option Description

url	URL for the GitLab server. Do NOT use a URL which redirects.
private_token	Your user token. Login/password is not supported. Refer to the official documentation to learn how to obtain a token.
oauth_token	An Oauth token for authentication. The Gitlab server must be configured to support this authentication method.
job_token	Your job token. See the official documentation to learn how to obtain a token.
api_version	GitLab API version to use. Only 4 is available since 1.5.0.

For all configuration options that contain secrets (for example, personal_token, oauth_token, job_token), you can specify a helper program to retrieve the secret indicated by a helper: prefix. This allows you to fetch values from a local keyring store or cloud-hosted vaults such as Bitwarden. Environment variables are expanded if they exist and ~ expands to your home directory.

It is expected that the helper program prints the secret to standard output. To use shell features such as piping to retrieve the value, you will need to use a wrapper script; see below.

Example for a keyring helper:

Example for a pass helper with a wrapper script:

In /path/to/helper.sh:

The gitlab command expects two mandatory arguments. The first one is the type of object that you want to manipulate. The second is the action that you want to perform. For example:

Use the --help option to list the available object types and actions:

Some actions require additional parameters. Use the --help option to list mandatory and optional arguments for an action:

Use the following optional arguments to change the behavior of gitlab. These options must be defined before the mandatory arguments.

--verbose, -v Outputs detail about retrieved objects. Available for legacy (default) output only. --config-file, -c Path to a configuration file. --gitlab, -g ID of a GitLab server defined in the configuration file. --output, -o Output format. Defaults to a custom format. Can also be yaml or json. --fields, -f Comma-separated list of fields to display (yaml and json output formats only). If not used, all the object fields are displayed.

Example:

You can make gitlab read values from files instead of providing them on the command line. This is handy for values containing new lines for instance:

To get autocompletion, you'll need to install the package with the extra "autocompletion":

Add the appropriate command below to your shell's config file so that it is run on startup. You will likely have to restart or re-login for the autocompletion to start working.

To activate completions for zsh you need to have bashcompinit enabled in zsh:

Afterwards you can enable completion for gitlab: