Pulumi GitLab Provider

9.10.0 · active · verified Thu Apr 16

A Pulumi package for creating and managing GitLab resources. The `pulumi-gitlab` library allows users to define, deploy, and manage GitLab entities such as projects, groups, users, and CI/CD configurations using Python code. It is currently at version 9.10.0 and maintains a frequent release cadence, often with weekly or bi-weekly updates.

Common errors

```
Error: unable to refresh environment: GitLab API returned error: 403 Forbidden
```
cause The GitLab token used (via `GITLAB_TOKEN` environment variable or Pulumi config) has insufficient permissions or is incorrect. Project/Group access tokens often have limited scopes.

fix Verify your `GITLAB_TOKEN`. Ensure it's a Personal Access Token or Service Account token with appropriate scopes (e.g., `api`). Regenerate if necessary.
```
error: no stack named '<stack-name>' found
```
cause This error typically occurs in CI/CD pipelines when `pulumi stack select <stack-name>` is executed before the stack has been initialized, or if the `PULUMI_ACCESS_TOKEN` doesn't have access to the specified stack/organization.

fix Ensure the stack is created with `pulumi stack init <stack-name>` before running `pulumi select` or `pulumi up`. Also, verify that the `PULUMI_ACCESS_TOKEN` has the necessary permissions to access the stack and organization.
```
Error: 409 conflict: Another update is currently in progress. To get past this, run `pulumi stack resume` if you think no update is running.
```
cause This means a Pulumi update (or preview) is already running on the target stack, or a previous update failed without releasing the stack lock.

fix Wait for the ongoing operation to complete. If no operation is actually running, manually clear the lock using `pulumi stack resume`.
```
gitlab.Project is not a callable object
```
cause This error occurs if you try to call `gitlab.Project` as a function, but the import `from pulumi_gitlab import Project` or `import pulumi_gitlab as gitlab` didn't correctly resolve the `Project` resource constructor. This could happen with an incorrect import alias or a malformed `__init__.py` in a custom `pulumi_gitlab` wrapper.

fix Ensure you have `import pulumi_gitlab as gitlab` and are calling resources like `gitlab.Project(...)`. If you are importing directly, ensure it is `from pulumi_gitlab import Project` and then call `Project(...)`.

Warnings

breaking In `v9.4.0`, the `memberRoleId` property in `gitlab:index/groupMembership:GroupMembership` resource became optional. Additionally, in the `gitlab:index/getProjectsProject:getProjectsProject` type, the `links` and `resourceGroupDefaultProcessMode` properties changed from optional to required.
Fix: Review `GroupMembership` resource definitions and `getProjectsProject` data source usages. Update code to reflect `memberRoleId` as optional and ensure `links` and `resourceGroupDefaultProcessMode` are provided when using `getProjectsProject`.
breaking In `v9.3.0`, the `nodeId` property in the `gitlab:index/getRepositoryTreeTree:getRepositoryTreeTree` type changed from optional to required.
Fix: Ensure that `nodeId` is provided when using the `getRepositoryTreeTree` data source.
gotcha When configuring the GitLab provider for self-hosted GitLab CE or GitLab Enterprise instances, the `baseUrl` property must be explicitly set and must end with `/api/v4/`. It can be provided in the provider configuration or via the `GITLAB_BASE_URL` environment variable.
Fix: Set `baseUrl` in your Pulumi program or `GITLAB_BASE_URL` environment variable, e.g., `https://my.gitlab.server/api/v4/`.
gotcha Project or Group access tokens, or `CI_JOB_TOKEN`s, may have limited permissions and cause `permission denied` or `403` errors for certain resources.
Fix: For comprehensive access, use a dedicated Personal Access Token or a Service Account with the necessary scopes (e.g., `api`) for the provider's authentication.
gotcha In CI/CD environments, the `PULUMI_ACCESS_TOKEN` environment variable is crucial for authenticating with Pulumi Cloud and performing `pulumi preview` or `pulumi up`. This token must be accessible to the CI job, especially considering GitLab's protected branch settings.
Fix: Ensure `PULUMI_ACCESS_TOKEN` is set as a secret environment variable in your CI/CD pipeline and is configured to be accessible by the branches running Pulumi commands.

Install

pip install pulumi_gitlab Install with pip

Imports

Group
```
from pulumi_gitlab import Group
```
Used to manage GitLab groups.
Project
```
from pulumi_gitlab import Project
```
Used to manage GitLab projects.
Provider
```
from pulumi_gitlab import Provider
```
Used to configure the GitLab provider, though often implicit via environment variables or Pulumi config.

Quickstart

This quickstart program demonstrates how to create a GitLab group and a project within that group using Pulumi and Python. It assumes the `GITLAB_TOKEN` environment variable is set for authentication.

import pulumi
import pulumi_gitlab as gitlab
import os

# Configure the GitLab token using an environment variable.
# Alternatively, use `pulumi config set gitlab:token <YOUR_TOKEN> --secret`
# os.environ.get('GITLAB_TOKEN') should contain a valid GitLab Personal Access Token
# with appropriate scopes (e.g., 'api', 'read_repository', 'write_repository').

# Create a new GitLab Group
example_group = gitlab.Group("example-group",
    name="my-pulumi-managed-group",
    path="my-pulumi-managed-group",
    description="Managed by Pulumi",
    visibility_level="private"
)

# Create a new GitLab Project within the group
example_project = gitlab.Project("example-project",
    name="my-pulumi-managed-project",
    description="My awesome project managed by Pulumi.",
    namespace_id=example_group.id,
    visibility_level="private",
    initialize_with_readme=True
)

pulumi.export("group_url", example_group.web_url)
pulumi.export("project_url", example_project.web_url)

view raw JSON →