Getting started with the API

The gitlab package provides 3 base types:

  • gitlab.Gitlab is the primary class, handling the HTTP requests. It holds the GitLab URL and authentication information.
  • gitlab.GitlabObject is the base class for all the GitLab objects. These objects provide an abstraction for GitLab resources (projects, groups, and so on).
  • gitlab.BaseManager is the base class for objects managers, providing the API to manipulate the resources and their attributes.

gitlab.Gitlab class

To connect to a GitLab server, create a gitlab.Gitlab object:

import gitlab

# private token authentication
gl = gitlab.Gitlab('', 'JVNSESs8EwWRx5yDxM5q')

# or username/password authentication
gl = gitlab.Gitlab('', email='jdoe', password='s3cr3t')

# make an API request to create the gl.user object. This is mandatory if you
# use the username/password authentication.

You can also use configuration files to create gitlab.Gitlab objects:

gl = gitlab.Gitlab.from_config('somewhere', ['/tmp/gl.cfg'])

See the Configuration section for more information about configuration files.

GitLab v4 support

python-gitlab uses the v3 GitLab API by default. Use the api_version parameter to switch to v4:

import gitlab

gl = gitlab.Gitlab('', 'JVNSESs8EwWRx5yDxM5q', api_version=4)


The v4 support is experimental.


The gitlab.Gitlab class provides managers to access the GitLab resources. Each manager provides a set of methods to act on the resources. The available methods depend on the resource type. Resources are represented as gitlab.GitlabObject-derived objects.


# list all the projects
projects = gl.projects.list()
for project in projects:

# get the group with id == 2
group = gl.groups.get(2)
for group in groups:

# create a new user
user_data = {'email': '', 'username': 'jen', 'name': 'Jen'}
user = gl.users.create(user_data)

The attributes of objects are defined upon object creation, and depend on the GitLab API itself. To list the available information associated with an object use the python introspection tools:

project = gl.projects.get(1)
# or

Some gitlab.GitlabObject classes also provide managers to access related GitLab resources:

# list the issues for a project
project = gl.projects.get(1)
issues = project.issues.list()

Gitlab Objects

You can update or delete an object when it exists as a GitlabObject object:

# update the attributes of a resource
project = gl.projects.get(1)
project.wall_enabled = False
# don't forget to apply your changes on the server:

# delete the resource

Some GitlabObject-derived classes provide additional methods, allowing more actions on the GitLab resources. For example:

# star a git repository
project = gl.projects.get(1)


If you have the administrator status, you can use sudo to act as another user. For example:

p = gl.projects.create({'name': 'awesome_project'}, sudo='user1')