GitHub - fgouteroux/python-gitlab: Python wrapper for the GitLab API

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

It supports the v3 api of GitLab.

A CLI tool is also provided (called gitlab).

Installation

Requirements

python-gitlab depends on:

Install with pip

pip install python-gitlab

State

python-gitlab is considered stable.

Bug reports

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

Documentation

See http://python-gitlab.readthedocs.org/en/stable/

Code snippet

# See https://github.com/gitlabhq/gitlabhq/tree/master/doc/api for the source.
from gitlab import Gitlab

# Register a connection to a gitlab instance, using its URL and a user private
# token
gl = Gitlab('http://192.168.123.107', 'JVNSESs8EwWRx5yDxM5q')
# Connect to get the current user
gl.auth()
# Print the user informations
print(gl.user)

# Get a list of projects
for p in gl.projects.list():
    print(p.name)
    # get associated issues
    issues = p.issues.list()
    for issue in issues:
        closed = 0 if not issue.closed else 1
        print("  %d => %s (closed: %d)" % (issue.id, issue.title, closed))
        # and close them all
        issue.state_event = "close"
        issue.save()

# Get the first 10 groups (pagination)
for g in gl.groups.list(page=1, per_page=10):
    print(g)

# To use pagination and retrieve all the items
for g in gl.groups.list(all=True):
    print(g)

# Create a new project (as another_user)
p = gl.project.create({'name': 'myCoolProject', 'wiki_enabled': False},
                      sudo="another_user")
print(p)

Command line use

To use the command line tool, you need to define which GitLab server(s) can be accessed. This can be done in 2 files:

/etc/python-gitlab.cfg
~/.python-gitlab.cfg

Here's an example of the syntax:

[global]
# required setting
default = local

# optional settings
ssl_verify = true
timeout = 5

[local]
url = http://10.0.3.2:8080
# get the private token from the gitlab web interface
private_token = vTbFeqJYCY3sibBP7BZM

[remote]
url = https://some.whe.re
private_token = thisisaprivatetoken
ssl_verify = false

The [global] section defines which server is accessed by default. Each other section defines how to access a server. Only private token authentication is supported (not user/password).

The ssl_verify option defines if the server SSL certificate should be validated (use false for self signed certificates, only useful with https).

The timeout option defines after how many seconds a request to the Gitlab server should be abandonned.

You can choose a different server than the default one at run time:

gitlab --gitlab remote [command]

gitlab always requires 2 mandatory arguments.

The first argument is the object type on which the program will act, the second one is the action:

Get help with:

# global help
gitlab --help

# object help
gitlab project --help

Some examples:

# list all the projects:
gitlab project list

# limit to 5 items per request, display the 1st page only
gitlab project list --page 1 --per-page 5

# get a specific project (id 2):
gitlab project get --id 2

# get a list of snippets for this project:
gitlab project-issue list --project-id 2

# delete a Snippet (id 3):
gitlab project-snippet delete --id 3 --project-id 2

# update a Snippet:
gitlab project-snippet update --id 4 --project-id 2 --code "My New Code"

# create a Snippet:
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"