# python-gitlab

`python-gitlab` is a Python package providing access to the GitLab server API.

It supports the v4 API of GitLab, and provides a CLI tool (`gitlab`).

## Features

`python-gitlab` enables you to:

- write Pythonic code to manage your GitLab resources.

- pass arbitrary parameters to the GitLab API. Simply follow GitLab’s docs on what parameters are available.

- access arbitrary endpoints as soon as they are available on GitLab, by using lower-level API methods.

- use persistent requests sessions for authentication, proxy and certificate handling.

- handle smart retries on network and server errors, with rate-limit handling.

- flexible handling of paginated responses, including lazy iterators.

- automatically URL-encode paths and parameters where needed.

- automatically convert some complex data structures to API attribute types

- merge configuration from config files, environment variables and arguments.

## Installation

As of 4.0.0, `python-gitlab` is compatible with Python 3.8+.

Use `pip` to install the latest stable version of `python-gitlab`:

    $ pip install --upgrade python-gitlab

The current development version is available on both GitHub.com and GitLab.com, and can be installed directly from the git repository:

    $ pip install git+https://github.com/python-gitlab/python-gitlab.git

From GitLab:

    $ pip install git+https://gitlab.com/python-gitlab/python-gitlab.git

## Using the docker images

`python-gitlab` provides Docker images in two flavors, based on the Alpine and Debian slim python base images. The default tag is `alpine`, but you can explicitly use the alias (see below).

The alpine image is smaller, but you may want to use the Debian-based slim tag (currently based on `-slim-bullseye`) if you are running into issues or need a more complete environment with a bash shell, such as in CI jobs.

The images are published on the GitLab registry, for example:

- `registry.gitlab.com/python-gitlab/python-gitlab:latest` (latest, alpine alias)

- `registry.gitlab.com/python-gitlab/python-gitlab:alpine` (latest alpine)

- `registry.gitlab.com/python-gitlab/python-gitlab:slim-bullseye` (latest slim-bullseye)

- `registry.gitlab.com/python-gitlab/python-gitlab:v3.2.0` (alpine alias)

- `registry.gitlab.com/python-gitlab/python-gitlab:v3.2.0-alpine`

- `registry.gitlab.com/python-gitlab/python-gitlab:v3.2.0-slim-bullseye`

You can run the Docker image directly from the GitLab registry:

    $ docker run -it --rm registry.gitlab.com/python-gitlab/python-gitlab:latest <command> ...

For example, to get a project on GitLab.com (without authentication):

    $ docker run -it --rm registry.gitlab.com/python-gitlab/python-gitlab:latest project get --id gitlab-org/gitlab

You can also mount your own config file:

    $ docker run -it --rm -v /path/to/python-gitlab.cfg:/etc/python-gitlab.cfg registry.gitlab.com/python-gitlab/python-gitlab:latest <command> ...

### Building the image

To build your own image from this repository, run:

    $ docker build -t python-gitlab:latest .

Run your own image:

    $ docker run -it --rm python-gitlab:latest <command> ...

Build a Debian slim-based image:

    $ docker build -t python-gitlab:latest --build-arg PYTHON_FLAVOR=slim-bullseye .

## Bug reports

Please report bugs and feature requests at https://github.com/python-gitlab/python-gitlab/issues.

## Gitter Community Chat

We have a gitter community chat available at https://gitter.im/python-gitlab/Lobby, which you can also directly access via the Open Chat button below.

If you have a simple question, the community might be able to help already, without you opening an issue. If you regularly use python-gitlab, we also encourage you to join and participate. You might discover new ideas and use cases yourself!

## Documentation

The full documentation for CLI and API is available on readthedocs.

### Build the docs

We use `tox` to manage our environment and build the documentation:

    pip install tox
    tox -e docs

## Contributing

For guidelines for contributing to `python-gitlab`, refer to CONTRIBUTING.rst.

# Indices and tables

- Index

- Module Index

- Search Page