#################### ``gitlab`` CLI usage #################### ``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. .. _cli_configuration: Configuration ============= Files ----- ``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. Content ------- The configuration file uses the ``INI`` format. It contains at least a ``[global]`` section, and a specific section for each GitLab server. For example: .. code-block:: ini [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. .. list-table:: Global options :header-rows: 1 * - 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`` or ``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. .. warning:: If the GitLab server you are using redirects requests from http to https, make sure to use the ``https://`` protocol in the ``url`` definition. 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. .. list-table:: GitLab server options :header-rows: 1 * - 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 __ https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html CLI === Objects and actions ------------------- 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: .. code-block:: console $ gitlab project list Use the ``--help`` option to list the available object types and actions: .. code-block:: console $ gitlab --help $ gitlab project --help Some actions require additional parameters. Use the ``--help`` option to list mandatory and optional arguments for an action: .. code-block:: console $ gitlab project create --help Optional arguments ------------------ 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``. **Notice:** The `PyYAML package `_ is required to use the yaml output option. You need to install it separately using ``pip install PyYAML`` ``--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: .. code-block:: console $ gitlab -o yaml -f id,permissions -g elsewhere -c /tmp/gl.cfg project list Examples ======== List the projects (paginated): .. code-block:: console $ gitlab project list List all the projects: .. code-block:: console $ gitlab project list --all Limit to 5 items per request, display the 1st page only .. code-block:: console $ gitlab project list --page 1 --per-page 5 Get a specific project (id 2): .. code-block:: console $ gitlab project get --id 2 Get a specific user by id: .. code-block:: console $ gitlab user get --id 3 Get a list of snippets for this project: .. code-block:: console $ gitlab project-issue list --project-id 2 Delete a snippet (id 3): .. code-block:: console $ gitlab project-snippet delete --id 3 --project-id 2 Update a snippet: .. code-block:: console $ gitlab project-snippet update --id 4 --project-id 2 \ --code "My New Code" Create a snippet: .. code-block:: console $ 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): .. code-block:: console $ 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): .. code-block:: console $ gitlab project create --name user_project1 --sudo username List values are comma-separated: .. code-block:: console $ gitlab issue list --labels foo,bar Reading values from files ------------------------- 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: .. code-block:: console $ 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