Pulumi CI/CD & GitLab Integration

With this GitLab integration, Pulumi is able to add Pulumi Previews to a GitLab Merge Request.

Integration Methods

There are two ways to integrate Pulumi and GitLab.

• If you are a Premium or Ultimate GitLab customer, you will use a GitLab Group Access Token. This integration type is simpler to setup and is not tied to a specific user. The user configuring the integration will need to be a GitLab Organization Owner.
• If you are not a paying GitLab customer, you will use a User OAuth Token. You will also need to configure a webhook, as described below.

Integrating via GitLab Group Access Token

If you are a Premium or Ultimate GitLab customer, you have access to GitLab Group Access Tokens, which Pulumi will use to add Pulumi Previews to your merge requests.

In Pulumi Cloud

1. Navigate to Settings > Integrations in the Pulumi Cloud dashboard.
2. In the GitLab integration card, select Authorize GitLab.

In GitLab

1. You will be redirected to GitLab, where you will be asked to approve the integration. Authenticate with your GitLab identity. This authorization is temporary and can be removed later.

Back in Pulumi Cloud

1. After approving the integration and being redirected back to Pulumi Cloud, use the dropdown to select the GitLab organization you would like to integrate with and select Save.
2. The authorization between the GitLab organization and Pulumi is now complete. Optionally, you can disassociate your personal GitLab identity from Pulumi by selecting your identity in the top right corner of the integration card, then selecting Remove Identity.

Configuring the GitLab pipeline

For the Pulumi preview command to run, you need to add a GitLab pipeline file to your project. If you are already using pipelines, you just need to update your pipeline file.

In Pulumi Cloud

1. Generate a Pulumi access token using the account that you would like to post the merge request notes. Save this token for use in the next step.

In GitLab

1. Set the newly generated token as a CI Variable for your project. Name it PULUMI_ACCESS_TOKEN.

2. In your GitLab project, create a .gitlab-ci.yml file if one doesn’t already exist.

3. Add the following content to the .gitlab-ci.yml file, updating pulumi/gitlab-demo/dev to be the path to your stack:

   image: pulumi/pulumi-go:latest
   
   stages:
       - pulumi
   
   preview:
     stage: pulumi
     script:
       - pulumi preview -s pulumi/gitlab-demo/dev
     only:
       - merge_request
   

4. Commit the file.

Configuring the GitLab webhook

In Pulumi Cloud

1. Create a Pulumi access token using the account that you would like the merge request notes to be posted as. Save this token for use in the next step.

In GitLab

You can configure a Group Hook or a Project Hook. The configuration values are the same regardless of where the webhook is registered. Configuring a webhook at the Group level means you don’t have to configure it for every project manually.

1. Navigate to Settings > Webhooks in your GitLab Group or Project.

2. Fill out the form as follows:

   • URL: https://api.pulumi.com/workflow/gitlab
   • Secret Token: The Pulumi access token you created above
   • Uncheck all trigger boxes and check only Merge request events

   

3. Ensure the checkbox under SSL verification is checked.

4. Click Add webhook.

   

That’s it! Now when you create a merge request and run Pulumi in a merge request pipeline, you should see notes in the MR that show a summary of the Pulumi preview. Learn how to run Pulumi in GitLab CI/CD.

Here’s a preview of what the merge request note looks like in GitLab:

Disabling the Integration

If would like to disable the integration for a specific execution of Pulumi, you can always set the PULUMI_DISABLE_CI_DETECTION env var to false without having to remove the integration configuration itself.