prefect-gitlab

0.3.4 verified Mon Apr 27 auth: no python

A Prefect collection for interacting with GitLab repositories. Provides blocks and tasks to manage GitLab resources (e.g., repositories, merge requests, CI/CD) within Prefect flows. Current version: 0.3.4. Released as part of the Prefect integration ecosystem; release cadence follows Prefect main branch releases.

pip install prefect-gitlab

Common errors

error ImportError: cannot import name 'GitLabCredentials' from 'prefect_gitlab' ↓

cause Prefect GitLab collection not installed, or wrong import path.

fix

Run pip install prefect-gitlab and ensure the import is from prefect_gitlab import GitLabCredentials.

error prefect.exceptions.MissingVariableError: Variable 'GITLAB_TOKEN' not found. ↓

cause Token not provided or not set as environment variable.

fix

Set the GITLAB_TOKEN environment variable, or use a Prefect Secret block: GitLabCredentials(token=PREFECT_SECRET('my-gitlab-token')).

error gitlab.exceptions.GitlabAuthenticationError: 401 Unauthorized ↓

cause Invalid or expired GitLab personal access token.

fix

Generate a new token in GitLab (Settings > Access Tokens) and update the credentials.

Warnings

gotcha The `GitLabCredentials.token` field is not mapped to Prefect secrets by default. You must provide the token explicitly via env var or Prefect block. ↓

fix Store the token as a Prefect Secret block and reference it using `GitLabCredentials(token=PREFECT_SECRET('my-gitlab-token'))` or pass via environment variable.

gotcha `GitLabRepository.repository` expects a full path (e.g., 'namespace/project'), not just a project name or ID. ↓

fix Use the full path as shown in the GitLab UI (e.g., 'my-group/my-subgroup/my-project').

breaking Prefect 3.x introduced breaking changes in block schema. If upgrading from Prefect 2.x, you must recreate GitLab Credentials blocks. ↓

fix After upgrading Prefect, delete old blocks and create new ones via the UI or CLI: `prefect block register -m prefect_gitlab`.

Imports

GitLabCredentials
```
from prefect_gitlab import GitLabCredentials
```
Common mistake: trying to import from prefect_gitlab.credentials or other nested paths.

GitLabRepository

wrong

from prefect_gitlab.repositories import GitLabRepository

correct

from prefect_gitlab import GitLabRepository

GitLabRepository is exposed at the top-level package.

Quickstart

Minimal example: instantiate GitLabCredentials with a token, then use GitLabRepository to interact with a GitLab project.

import os
from prefect import flow
from prefect_gitlab import GitLabCredentials, GitLabRepository

@flow
def gitlab_example():
    credentials = GitLabCredentials(
        url="https://gitlab.com",
        token=os.environ.get("GITLAB_TOKEN", ""),
    )
    repo = GitLabRepository(
        credentials=credentials,
        repository="namespace/project",
    )
    # Example: list recent commits
    commits = repo.list_commits()
    print(commits)

if __name__ == "__main__":
    gitlab_example()