Configuring Bitbucket Server/Data Center Access

These instructions are for using Bitbucket Server for HCP Terraform's VCS features.

These instructions also apply to Bitbucket Data Center, which is a variant of Bitbucket Server that supports clustering. HCP Terraform treats these two products identically, and Bitbucket Data Center users will select Bitbucket Server as their VCS Provider type. Unless stated otherwise, any reference to Bitbucket Server in this document also applies to Bitbucket Data Center.

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

Bitbucket Cloud has separate instructions, as do the other supported VCS providers.

Note that Bitbucket Server requires both OAuth authentication and an SSH key, both of which are covered in the instructions.

Before You Begin: Determine Your Bitbucket Server Version

HCP Terraform requires support for the delivery of webhooks to perform many operations, including tracking newly available configuration versions. When using Bitbucket Server version 5.3 or below (deprecated), Atlassian's webhooks plugin is required to be configured on Bitbucket Server. If using version 5.4 or above, no plugin is required, as webhooks are supported natively.

1. Open your Bitbucket server instance in your browser and log in as an admin user.

2. In the footer of every page is a reference to the instance's current version. If your version is greater than v5.4.0, you may skip all remaining steps in this section.

3. Go to the "Manage add-ons" page. You can click the gear icon and then use the "Manage add-ons" link or go directly to https://<BITBUCKET INSTANCE HOSTNAME>/plugins/servlet/upm.

4. Look for an add-on named "Web Post Hooks for Bitbucket Server", and make sure it is installed and enabled. The plugin is disabled by default. Clicking Enabled will toggle the plugin on.

5. If the plugin isn't present, click "Find new add-ons". Search for the plugin by name and install it.

   Make sure to install the correct plugin. HCP Terraform is designed to work with Web Post Hooks for Bitbucket Server by Atlassian .

   

6. Visit the repository's settings, click on Hooks and check that the plugin is enabled there as well.

There is an option to configure a webhook URL on the plugin. Leave this optional field blank. HCP Terraform will dynamically update the webhook URL after the VCS connection is established.

Leave the page open in a browser tab, and remain logged in as an admin user.

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 Bitbucket and then select Bitbucket Server from the menu. The page moves to the next step.

4. (Optional) Enter a Name for this VCS connection.

5. Enter the URL of your Bitbucket Server instance in the HTTP URL and API URL fields.

   Important: The values for the HTTP URL and API URL fields differ depending on whether or not your Bitbucket Server instance has a context path set.

   If your Bitbucket Server instance does not have a context path set, the API URL should be the same as the HTTP URL.

   If your Bitbucket Server instance has a context path set:

   1. Set the HTTP URL to the URL of your Bitbucket Server instance with the context path included, https://<BITBUCKET INSTANCE HOSTNAME>/<CONTEXT PATH>.
   2. Set the API URL to the URL of your Bitbucket Server instance without the context path, https://<BITBUCKET INSTANCE HOSTNAME>.

   Important: If Bitbucket Server isn't accessible on the standard ports (for example, if it's using its default ports of 7990 or 8443 and is not behind a reverse proxy), make sure to specify the port in the URL. If you omit the port in the URL, HCP Terraform uses the standard port for the protocol (80 for HTTP, 443 for HTTPS).

6. Click "Continue" to view the generated Consumer Key and Public Key you can use to create a new Application Link in BitBucket Server. Leave this page open so you can copy and paste these values in Step 2.

   To use keys from an existing Application Link, toggle "Use Custom Keys" and enter them into the page.

Step 2: On Bitbucket Server, Create a New Application Link

1. While logged in as an admin user, go to Bitbucket Server's "Application Links" administration page. Navigate to the admin pages or go directly to https://<BITBUCKET INSTANCE HOSTNAME>/plugins/servlet/applinks/listApplicationLinks.

   This page has a text field for creating a new application link, followed by a list of existing application links.

   

2. Select Create link in application links.

3. Select Atlassian product as the link type. This option also works for external applications and lets you continue to use OAuth 1.0 integrations.

4. Enter HCP Terraform's URL in the text field (https://app.terraform.io or the hostname of your Terraform Enterprise instance).

   Note: If you connect multiple HCP Terraform organizations to the same Bitbucket Server instance, you can only use HCP Terraform's main URL once. For subsequent organizations, you can enter the organization URL instead. Organization URLs are the pages you go to using HCP Terraform's Workspaces button and look like https://app.terraform.io/app/<ORG NAME> or https://<TFE HOSTNAME>/app/<ORG NAME>.

5. In the "Configure application URL" dialog, confirm that you wish to use the URL exactly as you entered it. If you used HCP Terraform's main URL, click "Continue;" if you used an organization URL, click the "Use this URL" checkbox and then click "Continue."

   

6. In the "Link applications" dialog, fill out the form fields as follows:

   Field	Value
   Application Name (text)	HCP Terraform (<ORG NAME>)
   Application Type (drop-down)	Generic Application
   Create incoming link (checkbox)	✔️ (enabled)

   Leave all the other fields blank, and click "Continue."

   

7. This takes you to another dialog, also titled "Link applications," with three text fields. In the "Consumer Key" and "Public Key" fields, copy and paste the values from step 1. In the "Consumer Name" field, enter "HCP Terraform (<ORG NAME>)." Click "Continue." This takes you to a page on your Bitbucket Server instance, asking if you want to authorize HCP Terraform. Double-check that you're logged in as the user account HCP Terraform will be using, and not as a Bitbucket administrator.

   

   If this results in a 500 error, it usually means HCP Terraform was unable to reach your Bitbucket Server instance.

8. Click the "Allow" button. This returns you to HCP Terraform to enter a SSH key.

Step 3: On Workstation: Create an SSH Key for HCP Terraform

On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to Bitbucket Server. 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.

Important Notes

• Do not use your personal SSH key to connect HCP Terraform and Bitbucket Server; 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 for authenticating to Bitbucket Server.
• 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.

Step 4: On Bitbucket Server, Switch Users and Add an SSH Key

1. If you are still logged in to Bitbucket Server as an administrator, log out now.

2. 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 access to any shared repositories of Terraform configurations, since creating webhooks requires admin permissions.

3. Go to the "SSH keys" page. You can click the profile icon, choose "Manage account". Click "SSH keys" or you can go directly to https://<BITBUCKET INSTANCE HOSTNAME>/plugins/servlet/ssh/account/keys.

   

4. Click the "Add key" button. Paste the text of the SSH public key you created in step 4 (from the .pub file) into the text field, then click the "Add key" button to confirm.

Step 5: On HCP Terraform, Request Access and Add an SSH Private Key

1. Click the "Add a private SSH key" link. A large text field will appear. Paste the text of the SSH private key you created in step 3, and click the "Add SSH Key" button.

Finished

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