GitLab

Pulumi Cloud integrates with GitLab to post merge request previews, deploy infrastructure on push, create ephemeral review stacks, and report commit statuses. Once configured, the integration automatically registers webhooks on your GitLab group and manages authentication for you.

Installation and configuration

1. Sign in to your Pulumi account.
2. Navigate to Management > Version control.
3. Select Add account and choose GitLab, then follow the prompts to authorize with GitLab.
4. Select the GitLab group you want to integrate with and configure your integration settings.

Pulumi automatically registers a group-level webhook on your GitLab group. No manual webhook or pipeline configuration is required.

Authentication methods

Pulumi supports two authentication methods depending on your GitLab plan:

• Group Access Token (recommended, Premium/Ultimate): Pulumi auto-provisions a token named “Pulumi App Integration for org: {orgName}” with api scope and Owner access level. Tokens expire after 1 year and auto-rotate 6 months before expiration.
• User OAuth Token (all plans including Free): Uses the logged-in user’s GitLab OAuth token with api and read_user scopes. Refresh tokens handle expiry automatically.

If the selected group does not support Group Access Tokens, Pulumi Cloud prompts you to use your personal GitLab account for organization authentication instead.

Individual user setup

Separately from the org-level integration, individual users can complete a 3-step OAuth flow under Management > Version control to grant Pulumi access to their GitLab account. This is used for features like Neo Agent repository creation on the user’s behalf and does not create webhooks.

Integration settings

After creating an integration, you can configure merge request behavior. Toggle these settings per integration:

To delete an integration, select Delete Integration on the integration card. This removes the webhook from your GitLab group and disconnects all stacks using that integration.

Capabilities

Merge request comments

Pulumi automatically posts comments on merge requests with the results of any stack changes. This includes a summary of how many resources were created, updated, or deleted, with a link to the full details in Pulumi Cloud. When enabled, comments also include a collapsible detailed diff and an AI-generated explanation from Neo.

Comments are idempotent: updates to the same stack edit the existing comment rather than creating a new one. Draft and WIP merge requests are treated identically to regular merge requests.

For review stacks, comments show the review stack status and outputs instead of a standard preview summary.

Commit status checks

Pulumi posts commit status checks to GitLab on every deployment, for both push and merge request events. Statuses map to GitLab’s pending, running, success, and failed states and include a link back to the deployment in Pulumi Cloud.

Push-to-deploy

Push-to-deploy automatically runs pulumi up when a commit is pushed to a configured branch, most commonly the default branch. Enable this under Stack > Settings > Deploy by toggling Deploy on push. See the push-to-deploy documentation for setup instructions.

You can use path filters to limit deployments to commits that change files matching specific glob patterns (e.g., infrastructure/**).

Review stacks

Review stacks are ephemeral cloud environments created automatically every time a merge request is opened, powered by Pulumi Deployments. Open a merge request, and Pulumi Deployments stands up a stack with your changes and posts a merge request comment with the outputs. Merge or close the merge request, and Pulumi Deployments destroys the stack and frees the associated resources.

Review stacks follow the naming convention pr-{group}-{project}-{mr-iid} (for example, group acme/infra with merge request #42 produces stack pr-acme-infra-42). Configuration is copied from the template stack via pulumi config cp, and stacks are automatically deleted after the destroy completes.

To enable review stacks, toggle Pull request template under Stack > Settings > Deploy on the stack you want to use as a template.

Environment variables

Pulumi injects the following environment variables during GitLab-triggered deployments:

New project wizard

The New Project Wizard supports GitLab as a VCS provider. When the GitLab integration is configured and you have a GitLab OAuth token, you can:

• Create new GitLab projects in your integrated group (created as private with a README)
• Select an existing GitLab repository and branch
• Choose any deployment method: CLI, Pulumi Deployments (no-code), or Pulumi Deployments (VCS-backed)

When using the VCS-backed deployment method, the wizard configures deploy-on-push, merge request previews, and review stacks automatically. If a template URL contains gitlab.com, GitLab is auto-selected as the VCS provider.

Organizations can register GitLab repositories as template sources. Pulumi scans registered repositories for subdirectories containing a Pulumi.yaml file, and each subdirectory becomes a selectable template. Private repositories are authenticated automatically via the integration’s token.

CI integration

The Pulumi GitLab integration posts results back to GitLab regardless of which CI/CD system triggers the run. You can also run Pulumi commands directly in GitLab CI/CD pipelines. See the GitLab CI guide for setup instructions and example pipeline configurations.

OIDC authentication

Use GitLab CI’s built-in OIDC tokens to authenticate with Pulumi Cloud without storing long-lived credentials as CI variables. See Configuring OpenID Connect for GitLab for configuration details.

Template sources

Use GitLab repositories as template sources for Pulumi IDP. Your teams can reference GitLab-hosted Pulumi templates when creating new projects through the developer portal. For details on registering template repositories, see New project wizard.

Troubleshooting

Merge request comments not appearing

If comments aren’t appearing on your merge requests, verify that:

1. The GitLab integration is connected and shows a valid status under Management > Version control.
2. The webhook exists on your GitLab group. Navigate to your group’s Settings > Webhooks and look for the https://api.pulumi.com/workflow/gitlab endpoint.
3. The stack is associated with the correct GitLab repository and branch.

Integration shows as disconnected

If the integration card shows an invalid or disconnected status, delete the integration and re-create it by following the installation steps.

Deployments not triggering

If deployments aren’t triggering on push or merge request events:

1. Verify deployment settings are enabled under Stack > Settings > Deploy.
2. Check that the branch matches your configured deployment branch.
3. If using path filters, confirm that the changed files match your glob patterns.