API reference (`gitlab` package)¶

Module contents¶

Wrapper for the GitLab API.

class gitlab.Gitlab(url: str | None = None, private_token: str | None = None, oauth_token: str | None = None, job_token: str | None = None, ssl_verify: bool | str = True, http_username: str | None = None, http_password: str | None = None, timeout: float | None = None, api_version: str = '4', per_page: int | None = None, pagination: str | None = None, order_by: str | None = None, user_agent: str = 'python-gitlab/4.4.0', retry_transient_errors: bool = False, keep_base_url: bool = False, **kwargs: Any)

Bases: object

Represents a GitLab server connection.

Parameters:

url (str | None) – The URL of the GitLab server (defaults to https://gitlab.com).
private_token (str | None) – The user private token
oauth_token (str | None) – An oauth token
job_token (str | None) – A CI job token
ssl_verify (bool | str) – Whether SSL certificates should be validated. If the value is a string, it is the path to a CA file used for certificate validation.
timeout (float | None) – Timeout to use for requests to the GitLab server.
http_username (str | None) – Username for HTTP authentication
http_password (str | None) – Password for HTTP authentication
api_version (str) – Gitlab API version to use (support for 4 only)
pagination (str | None) – Can be set to ‘keyset’ to use keyset pagination
order_by (str | None) – Set order_by globally
user_agent (str) – A custom user agent to use for making HTTP requests.
retry_transient_errors (bool) – Whether to retry after 500, 502, 503, 504 or 52x responses. Defaults to False.
keep_base_url (bool) – keep user-provided base URL for pagination if it differs from response headers
session (requests.Session) – HTTP Requests Session
backend (RequestsBackend) – Backend that will be used to make http requests
per_page (int | None)
kwargs (Any)

property api_url: str: The computed API base URL.

property api_version: str: The API version used (4 only).

appearance: See ApplicationAppearanceManager

applications: See ApplicationManager

audit_events: See AuditEventManager

auth() → None

Performs an authentication using private token. Warns the user if a potentially misconfigured URL is detected on the client or server side.

The user attribute will hold a gitlab.objects.CurrentUser object on success.

Return type:: None

broadcastmessages: See BroadcastMessageManager

bulk_import_entities: See BulkImportAllEntityManager

bulk_imports: See BulkImportManager

ci_lint: See CiLintManager

deploykeys: See DeployKeyManager

deploytokens: See DeployTokenManager

dockerfiles: See DockerfileManager

enable_debug(mask_credentials: bool = True) → None

Parameters:: mask_credentials (bool)
Return type:: None

events: See EventManager

features: See FeatureManager

classmethod from_config(gitlab_id: str | None = None, config_files: List[str] | None = None, **kwargs: Any) → Gitlab

Create a Gitlab connection from configuration files.

Parameters:

gitlab_id (str | None) – ID of the configuration section.
list[str] (config_files) – List of paths to configuration files.
config_files (List[str] | None)
kwargs (Any)

Return type:

Gitlab

kwargs:: session requests.Session: Custom requests Session

Returns:

A Gitlab connection.

Raises:

gitlab.config.GitlabDataError – If the configuration is not correct.

Parameters:

gitlab_id (str | None)
config_files (List[str] | None)
kwargs (Any)

Return type:

Gitlab

geonodes: See GeoNodeManager

get_license(**kwargs: Any) → Dict[str, str | Dict[str, str]]

Retrieve information about the current license.

Parameters:

**kwargs (Any) – Extra options to send to the server (e.g. sudo)

Raises:

GitlabAuthenticationError – If authentication is not correct
GitlabGetError – If the server cannot perform the request

Returns:

The current license information

Return type:

Dict[str, str | Dict[str, str]]

gitignores: See GitignoreManager

gitlabciymls: See GitlabciymlManager

groups: See GroupManager

headers: Headers that will be used in request to GitLab

hooks: See HookManager

http_delete(path: str, **kwargs: Any) → Response

Make a DELETE request to the Gitlab server.

Parameters:

path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

Returns:

The requests object.

Raises:

GitlabHttpError – When the return code is not 2xx

Return type:

Response

http_get(path: str, query_data: Dict[str, Any] | None = None, streamed: bool = False, raw: bool = False, **kwargs: Any) → Dict[str, Any] | Response

Make a GET request to the Gitlab server.

Parameters:

path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
query_data (Dict[str, Any] | None) – Data to send as query parameters
streamed (bool) – Whether the data should be streamed
raw (bool) – If True do not try to parse the output as json
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

Returns:

A requests result object is streamed is True or the content type is not json. The parsed json data otherwise.

Raises:

GitlabHttpError – When the return code is not 2xx
GitlabParsingError – If the json data could not be parsed

Return type:

Dict[str, Any] | Response

http_head(path: str, query_data: Dict[str, Any] | None = None, **kwargs: Any) → CaseInsensitiveDict[Any]

Make a HEAD request to the Gitlab server.

Parameters:

path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
query_data (Dict[str, Any] | None) – Data to send as query parameters
**kwargs (Any) – Extra options to send to the server (e.g. sudo, page, per_page)

Returns:

A requests.header object

Raises:

GitlabHttpError – When the return code is not 2xx

Return type:

CaseInsensitiveDict[Any]

http_list(path: str, query_data: Dict[str, Any] | None = None, *, iterator: bool | None = None, **kwargs: Any) → GitlabList | List[Dict[str, Any]]

Make a GET request to the Gitlab server for list-oriented queries.

Parameters:

path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projects’)
query_data (Dict[str, Any] | None) – Data to send as query parameters
iterator (bool | None) – Indicate if should return a generator (True)
**kwargs (Any) – Extra options to send to the server (e.g. sudo, page, per_page)

