Getting started with the API#

python-gitlab only supports GitLab API v4.

`gitlab.Gitlab` class#

To connect to GitLab.com or another GitLab instance, create a gitlab.Gitlab object:

import gitlab

# anonymous read-only access for public resources (GitLab.com)
gl = gitlab.Gitlab()

# anonymous read-only access for public resources (self-hosted GitLab instance)
gl = gitlab.Gitlab('https://gitlab.example.com')

# private token or personal token authentication (GitLab.com)
gl = gitlab.Gitlab(private_token='JVNSESs8EwWRx5yDxM5q')

# private token or personal token authentication (self-hosted GitLab instance)
gl = gitlab.Gitlab(url='https://gitlab.example.com', private_token='JVNSESs8EwWRx5yDxM5q')

# oauth token authentication
gl = gitlab.Gitlab('https://gitlab.example.com', oauth_token='my_long_token_here')

# job token authentication (to be used in CI)
# bear in mind the limitations of the API endpoints it supports:
# https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html
import os
gl = gitlab.Gitlab('https://gitlab.example.com', job_token=os.environ['CI_JOB_TOKEN'])

# Define your own custom user agent for requests
gl = gitlab.Gitlab('https://gitlab.example.com', user_agent='my-package/1.0.0')

# make an API request to create the gl.user object. This is mandatory if you
# use the username/password authentication - not required for token authentication,
# and will not work with job tokens.
gl.auth()

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.

Warning

Note that a url that results in 301/302 redirects will raise an error, so it is highly recommended to use the final destination in the url field. For example, if the GitLab server you are using redirects requests from http to https, make sure to use the https:// protocol in the URL definition.

A URL that redirects using 301/302 (rather than 307/308) will most likely cause malformed POST and PUT requests.

python-gitlab will therefore raise a RedirectionError when it encounters a redirect which it believes will cause such an error, to avoid confusion between successful GET and failing POST/PUT requests on the same instance.

Note on password authentication#

The /session API endpoint used for username/password authentication has been removed from GitLab in version 10.2, and is not available on gitlab.com anymore. Personal token authentication is the preferred authentication method.

If you need username/password authentication, you can use cookie-based authentication. You can use the web UI form to authenticate, retrieve cookies, and then use a custom requests.Session object to connect to the GitLab API. The following code snippet demonstrates how to automate this: https://gist.github.com/gpocentek/bd4c3fbf8a6ce226ebddc4aad6b46c0a.

See issue 380 for a detailed discussion.

Managers#

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.

Examples:

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

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

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

You can list the mandatory and optional attributes for object creation and update with the manager’s get_create_attrs() and get_update_attrs() methods. They return 2 tuples, the first one is the list of mandatory attributes, the second one is the list of optional attribute:

# v4 only
print(gl.projects.get_create_attrs())
(('name',), ('path', 'namespace_id', ...))

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 attributes attribute:

project = gl.projects.get(1)
print(project.attributes)

Some objects also provide managers to access related GitLab resources:

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

python-gitlab allows to send any data to the GitLab server when making queries. In case of invalid or missing arguments python-gitlab will raise an exception with the GitLab server error message:

>>> gl.projects.list(sort='invalid value')
...
GitlabListError: 400: sort does not have a valid value

You can use the query_parameters argument to send arguments that would conflict with python or python-gitlab when using them as kwargs:

gl.user_activities.list(from='2019-01-01')  ## invalid

gl.user_activities.list(query_parameters={'from': '2019-01-01'})  # OK

Gitlab Objects#

You can update or delete a remote object when it exists locally:

# 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:
project.save()

# delete the resource
project.delete()

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

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

You can print a Gitlab Object. For example:

project = gl.projects.get(1)
print(project)

# Or in a prettier format.
project.pprint()

# Or explicitly via `pformat()`. This is equivalent to the above.
print(project.pformat())

You can also extend the object if the parameter isn’t explicitly listed. For example, if you want to update a field that has been newly introduced to the Gitlab API, setting the value on the object is accepted:

issues = project.issues.list(state='opened')
for issue in issues:
   issue.my_super_awesome_feature_flag = "random_value"
   issue.save()

Base types#

The gitlab package provides some base types.

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

Lazy objects#

To avoid useless API calls to the server you can create lazy objects. These objects are created locally using a known ID, and give access to other managers and methods.

The following example will only make one API call to the GitLab server to star a project (the previous example used 2 API calls):

# star a git repository
project = gl.projects.get(1, lazy=True)  # no API call
project.star()  # API call

Pagination#

You can use pagination to iterate over long lists. All the Gitlab objects listing methods support the page and per_page parameters:

ten_first_groups = gl.groups.list(page=1, per_page=10)

Warning

The first page is page 1, not page 0.

By default GitLab does not return the complete list of items. Use the all parameter to get all the items when using listing methods:

all_groups = gl.groups.list(all=True)
all_owned_projects = gl.projects.list(owned=True, all=True)

You can define the per_page value globally to avoid passing it to every list() method call:

gl = gitlab.Gitlab(url, token, per_page=50)

Gitlab allows to also use keyset pagination. You can supply it to your project listing, but you can also do so globally. Be aware that GitLab then also requires you to only use supported order options. At the time of writing, only order_by="id" works.

gl = gitlab.Gitlab(url, token, pagination="keyset", order_by="id", per_page=100)
gl.projects.list()

Reference: https://docs.gitlab.com/ce/api/README.html#keyset-based-pagination

