python-gitlab

Warnings

• breaking python-gitlab v7.0.0 and later require Python 3.10 or higher. Python 3.9 and older are no longer supported.
  Fix: Upgrade your Python environment to 3.10 or newer. Ensure your `pyproject.toml` or `requirements.txt` specifies `python_requires='>=3.10'` for compatibility.
• breaking In python-gitlab v8.0.0, the GraphQL API client's `GraphQL.execute()` method no longer accepts `graphql.Source` objects directly.
  Fix: Review the GraphQL client usage and adapt to the updated `GraphQL.execute()` signature, likely by passing the query string directly or using `gql` package objects.
• gotcha Password-based authentication (username/password) is deprecated and largely removed from GitLab API v10.2 onwards. It is highly recommended to use Personal Access Tokens or OAuth tokens.
  Fix: Switch to Personal Access Tokens, Project Access Tokens, or OAuth tokens for authentication. Avoid using direct username/password pairs.
• gotcha If your GitLab instance redirects HTTP requests to HTTPS (e.g., `http://gitlab.example.com` to `https://gitlab.example.com`), you must specify the final HTTPS URL in the `Gitlab` object constructor to avoid `RedirectionError` or malformed requests.
  Fix: Always use the canonical (final) URL of your GitLab instance, typically starting with `https://`, when initializing the `Gitlab` object.
• gotcha By default, python-gitlab handles rate limiting by sleeping and retrying based on `Retry-After` headers or exponential backoff. It also does *not* retry transient HTTP errors (5xx codes) by default.
  Fix: To customize rate limiting behavior (e.g., disable waiting), use `obey_rate_limit=False` or `max_retries`. To enable automatic retries for transient errors, set `retry_transient_errors=True` during `Gitlab` object initialization or on individual API calls.

Install

• pip install python-gitlab Install latest version

Imports

• Gitlab

  import gitlab
  gl = gitlab.Gitlab(...)

  Importing the top-level 'gitlab' module is the standard and recommended practice for accessing the Gitlab class and other functionalities.

Quickstart

This quickstart demonstrates how to connect to a GitLab instance using a personal access token and then fetch a list of projects owned by the authenticated user. It highlights setting the GitLab URL and private token via environment variables for security and explicitly uses API v4.

import os
import gitlab

# Configure GitLab connection using environment variables
GITLAB_URL = os.environ.get('GITLAB_URL', 'https://gitlab.com')
GITLAB_PRIVATE_TOKEN = os.environ.get('GITLAB_PRIVATE_TOKEN', 'your_private_token_here')

# Initialize the Gitlab API client
# Ensure you use 'https://' if your GitLab instance redirects from http
try:
    gl = gitlab.Gitlab(
        url=GITLAB_URL,
        private_token=GITLAB_PRIVATE_TOKEN,
        api_version='4' # Explicitly set API version, often '4'
    )
    
    # Optional: Validate the token by getting the current authenticated user
    gl.auth() 
    user = gl.user.get()
    print(f"Connected to GitLab as: {user.username}")

    # List current user's projects
    print("\nListing your projects:")
    projects = gl.projects.list(owned=True, all=True)
    if projects:
        for project in projects:
            print(f"  - {project.name} (ID: {project.id})")
    else:
        print("  No projects found.")

except gitlab.exceptions.GitlabError as e:
    print(f"GitLab API error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")