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.

1. In the Pulumi dashboard, navigate to Integrations, found under the Settings menu.
2. In the GitLab integration card, select Authorize GitLab.
3. You will be redirected to GitLab, where you will be asked to approve the integration. For this step, you will authenticate with your GitLab identity. This is temporary and can be removed later.
4. After approving the integration and redirecting back to Pulumi, use the dropdown to select the GitLab organization you would like to integrate with and select save.
5. The authorization between the GitLab organization and Pulumi is now complete. Optionally, you can now disassociate your personal GitLab identity from Pulumi by selecting your identity in top right corner of the integration card, and 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.

1. Generate a Pulumi token using the account that you would like to post the merge request notes. Save this token as we will use this momentarily in a following step.

2. In GitLab, set the newly generated token as a CI Variable for your project. Name it PULUMI_ACCESS_TOKEN.

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

4. 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
   

   Copy

5. Commit the file

Configuring the GitLab Webhook

• Create a Pulumi access token using the account that you would like the merge request notes to be posted as. Save this token as we will use this momentarily in a following step.
• You can configure a Group Hook or a Project Hook. The configuration values you use are the same regardless of where the webhook is registered on GitLab.
• Configuring a webhook at the Group-level means that you don’t have to configure the webhook for every project manually. If you only want to configure a webhook for a certain project, then you may do that as well.
• Head-over to the Settings > Webhooks page of your Group or Project and fill out the form as follows:
  • URL: https://api.pulumi.com/workflow/gitlab
  • Secret Token: <The Pulumi access token from above.>
  • Uncheck all boxes and check just the Merge request events checkbox

• Ensure the checkbox under SSL verification is checked as shown below
• Click the Add webhook button.

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 it looks like.

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.