Table of Contents
gitlab package)gitlab command)python-gitlab provides agitlab command-line tool to interactwith GitLab servers.
This is especially convenient for running quick ad-hoc commands locally, easilyinteracting with the API inside GitLab CI, or with more advanced shell scriptingwhen 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 variableequivalents, seeCLI reference (gitlab command).
With no configuration provided,gitlab will default to unauthenticatedrequests againstGitLab.com.
With no configuration but running inside a GitLab CI job, it will default toauthenticated requests using the current job token against the current instance(viaCI_SERVER_URL andCI_JOB_TOKEN environment variables).
Warning
Please note the job token has very limited permissions and can only be usedwith certain endpoints. You may need to provide a personal access token instead.
When you provide configuration, values are evaluated with the following precedence:
Explicitly provided CLI arguments,
Environment variables,
Configuration files:
explicitly defined config files:
via the--config-file CLI argument,
via thePYTHON_GITLAB_CFG environment variable,
user-specific config file,
system-level config file,
Environment variables always present in CI (CI_SERVER_URL,CI_JOB_TOKEN).
Additionally, authentication will take the following precedencewhen multiple options or environment variables are present:
Private token,
OAuth token,
CI job token.
gitlab looks up 3 configuration files by default:
PYTHON_GITLAB_CFG environment variableAn environment variable that contains the path to a configuration file.
/etc/python-gitlab.cfgSystem-wide configuration file
~/.python-gitlab.cfgUser configuration file
You can use a different configuration file with the--config-file option.
Warning
If thePYTHON_GITLAB_CFG environment variable is defined and the targetfile exists, it will be the only configuration file parsed bygitlab.
If the environment variable is defined and the target file cannot be accessed,gitlab will fail explicitly.
The configuration file uses theINI format. It contains at least a[global] section, and a specific section for each GitLab server. Forexample:
[global]default=somewheressl_verify=truetimeout=5[somewhere]url=https://some.whe.reprivate_token=vTbFeqJYCY3sibBP7BZMapi_version=4[elsewhere]url=http://else.whe.re:8080private_token=helper: path/to/helper.shtimeout=1
Thedefault option of the[global] section defines the GitLab server touse if no server is explicitly specified with the--gitlab CLI option.
The[global] section also defines the values for the default connectionparameters. You can override the values in each GitLab server section.
Option | Possible values | Description |
|---|---|---|
|
| Verify the SSL certificate. Set to |
| Integer | Number of seconds to wait for an answer before failing. |
|
| The API version to use to make queries. Only |
| Integer between 1 and 100 | The number of items to return in listing queries. GitLab limits thevalue at 100. |
|
| A string defining a custom user agent to use when |
You must define theurl in each GitLab server section.
Warning
Note that a url that results in 301/302 redirects will raise an error,so it is highly recommended to use the final destination in theurl field.For example, if the GitLab server you are using redirects requests from httpto https, make sure to use thehttps:// protocol in the URL definition.
A URL that redirects using 301/302 (rather than 307/308) will most likelycause malformed POST and PUT requests.
python-gitlab will therefore raise aRedirectionError when it encountersa redirect which it believes will cause such an error, to avoid confusionbetween successful GET and failing POST/PUT requests on the same instance.
Only one ofprivate_token,oauth_token orjob_token should bedefined. If neither are defined an anonymous request will be sent to the Gitlabserver, with very limited permissions.
We recommend that you useCredential helpers to securely store your tokens.
Option | Description |
|---|---|
| URL for the GitLab server. DoNOT use a URL which redirects. |
| Your user token. Login/password is not supported. Refer totheofficial documentationto learn how to obtain a token. |
| An Oauth token for authentication. The Gitlab server must be configuredto support this authentication method. |
| Your job token. Seethe official documentationto learn how to obtain a token. |
| GitLab API version to use. Only |
For all configuration options that contain secrets (for example,personal_token,oauth_token,job_token), you can specifya helper program to retrieve the secret indicated by ahelper:prefix. This allows you to fetch values from a local keyring storeor cloud-hosted vaults such as Bitwarden. Environment variables areexpanded 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 needto use a wrapper script; see below.
Example for akeyring helper:
[global]default=somewheressl_verify=truetimeout=5[somewhere]url=http://somewhe.reprivate_token=helper: keyring get Service Usernametimeout=1
Example for apass helper with a wrapper script:
[global]default=somewheressl_verify=truetimeout=5[somewhere]url=http://somewhe.reprivate_token=helper: /path/to/helper.shtimeout=1
In/path/to/helper.sh:
#!/bin/bashpassshowpath/to/credentials|head-n1
Thegitlab command expects two mandatory arguments. The first one is thetype of object that you want to manipulate. The second is the action that youwant to perform. For example:
$gitlabprojectlistUse the--help option to list the available object types and actions:
$gitlab--help$gitlabproject--help
Some actions require additional parameters. Use the--help option tolist mandatory and optional arguments for an action:
$gitlabprojectcreate--helpUse the following optional arguments to change the behavior ofgitlab.These options must be defined before the mandatory arguments.
--verbose,-vOutputs detail about retrieved objects. Available for legacy (default)output only.
--config-file,-cPath to a configuration file.
--gitlab,-gID of a GitLab server defined in the configuration file.
--output,-oOutput format. Defaults to a custom format. Can also beyaml orjson.
Important
ThePyYAML package is required to use the yaml output option.You need to install it explicitly usingpipinstallpython-gitlab[yaml]
--fields,-fComma-separated list of fields to display (yaml andjson outputformats only). If not used, all the object fields are displayed.
Example:
$gitlab-oyaml-fid,permissions-gelsewhere-c/tmp/gl.cfgprojectlistYou can makegitlab read values from files instead of providing them on thecommand line. This is handy for values containing new lines for instance:
$cat>/tmp/description<<EOFThis is the description of my project.It is obviously the best project aroundEOF$gitlabprojectcreate--nameSuperProject--description@/tmp/description
It you want to explicitly pass an argument starting with@, you can escape it using@@:
$gitlabproject-taglist--project-idsomenamespace/myproject...name: @at-started-tag...$gitlabproject-tagdelete--project-idsomenamespace/myproject--name'@@at-started-tag'
To get autocompletion, you’ll need to install the package with the extra“autocompletion”:
pip install python_gitlab[autocompletion]Add the appropriate command below to your shell’s config file so that it is run onstartup. You will likely have to restart or re-login for the autocompletion tostart working.
eval "$(register-python-argcomplete gitlab)"eval ``register-python-argcomplete --shell tcsh gitlab``register-python-argcomplete --shell fish gitlab | .Warning
Zsh autocompletion support is broken right now in the argcomplete pythonpackage. Perhaps it will be fixed in a future release of argcomplete atwhich point the following instructions will enable autocompletion in zsh.
To activate completions for zsh you need to have bashcompinit enabled in zsh:
autoload -U bashcompinitbashcompinit
Afterwards you can enable completion for gitlab:
eval "$(register-python-argcomplete gitlab)"