python-gitlab
provides a :command:`gitlab` command-line tool to interact
with GitLab servers. It uses a configuration file to define how to connect to
the servers.
gitlab
looks up 2 configuration files by default:
/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:
[global]
default = somewhere
ssl_verify = true
timeout = 5
[somewhere]
url = https://some.whe.re
private_token = vTbFeqJYCY3sibBP7BZM
api_version = 3
[elsewhere]
url = http://else.whe.re:8080
private_token = CkqsjqcQSFH5FQKDccu4
timeout = 1
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.
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 |
3 ou 4 |
The API version to use to make queries. Requires python-gitlab >= 1.3.0. |
per_page |
Integer between 1 and 100 | The number of items to return in listing queries. GitLab limits the value at 100. |
You must define the url
in each GitLab server section.
Only one of private_token
or oauth_token
should be defined. If neither
are defined an anonymous request will be sent to the Gitlab server, with very
limited permissions.
Option | Description |
---|---|
url |
URL for the GitLab server |
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. |
api_version |
GitLab API version to use (3 or 4 ). Defaults to 4 since
version 1.3.0. |
http_username |
Username for optional HTTP authentication |
http_password |
Password for optional HTTP authentication |
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:
$ gitlab project list
Use the --help
option to list the available object types and actions:
$ gitlab --help
$ gitlab project --help
Some actions require additional parameters. Use the --help
option to
list mandatory and optional arguments for an action:
$ gitlab project create --help
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
orjson
. --fields
,-f
- Comma-separated list of fields to display (
yaml
andjson
output formats only). If not used, all the object fields are displayed.
Example:
$ gitlab -o yaml -f id,permissions -g elsewhere -c /tmp/gl.cfg project list
List the projects (paginated):
$ gitlab project list
List all the projects:
$ gitlab project list --all
Limit to 5 items per request, display the 1st page only
$ gitlab project list --page 1 --per-page 5
Get a specific project (id 2):
$ gitlab project get --id 2
Get a specific user by id:
$ gitlab user get --id 3
Get a list of snippets for this project:
$ gitlab project-issue list --project-id 2
Delete a snippet (id 3):
$ gitlab project-snippet delete --id 3 --project-id 2
Update a snippet:
$ gitlab project-snippet update --id 4 --project-id 2 \
--code "My New Code"
Create a snippet:
$ gitlab project-snippet create --project-id 2
Impossible to create object (Missing attribute(s): title, file-name, code)
$ # oops, let's add the attributes:
$ gitlab project-snippet create --project-id 2 --title "the title" \
--file-name "the name" --code "the code"
Define the status of a commit (as would be done from a CI tool for example):
$ gitlab project-commit-status create --project-id 2 \
--commit-id a43290c --state success --name ci/jenkins \
--target-url http://server/build/123 \
--description "Jenkins build succeeded"
Use sudo to act as another user (admin only):
$ gitlab project create --name user_project1 --sudo username
List values are comma-separated:
$ gitlab issue list --labels foo,bar
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:
$ cat > /tmp/description << EOF
This is the description of my project.
It is obviously the best project around
EOF
$ gitlab project create --name SuperProject --description @/tmp/description