list() methods can also return a generator object which will handle the next calls to the API when required. This is the recommended way to iterate through a large number of items:

items = gl.groups.list(as_list=False)
for item in items:
    print(item.attributes)

The generator exposes extra listing information as received from the server:

current_page: current page number (first page is 1)
prev_page: if None the current page is the first one
next_page: if None the current page is the last one
per_page: number of items per page
total_pages: total number of pages available. This may be a None value.
total: total number of items in the list. This may be a None value.

Note

For performance reasons, if a query returns more than 10,000 records, GitLab does not return the total_pages or total headers. In this case, total_pages and total will have a value of None.

For more information see: https://docs.gitlab.com/ee/user/gitlab_com/index.html#pagination-response-headers

Sudo#

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

Advanced HTTP configuration#

python-gitlab relies on requests Session objects to perform all the HTTP requests to the Gitlab servers.

You can provide your own Session object with custom configuration when you create a Gitlab object.

Context manager#

You can use Gitlab objects as context managers. This makes sure that the requests.Session object associated with a Gitlab instance is always properly closed when you exit a with block:

with gitlab.Gitlab(host, token) as gl:
    gl.projects.list()

Warning

The context manager will also close the custom Session object you might have used to build the Gitlab instance.

Proxy configuration#

The following sample illustrates how to define a proxy configuration when using python-gitlab:

import gitlab
import requests

session = requests.Session()
session.proxies = {
    'https': os.environ.get('https_proxy'),
    'http': os.environ.get('http_proxy'),
}
gl = gitlab.gitlab(url, token, api_version=4, session=session)

Reference: https://2.python-requests.org/en/master/user/advanced/#proxies

SSL certificate verification#

python-gitlab relies on the CA certificate bundle in the certifi package that comes with the requests library.

If you need python-gitlab to use your system CA store instead, you can provide the path to the CA bundle in the REQUESTS_CA_BUNDLE environment variable.

Reference: https://2.python-requests.org/en/master/user/advanced/#ssl-cert-verification

Client side certificate#

The following sample illustrates how to use a client-side certificate:

import gitlab
import requests

session = requests.Session()
session.cert = ('/path/to/client.cert', '/path/to/client.key')
gl = gitlab.gitlab(url, token, api_version=4, session=session)

Reference: https://2.python-requests.org/en/master/user/advanced/#client-side-certificates

Rate limits#

python-gitlab obeys the rate limit of the GitLab server by default. On receiving a 429 response (Too Many Requests), python-gitlab sleeps for the amount of time in the Retry-After header that GitLab sends back. If GitLab does not return a response with the Retry-After header, python-gitlab will perform an exponential backoff.

If you don’t want to wait, you can disable the rate-limiting feature, by supplying the obey_rate_limit argument.

import gitlab
import requests

gl = gitlab.gitlab(url, token, api_version=4)
gl.projects.list(all=True, obey_rate_limit=False)

If you do not disable the rate-limiting feature, you can supply a custom value for max_retries; by default, this is set to 10. To retry without bound when throttled, you can set this parameter to -1. This parameter is ignored if obey_rate_limit is set to False.

import gitlab
import requests

gl = gitlab.gitlab(url, token, api_version=4)
gl.projects.list(all=True, max_retries=12)

Warning

You will get an Exception, if you then go over the rate limit of your GitLab instance.

Transient errors#

GitLab server can sometimes return a transient HTTP error. python-gitlab can automatically retry in such case, when retry_transient_errors argument is set to True. When enabled, HTTP error codes 500 (Internal Server Error), 502 (502 Bad Gateway), 503 (Service Unavailable), and 504 (Gateway Timeout) are retried. It will retry until reaching the max_retries value. By default, retry_transient_errors is set to False and an exception is raised for these errors.

import gitlab
import requests

gl = gitlab.gitlab(url, token, api_version=4)
gl.projects.list(all=True, retry_transient_errors=True)

The default retry_transient_errors can also be set on the Gitlab object and overridden by individual API calls.

import gitlab
import requests
gl = gitlab.gitlab(url, token, api_version=4, retry_transient_errors=True)
gl.projects.list(all=True)                               # retries due to default value
gl.projects.list(all=True, retry_transient_errors=False) # does not retry

Timeout#

python-gitlab will by default use the timeout option from it’s configuration for all requests. This is passed downwards to the requests module at the time of making the HTTP request. However if you would like to override the global timeout parameter for a particular call, you can provide the timeout parameter to that API invocation:

import gitlab

gl = gitlab.gitlab(url, token, api_version=4)
gl.projects.import_github(ACCESS_TOKEN, 123456, "root", timeout=120.0)

Attributes in updated objects#

When methods manipulate an existing object, such as with refresh() and save(), the object will only have attributes that were returned by the server. In some cases, such as when the initial request fetches attributes that are needed later for additional processing, this may not be desired:

project = gl.projects.get(1, statistics=True)
project.statistics

project.refresh()
project.statistics # AttributeError

To avoid this, either copy the object/attributes before calling refresh()/save() or subsequently perform another get() call as needed, to fetch the attributes you want.

Getting started with the API#

gitlab.Gitlab class#

Note on password authentication#

Managers#

Gitlab Objects#

Base types#

Lazy objects#

Pagination#

Sudo#

Advanced HTTP configuration#

Context manager#

Proxy configuration#

SSL certificate verification#

Client side certificate#

Rate limits#

Transient errors#

Timeout#

Attributes in updated objects#

`gitlab.Gitlab` class#