» Configuring GitLab EE and CE Access
These instructions are for using an on-premise installation of GitLab Enterprise Edition (EE) or GitLab Community Edition (CE) for Terraform Cloud's VCS features. GitLab.com has separate instructions, as do the other supported VCS providers.
Connecting Terraform Cloud to your VCS involves five steps:
|On your VCS||On Terraform Cloud|
|Register your Terraform Cloud organization as a new app. Get ID and key.|
|Tell Terraform Cloud how to reach VCS, and provide ID and key. Get callback URL.|
|Provide callback URL.|
|Request VCS access.|
|Approve access request.|
The rest of this page explains the on-premise GitLab versions of these steps.
Important: Terraform Cloud needs to contact your GitLab instance during setup and during normal operation. For the SaaS version of Terraform Cloud, this means GitLab must be internet-accessible; for Terraform Enterprise, you must have network connectivity between your Terraform Enterprise and GitLab instances.
Note: Alternately, you can skip the OAuth configuration process and authenticate with a personal access token. This requires using Terraform Cloud's API. For details, see the OAuth Clients API page.
Version Note: Terraform Cloud supports GitLab versions 9.0 and newer. HashiCorp does not test older versions of GitLab with Terraform Cloud, and they might not work as expected. Also note that, although we do not deliberately remove support for versions that have reached end of life (per the GitLab Support End of Life Policy), our ability to resolve customer issues with end of life versions might be limited.
» Step 1: On GitLab, Create a New Application
Open your GitLab instance in your browser and log in as whichever account you want Terraform Cloud to act as. For most organizations this should be a dedicated service user, but a personal account will also work.
Important: The account you use for connecting Terraform Cloud must have admin (master) access to any shared repositories of Terraform configurations, since creating webhooks requires admin permissions. Do not create the application as an administrative application not owned by a user; Terraform Cloud needs user access to repositories to create webhooks and ingress configurations.
Important: In GitLab CE or EE 10.6 and up, you may also need to enable Allow requests to the local network from hooks and services on the "Outbound requests" section inside the Admin area under Settings (
/admin/application_settings). Refer to the GitLab documentation for details.
Navigate to GitLab's "User Settings > Applications" page.
This page is located at
https://<GITLAB INSTANCE HOSTNAME>/profile/applications. You can also reach it through GitLab's menus:
- In the upper right corner, click your profile picture and choose "Settings."
- In the navigation sidebar, click "Applications."
This page has a list of applications and a form for adding new ones. The form has two text fields and some checkboxes.
Fill out the form as follows:
Field Value (all checkboxes) (empty) Name Terraform Cloud (
<YOUR ORGANIZATION NAME>)
https://example.com/replace-this-later(or any placeholder; the correct URI doesn't exist until the next step.)
Click the "Save application" button, which creates the application and takes you to its page.
Leave this page open in a browser tab. In the next step, you will copy and paste the unique Application ID and Secret.
» Step 2: On Terraform Cloud, Add a VCS Provider
Open Terraform Cloud in your browser and navigate to the "VCS Provider" settings for your organization. Click the "Add VCS Provider" button.
If you just created your organization, you might already be on this page. Otherwise:
- Click the upper-left organization menu, making sure it currently shows your organization.
- Click the "Settings" link at the top of the page (or within the ☰ menu)
- On the next page, click "VCS Provider" in the left sidebar.
- Click the "Add VCS Provider" button.
The next page has a drop-down and four text fields. Select "GitLab Enterprise Edition" or "GitLab Community Edition" from the drop-down, and fill in all four text fields as follows:
Field Value HTTP URL
https://<GITLAB INSTANCE HOSTNAME>
https://<GITLAB INSTANCE HOSTNAME>/api/v4
Application ID (paste value from previous step) Secret (paste value from previous step)
Note that Terraform Cloud uses GitLab's v4 API.
Click "Create connection." This will take you back to the VCS Provider page, which now includes your new GitLab client.
Locate the new client's "Callback URL," and copy it to your clipboard; you'll paste it in the next step. Leave this page open in a browser tab.
» Step 3: On GitLab, Update the Callback URL
Go back to your GitLab browser tab. (If you accidentally closed it, you can reach your OAuth app page through the menus: use the upper right menu > Settings > Applications > "Terraform Cloud (
<YOUR ORG NAME>)".)
Click the "Edit" button.
In the "Redirect URI" field, paste the callback URL from Terraform Cloud's VCS Provider page, replacing the "example.com" placeholder you entered earlier.
Click the "Save application" button. A banner saying the update succeeded should appear at the top of the page.
» Step 4: On Terraform Cloud, Request Access
Go back to your Terraform Cloud browser tab and click the "Connect organization
<NAME>" button on the VCS Provider page.
This takes you to a page on GitLab, asking whether you want to authorize the app.
Click the green "Authorize" button at the bottom of the authorization page. This returns you to Terraform Cloud's VCS Provider page, where the GitLab client's information has been updated.
If this results in a 500 error, it usually means Terraform Cloud was unable to reach your GitLab instance.
At this point, GitLab access for Terraform Cloud is fully configured, and you can create Terraform workspaces based on your organization's shared repositories.