Returns:

A list of the objects returned by the server. If iterator is True and no pagination-related arguments (page, per_page, get_all) are defined then a GitlabList object (generator) is returned instead. This object will make API calls when needed to fetch the next items from the server.

Raises:

GitlabHttpError – When the return code is not 2xx
GitlabParsingError – If the json data could not be parsed

Return type:

GitlabList | List[Dict[str, Any]]

http_patch(path: str, *, query_data: Dict[str, Any] | None = None, post_data: Dict[str, Any] | bytes | None = None, raw: bool = False, **kwargs: Any) → Dict[str, Any] | Response

Make a PATCH request to the Gitlab server.

Parameters:

path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
query_data (Dict[str, Any] | None) – Data to send as query parameters
post_data (Dict[str, Any] | bytes | None) – Data to send in the body (will be converted to json by default)
raw (bool) – If True, do not convert post_data to json
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

Returns:

The parsed json returned by the server.

Raises:

GitlabHttpError – When the return code is not 2xx
GitlabParsingError – If the json data could not be parsed

Return type:

Dict[str, Any] | Response

http_post(path: str, query_data: Dict[str, Any] | None = None, post_data: Dict[str, Any] | None = None, raw: bool = False, files: Dict[str, Any] | None = None, **kwargs: Any) → Dict[str, Any] | Response

Make a POST request to the Gitlab server.

Parameters:

path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
query_data (Dict[str, Any] | None) – Data to send as query parameters
post_data (Dict[str, Any] | None) – Data to send in the body (will be converted to json by default)
raw (bool) – If True, do not convert post_data to json
files (Dict[str, Any] | None) – The files to send to the server
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

Returns:

The parsed json returned by the server if json is return, else the raw content

Raises:

GitlabHttpError – When the return code is not 2xx
GitlabParsingError – If the json data could not be parsed

Return type:

Dict[str, Any] | Response

Make a PUT request to the Gitlab server.

Parameters:

path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
query_data (Dict[str, Any] | None) – Data to send as query parameters
post_data (Dict[str, Any] | bytes | BinaryIO | None) – Data to send in the body (will be converted to json by default)
raw (bool) – If True, do not convert post_data to json
files (Dict[str, Any] | None) – The files to send to the server
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

Returns:

The parsed json returned by the server.

Raises:

GitlabHttpError – When the return code is not 2xx
GitlabParsingError – If the json data could not be parsed

Return type:

Dict[str, Any] | Response

http_request(verb: str, path: str, query_data: Dict[str, Any] | None = None, post_data: Dict[str, Any] | bytes | BinaryIO | None = None, raw: bool = False, streamed: bool = False, files: Dict[str, Any] | None = None, timeout: float | None = None, obey_rate_limit: bool = True, retry_transient_errors: bool | None = None, max_retries: int = 10, **kwargs: Any) → Response

Make an HTTP request to the Gitlab server.

Parameters:

