Set up the GitLab EE and CE VCS provider

These instructions are for using an on-premise installation of GitLab Enterprise Edition (EE) or GitLab Community Edition (CE) for HCP Terraform's VCS features. GitLab.com has separate instructions, as do the other supported VCS providers.

Configuring a new VCS provider requires permission to manage VCS settings for the organization. (More about permissions.)

Connecting HCP Terraform to your VCS involves four steps:

The rest of this page explains the on-premise GitLab versions of these steps.

Step 1: On HCP Terraform, Begin Adding a New VCS Provider

1. Go to your organization's settings and then click Providers. The VCS Providers page appears.

2. Click Add VCS Provider. The VCS Providers page appears.

3. Select GitLab and then select GitLab Enterprise Edition or GitLab Community Edition from the menu. The page moves to the next step.

4. In the "Set up provider" step, fill in the HTTP URL and API URL of your GitLab Enterprise Edition or GitLab Community Edition instance, as well as an optional Name for this VCS connection. Click "Continue."

   Field	Value
   HTTP URL	https://<GITLAB INSTANCE HOSTNAME>
   API URL	https://<GITLAB INSTANCE HOSTNAME>/api/v4

   Note that HCP Terraform uses GitLab's v4 API.

Leave the page open in a browser tab. In the next step you will copy values from this page, and in later steps you will continue configuring HCP Terraform.

Step 2: On GitLab, Create a New Application

1. In a new browser tab, open your GitLab instance and log in as whichever account you want HCP Terraform 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 HCP Terraform 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; HCP Terraform 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/network). Refer to the GitLab documentation for details.

2. 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:

   • Click your profile picture and choose "Settings."
   • Click "Applications."

3. 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 fields and checkboxes with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard.

   Fill out the form as follows:

   Field	Value
   Name	HCP Terraform (<YOUR ORGANIZATION NAME>)
   Redirect URI	https://app.terraform.io/<YOUR CALLBACK URL>
   Confidential (checkbox)	✔️ (enabled)
   Expire access tokens (checkbox)	(no longer required)
   Scopes (all checkboxes)	api

   Note: For previous versions of HCP Terraform and GitLab, we recommended disabling a setting called Expire access tokens. This action was required because Gitlab marked OAuth tokens as expired after 2 hours, but HCP Terraform only refreshed tokens after 6 hours. This setting does not exist on Gitlab v15+ and HCP Terraform now refreshes tokens more often.

4. Click the "Save application" button, which creates the application and takes you to its page.

5. Leave this page open in a browser tab. In the next step, you will copy and paste the unique Application ID and Secret.

Step 3: On HCP Terraform, Set up Your Provider

1. On the "Configure settings" step on HCP Terraform, enter the Application ID and Secret from the previous step.

2. Click Connect and continue. This takes you to a page on GitLab asking whether you want to authorize the app. Alternatively, if you are redirected to a 500 error, it usually means HCP Terraform was unable to reach your GitLab instance.

3. Click the green Authorize button at the bottom of the authorization page.

Step 4: On HCP Terraform, Configure Advanced Settings (Optional)

The settings in this section are optional. The Advanced Settings you can configure are:

• Scope of VCS Provider - You can configure which workspaces can use repositories from this VCS provider. By default the All Projects option is selected, meaning this VCS provider is available to be used by all workspaces in the organization.
• Set up a PEM formatted SSH Keypair - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time.

If You Don't Need to Configure Advanced Settings:

1. Click the Skip and Finish button. This returns you to HCP Terraform's VCS Provider page, which now includes your new GitLab client.

If You Need to Limit the Scope of this VCS Provider:

1. Select the Selected Projects option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider.

2. Click the Update VCS Provider button to save your selections.

If You Do Need a PEM formatted SSH Keypair:

Important Notes

• SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS.
• Do not use your personal SSH key to connect HCP Terraform and GitLab; generate a new one or use an existing key reserved for service access.
• In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, it retains it and will use it when authenticating to GitLab.
• Protect this private key carefully. It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them.

1. On a secure workstation, create a PEM formatted SSH keypair that HCP Terraform can use to connect to GitLab. The exact command depends on your OS, but is usually something like: ssh-keygen -t rsa -m PEM -f "/Users/<NAME>/.ssh/service_terraform" -C "service_terraform_enterprise" This creates a service_terraform file with the private key, and a service_terraform.pub file with the public key. This SSH key must have an empty passphrase. HCP Terraform cannot use SSH keys that require a passphrase.

2. While logged into the GitLab account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created.

3. In HCP Terraform's Add VCS Provider page, paste the text of the SSH private key you just created, and click the Add SSH Key button.

Finished

At this point, GitLab access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared repositories.