diff options
Diffstat (limited to 'docs/cli-usage.rst')
| -rw-r--r-- | docs/cli-usage.rst | 399 |
1 files changed, 399 insertions, 0 deletions
diff --git a/docs/cli-usage.rst b/docs/cli-usage.rst new file mode 100644 index 0000000..10fd73a --- /dev/null +++ b/docs/cli-usage.rst @@ -0,0 +1,399 @@ +#################### +``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 3 configuration files by default: + +``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. + +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 = 4 + + [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`` + - ``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. + +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``, ``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. + +.. 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`_pat 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`_job-token to learn how to obtain a token. + * - ``api_version`` + - GitLab API version to use. Only ``4`` is available since 1.5.0. + * - ``http_username`` + - Username for optional HTTP authentication + * - ``http_password`` + - Password for optional HTTP authentication + +.. _pat: https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html +.. _job-token: https://docs.gitlab.com/ce/api/jobs.html#get-job-artifacts + +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 <https://pypi.org/project/PyYAML/>`_ is required to use the yaml output option. + You need to install it explicitly using ``pip install python-gitlab[yaml]`` + +``--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 +======== + + **Notice:** + + For a complete list of objects and actions available, see :doc:`/cli-objects`. + +List the projects (paginated): + +.. code-block:: console + + $ gitlab project list + +List all the projects: + +.. code-block:: console + + $ gitlab project list --all + +List all projects of a group: + +.. code-block:: console + + $ gitlab group-project list --all --group-id 1 + +List all projects of a group and its subgroups: + +.. code-block:: console + + $ gitlab group-project list --all --include-subgroups true --group-id 1 + +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 + +Create a deploy token for a project: + +.. code-block:: console + + $ gitlab -v project-deploy-token create --project-id 2 \ + --name bar --username root --expires-at "2021-09-09" --scopes "read_repository" + +List deploy tokens for a group: + +.. code-block:: console + + $ gitlab -v group-deploy-token list --group-id 3 + +List packages for a project: + +.. code-block:: console + + $ gitlab -v project-package list --project-id 3 + +List packages for a group: + +.. code-block:: console + + $ gitlab -v group-package list --group-id 3 + +Get a specific project package by id: + +.. code-block:: console + + $ gitlab -v project-package get --id 1 --project-id 3 + +Delete a specific project package by id: + +.. code-block:: console + + $ gitlab -v project-package delete --id 1 --project-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" + +Get a specific project commit by its SHA id: + +.. code-block:: console + + $ gitlab project-commit get --project-id 2 --id a43290c + +Get the signature (e.g. GPG or x509) of a signed commit: + +.. code-block:: console + + $ gitlab project-commit signature --project-id 2 --id a43290c + +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 + +Enabling shell autocompletion +============================ + +To get autocompletion, you'll need to install the package with the extra +"autocompletion": + +.. code-block:: console + + pip install python_gitlab[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. + +Bash +---- + +.. code-block:: console + + eval "$(register-python-argcomplete gitlab)" + +tcsh +---- + +.. code-block:: console + + eval `register-python-argcomplete --shell tcsh gitlab` + +fish +---- + +.. code-block:: console + + register-python-argcomplete --shell fish gitlab | . + +Zsh +--- + +.. warning:: + + Zsh autocompletion support is broken right now in the argcomplete python + package. Perhaps it will be fixed in a future release of argcomplete at + which point the following instructions will enable autocompletion in zsh. + +To activate completions for zsh you need to have bashcompinit enabled in zsh: + +.. code-block:: console + + autoload -U bashcompinit + bashcompinit + +Afterwards you can enable completion for gitlab: + +.. code-block:: console + + eval "$(register-python-argcomplete gitlab)" |