Connecting GitLab

Connect your GitLab account to enable automated Terraform reviews on every merge request. The setup takes under five minutes and requires GitLab Owner or Maintainer permissions on the projects you want to monitor.

🚀 Overview

Terracotta connects to GitLab via OAuth to read your Terraform files and post review comments on merge requests. Once connected, reviews trigger automatically on new MRs and push events — no CI pipeline changes required.

🛠️ OAuth Setup

Navigate to Settings > Integrations > GitLab in the Terracotta dashboard.
Click Connect GitLab.
You are redirected to GitLab to authorize the Terracotta application.
Review the requested permissions and click Authorize.
GitLab redirects you back to Terracotta with the connection confirmed.

If your organization uses a self-managed GitLab instance, enter your instance URL before clicking Connect.

🔐 Required Scopes

Terracotta requests two OAuth scopes during authorization:

Scope	Purpose
`api`	Post review comments and status checks on merge requests
`read_repository`	Read Terraform files and directory structure from your projects

These are the minimum scopes required for Terracotta to function. No write access to your code is requested.

🔍 Project Selection

After authorization, you are presented with a list of your GitLab projects:

Select the projects Terracotta should monitor for Terraform changes
Use the search bar to filter by project name or group
You can add or remove projects at any time from Settings > Integrations > GitLab

Start with one or two projects to validate the integration before rolling out across your organization.

🛠️ Webhook Setup

Terracotta automatically creates webhooks on each selected project. These webhooks notify Terracotta when:

A new merge request is opened
New commits are pushed to an existing merge request
A merge request is reopened

You do not need to configure webhooks manually. If a webhook is accidentally deleted, disconnect and reconnect the project to recreate it.

✅ Verifying the Connection

To confirm everything is working:

Open a merge request with Terraform changes (.tf files) in a connected project.
Terracotta posts a review comment within 60 seconds.
The comment includes findings, severity badges, and fix recommendations.

If no comment appears:

Verify the project is selected in Settings > Integrations > GitLab
Check that the merge request contains .tf file changes
Confirm the webhook exists in GitLab > Project > Settings > Webhooks

📋 TL;DR

Connect GitLab via OAuth from Settings > Integrations > GitLab
Terracotta requests api and read_repository scopes — no code write access
Select which projects to monitor after authorization
Webhooks are created automatically on selected projects
Verify by opening an MR with Terraform changes — expect a review comment within 60 seconds