{"id":8455,"library":"pulumi-gitlab","title":"Pulumi GitLab Provider","description":"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.","status":"active","version":"9.10.0","language":"en","source_language":"en","source_url":"https://github.com/pulumi/pulumi-gitlab","tags":["pulumi","gitlab","iac","devops","cloud-native","automation"],"install":[{"cmd":"pip install pulumi_gitlab","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core Pulumi SDK is required to use any Pulumi provider.","package":"pulumi","optional":false},{"reason":"Minimum Python version required for the library.","package":"python","optional":false}],"imports":[{"note":"Used to manage GitLab groups.","symbol":"Group","correct":"from pulumi_gitlab import Group"},{"note":"Used to manage GitLab projects.","symbol":"Project","correct":"from pulumi_gitlab import Project"},{"note":"Used to configure the GitLab provider, though often implicit via environment variables or Pulumi config.","symbol":"Provider","correct":"from pulumi_gitlab import Provider"}],"quickstart":{"code":"import pulumi\nimport pulumi_gitlab as gitlab\nimport os\n\n# Configure the GitLab token using an environment variable.\n# Alternatively, use `pulumi config set gitlab:token <YOUR_TOKEN> --secret`\n# os.environ.get('GITLAB_TOKEN') should contain a valid GitLab Personal Access Token\n# with appropriate scopes (e.g., 'api', 'read_repository', 'write_repository').\n\n# Create a new GitLab Group\nexample_group = gitlab.Group(\"example-group\",\n    name=\"my-pulumi-managed-group\",\n    path=\"my-pulumi-managed-group\",\n    description=\"Managed by Pulumi\",\n    visibility_level=\"private\"\n)\n\n# Create a new GitLab Project within the group\nexample_project = gitlab.Project(\"example-project\",\n    name=\"my-pulumi-managed-project\",\n    description=\"My awesome project managed by Pulumi.\",\n    namespace_id=example_group.id,\n    visibility_level=\"private\",\n    initialize_with_readme=True\n)\n\npulumi.export(\"group_url\", example_group.web_url)\npulumi.export(\"project_url\", example_project.web_url)\n","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=9.4.0"},{"fix":"Ensure that `nodeId` is provided when using the `getRepositoryTreeTree` data source.","message":"In `v9.3.0`, the `nodeId` property in the `gitlab:index/getRepositoryTreeTree:getRepositoryTreeTree` type changed from optional to required.","severity":"breaking","affected_versions":">=9.3.0"},{"fix":"Set `baseUrl` in your Pulumi program or `GITLAB_BASE_URL` environment variable, e.g., `https://my.gitlab.server/api/v4/`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Project or Group access tokens, or `CI_JOB_TOKEN`s, may have limited permissions and cause `permission denied` or `403` errors for certain resources.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"Error: unable to refresh environment: GitLab API returned error: 403 Forbidden"},{"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.","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.","error":"error: no stack named '<stack-name>' found"},{"fix":"Wait for the ongoing operation to complete. If no operation is actually running, manually clear the lock using `pulumi stack resume`.","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.","error":"Error: 409 conflict: Another update is currently in progress. To get past this, run `pulumi stack resume` if you think no update is running."},{"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(...)`.","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.","error":"gitlab.Project is not a callable object"}]}