diff options
Diffstat (limited to 'docs/cli.rst')
| -rw-r--r-- | docs/cli.rst | 395 |
1 files changed, 0 insertions, 395 deletions
diff --git a/docs/cli.rst b/docs/cli.rst deleted file mode 100644 index 95f7062..0000000 --- a/docs/cli.rst +++ /dev/null @@ -1,395 +0,0 @@ -#################### -``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 -======== - -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)" |