verb (str) – The HTTP method to call (‘get’, ‘post’, ‘put’, ‘delete’)
path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
query_data (Dict[str, Any] | None) – Data to send as query parameters
post_data (Dict[str, Any] | bytes | BinaryIO | None) – Data to send in the body (will be converted to json by default)
raw (bool) – If True, do not convert post_data to json
streamed (bool) – Whether the data should be streamed
files (Dict[str, Any] | None) – The files to send to the server
timeout (float | None) – The timeout, in seconds, for the request
obey_rate_limit (bool) – Whether to obey 429 Too Many Request responses. Defaults to True.
retry_transient_errors (bool | None) – Whether to retry after 500, 502, 503, 504 or 52x responses. Defaults to False.
max_retries (int) – Max retries after 429 or transient errors, set to -1 to retry forever. Defaults to 10.
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

Returns:

A requests result object.

Raises:

GitlabHttpError – When the return code is not 2xx

Return type:

Response

issues: See IssueManager

issues_statistics: See IssuesStatisticsManager

keys: See KeyManager

ldapgroups: See LDAPGroupManager

licenses: See LicenseManager

markdown(text: str, gfm: bool = False, project: str | None = None, **kwargs: Any) → str

Render an arbitrary Markdown document.

Parameters:

text (str) – The markdown text to render
gfm (bool) – Render text using GitLab Flavored Markdown. Default is False
project (str | None) – Full path of a project used a context when gfm is True
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

Raises:

GitlabAuthenticationError – If authentication is not correct
GitlabMarkdownError – If the server cannot perform the request

Returns:

The HTML rendering of the markdown text.

Return type:

str

classmethod merge_config(options: Dict[str, Any], gitlab_id: str | None = None, config_files: List[str] | None = None) → Gitlab

Create a Gitlab connection by merging configuration with the following precedence:

Explicitly provided CLI arguments,
Environment variables,
Configuration files:
1. explicitly defined config files:
  
  via the –config-file CLI argument,
  
  via the PYTHON_GITLAB_CFG environment variable,
2. user-specific config file,
3. system-level config file,
Environment variables always present in CI (CI_SERVER_URL, CI_JOB_TOKEN).

Parameters:

options (Dict[str, Any]) – A dictionary of explicitly provided key-value options.
gitlab_id (str | None) – ID of the configuration section.
config_files (List[str] | None) – List of paths to configuration files.

Returns:

A Gitlab connection.

Return type:

(gitlab.Gitlab)

Raises:

gitlab.config.GitlabDataError – If the configuration is not correct.

mergerequests: See MergeRequestManager

namespaces: See NamespaceManager

notificationsettings: See NotificationSettingsManager

pagesdomains: See PagesDomainManager

personal_access_tokens: See PersonalAccessTokenManager

projects: See ProjectManager

registry_repositories: See RegistryRepositoryManager

runners: See RunnerManager

runners_all: See RunnerManager

search(scope: str, search: str, **kwargs: Any) → GitlabList | List[Dict[str, Any]]

Search GitLab resources matching the provided string.’

Parameters:

scope (str) – Scope of the search
search (str) – Search string
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

Raises:

GitlabAuthenticationError – If authentication is not correct
GitlabSearchError – If the server failed to perform the request

Returns:

A list of dicts describing the resources found.

Return type:

GitlabList | List[Dict[str, Any]]

set_license(license: str, **kwargs: Any) → Dict[str, Any]

Add a new license.

Parameters:

license (str) – The license string
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

Raises:

GitlabAuthenticationError – If authentication is not correct
GitlabPostError – If the server cannot perform the request

Returns:

The new license information

Return type:

Dict[str, Any]

settings: See ApplicationSettingsManager

sidekiq: See SidekiqManager

snippets: See SnippetManager

ssl_verify: Whether SSL certificates should be validated

statistics: See ApplicationStatisticsManager

timeout: Timeout to use for requests to gitlab server

todos: See TodoManager

topics: See TopicManager

property url: str: The user-provided server URL.

user_activities: See UserActivitiesManager

users: See UserManager

variables: See VariableManager

version() → Tuple[str, str]

Returns the version and revision of the gitlab server.

Note that self.version and self.revision will be set on the gitlab object.

Returns:

The server version and server revision.: (‘unknown’, ‘unknown’) if the server doesn’t perform as expected.

Return type:

Tuple[str, str]

exception gitlab.GitlabActivateError(error_message: str | bytes = '', response_code: int | None = None, response_body: bytes | None = None)

API reference (gitlab package)¶

Module contents¶

Subpackages¶

Submodules¶

gitlab.base module¶

gitlab.cli module¶

gitlab.config module¶

gitlab.const module¶

gitlab.exceptions module¶

gitlab.mixins module¶

gitlab.utils module¶

API reference (`gitlab` package)¶