Repository files navigation

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).

python-gitlab depends on:

• python-requests

pip install python-gitlab

docker build -t python-gitlab:TAG .

docker run -it --rm -e GITLAB_PRIVATE_TOKEN=<your token> -v /path/to/python-gitlab.cfg:/python-gitlab.cfg python-gitlab <command> ...

or run it directly from the upstream image:

docker run -it --rm -e GITLAB_PRIVATE_TOKEN=<your token> -v /path/to/python-gitlab.cfg:/python-gitlab.cfg registry.gitlab.com/python-gitlab/python-gitlab:latest <command> ...

To change the GitLab URL, use -e GITLAB_URL=<your url>

Bring your own config file:docker run -it --rm -v /path/to/python-gitlab.cfg:/python-gitlab.cfg -e GITLAB_CFG=/python-gitlab.cfg python-gitlab <command> ...

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

There is agitter community chatavailable athttps://gitter.im/python-gitlab/Lobby

The full documentation for CLI and API is available onreadthedocs.

You can build the documentation usingsphinx:

pip install sphinxpython setup.py build_sphinx

You can contribute to the project in multiple ways:

• Write documentation
• Implement features
• Fix bugs
• Add unit and functional tests
• Everything else you can think of

Before contributing, please make sure you havepre-commitinstalled and configured. This will help automate adhering to code style and commitmessage guidelines described below:

cd python-gitlab/pip3 install --user pre-commitpre-commit install -t pre-commit -t commit-msg --install-hooks

Please provide your patches as GitHub pull requests. Thanks!

We enforce commit messages to be formatted using theconventional-changelog.This leads to more readable messages that are easy to follow when looking through the project history.

We use black as code formatter, so you'll need to format your changes using theblack code formatter. Pre-commit hooks will validate/format your codewhen committing. You can then stage any changesblack added if the commit failed.

To format your code according to our guidelines before committing, run:

cd python-gitlab/pip3 install --user blackblack.

Before submitting a pull request make sure that the tests and lint checks still succeed withyour change. Unit tests and functional tests run in GitHub Actions andpassing checks are mandatory to get merge requests accepted.

Please write new unit tests with pytest and usingresponses.An example can be found intests/unit/objects/test_runner.py

You need to installtox (pip3 install tox) to run tests and lint checks locally:

# run unit tests using your installed python3, and all lint checks:tox -s# run unit tests for all supported python3 versions, and all lint checks:tox# run tests in one environment only:tox -epy38# build the documentation, the result will be generated in# build/sphinx/html/tox -edocs

Integration tests run against a running gitlab instance, using a dockercontainer. You need to have docker installed on the test machine, and your usermust have the correct permissions to talk to the docker daemon.

To run these tests:

# run the CLI tests:tox -e cli_func_v4# run the python API tests:tox -e py_func_v4

When developing tests it can be a little frustrating to wait for GitLab to spinup every run. To prevent the containers from being cleaned up afterwards, pass--keep-containers to pytest, i.e.:

tox -e py_func_v4 -- --keep-containers

If you then wish to test against a clean slate, you may perform a manual cleanup of the containers by running:

docker-compose -f tests/functional/fixtures/docker-compose.yml -p pytest-python-gitlab down -v

By default, the tests run against the latest version of thegitlab/gitlab-ceimage. You can override both the image and tag by providing either theGITLAB_IMAGE orGITLAB_TAG environment variables.

This way you can run tests against different versions, such asnightly forfeatures in an upcoming release, or an older release (e.g.12.8.0-ce.0).The tag must match an exact tag on Docker Hub:

# run tests against `nightly` or specific tagGITLAB_TAG=nightly tox -e py_func_v4GITLAB_TAG=12.8.0-ce.0 tox -e py_func_v4# run tests against the latest gitlab EE imageGITLAB_IMAGE=gitlab/gitlab-ee tox -e py_func_v4

A freshly configured gitlab container will be available athttp://localhost:8080 (loginroot / password5iveL!fe). A configurationfor python-gitlab will be written in/tmp/python-gitlab.cfg.

To cleanup the environment delete the container:

docker rm -f gitlab-testdocker rm -f gitlab-runner-test

A release is automatically published once a month on the 28th if any commits mergedto the main branch contain commit message types that signal a semantic version bump(fix,feat,BREAKING CHANGE:).

Additionally, the release workflow can be run manually by maintainers to publish urgentfixes, either on GitHub or using thegh CLI withgh workflow run release.yml.

Note: As a maintainer, this means you should carefully review commit messagesused by contributors in their pull requests. If scopes such asfix andfeatare applied to trivial commits not relevant to end users, it's best to squash theirpull requests and summarize the addition in a single conventional commit.This avoids triggering incorrect version bumps and releases without functional changes.

The release workflow usespython-semantic-release and does the following:

• Bumps the version in__version__.py and adds an entry inCHANGELOG.md,
• Commits and tags the changes, then pushes to the main branch as thegithub-actions user,
• Creates a release from the tag and adds the changelog entry to the release notes,
• Uploads the package as assets to the GitHub release,
• Uploads the package to PyPI usingPYPI_TOKEN (configured as a secret).