HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Terraform
Terraform Home

Configuring Bitbucket Data Center Access

This topic describes how to connect Bitbucket Data Center to HCP Terraform. For instructions on how to connect Bitbucket Cloud, refer to Configuring Bitbucket Cloud Access. Refer to Connecting VCS Providers to HCP Terraform for other supported VCS providers.

Bitbucket Server is deprecated. Atlassian ended support for Bitbucket Server on February 15, 2024, and recommends using either Bitbucket Data Center (v8.0 or newer) or Bitbucket Cloud instead. Refer to the Atlassian documentation for additional information.

HCP Terraform will end support Bitbucket Server on August 15, 2024. Terraform Enterprise will also end support for Bitbucket Server in Terraform Enterprise v202410. Contact HashiCorp support if you have any questions regarding this change.

Overview

The following steps provide an overview of how to connect HCP Terraform and Terraform Enterprise to Bitbucket Data Center:

  1. Add a new VCS provider to HCP Terraform or Enterprise.
  2. Create a new application link in Bitbucket.
  3. Create an SSH key pair. SSH keys must have an empty passphrase because HCP Terraform cannot use SSH keys that require a passphrase.
  4. Add an SSH key to Bitbucket. You must complete this step as a non-administrator user in Bitbucket.
  5. Add the private SSH key to Terraform.

Requirements

  • You must have permission to manage VCS settings for the organization. Refer to Permissions for additional information.

  • You must have OAuth authentication credentials for Bitbucket Data Center.

  • Your instance of Bitbucket Data Center must be internet-accessible on its SSH and HTTP(S) ports. This is because HCP Terraform must be able to contact Bitbucket Data Center over both SSH and HTTP or HTTPS during setup and during normal operation.

  • HCP Terraform must have network connectivity to Bitbucket Data Center instances. Note that Bitbucket Data Center's default ports are 7999 for SSH and 7990 for HTTP. Check your configuration to confirm your BitBucket instance's real ports.

Add a new VCS provider to Terraform

  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. Choose Bitbucket Data Center from the Bitbucket drop-down menu.

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

  5. Specify the URL of your Bitbucket Data Center instance in the HTTP URL and API URL fields. If the context path is not set for your Bitbucket Data Center instance, the API URL is the same as the HTTP URL. Refer to the Atlassian documentation for additional information. Specify the following values if the context path is set for your Bitbucket Data Center instance:

    • Set the HTTP URL field to your Bitbucket Data Center instance URL and add the context path: https://<BITBUCKET INSTANCE HOSTNAME>/<CONTEXT PATH>.
    • Set the API URL field to your Bitbucket Data Center instance URL: https://<BITBUCKET INSTANCE HOSTNAME>.

    By default, HCP Terraform uses port 80 for HTTP and 443 for HTTPS. If Bitbucket Data Center is configured to use non-standard ports or is behind a reverse proxy, you may need to include the port number in the URL.

  6. You can either generate new consumer and public keys that you can use to create a new application link in Bitbucket Data Center described in Create an application link or use keys from an existing application link:

    • To generate new keys, click Continue. Do not leave this screen until you have copied the key values.
    • To use existing keys, enable the Use Custom Keys option and enter them into the fields.

Create an application link

  1. Log into Bitbucket Data Center as an admin.

  2. Open the Application Links administration page using the navigation or by entering https://<BITBUCKET INSTANCE HOSTNAME>/plugins/servlet/applinks/listApplicationLinks in your browser's address bar.

  3. Click Application Links in the sidebar, then click Create new link.

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

  5. Enter https://app.terraform.io or the hostname of your Terraform Enterprise instance when prompted. You can only specify the main URL once. To connect multiple HCP Terraform organizations to the same Bitbucket Data Center instance, enter the organization URL when creating the link instead. The organization URL is the HCP Terraform URL or Terraform Enterprise hostname appended with /app/<ORG NAME>.

  6. When prompted, confirm that you wish to use the URL as entered. If you specified HCP Terraform's main URL, click Continue. If you specified an organization URL, enable the Use this URL option and then click Continue.

  7. In the Link applications dialog, configure the following settings:

    • Specify HCP Terraform <ORG NAME> in the Application Name field
    • Choose Generic Application from the Application Type drop-down menu
    • Enable the Create incoming link option

    Leave all the other fields empty.

  8. Click Continue. The Link applications screen progresses to the second configuration screen.

  9. In the Consumer Key and Public Key fields, enter the key values you created in the Add a new VCS provider to Terraform instructions.

  10. In the Consumer Name field, enter HCP Terraform (<ORG NAME>).

  11. Click Continue. Bitbucket prompts you to authorize Terraform to make changes. Before you proceed, verify that you are logged in with the user account that HCP Terraform will use to access Bitbucket and not as a Bitbucket administrator. If Bitbucket returns a 500 error instead of the authorization screen, Terraform may have been unable to reach your Bitbucket Data Center instance.

  12. Click Allow and enter the SSH key when prompted.

Create an SSH key for Terraform

On a secure workstation, create an SSH keypair that HCP Terraform or Terraform Enterprise can use to connect to Bitbucket Data Center. The command for generating SSH keys depends on your OS. The following example for Linux creates a service_terraform file with the private key and a service_terraform.pub file with the public key:

$ ssh-keygen -t rsa -m PEM -f "/Users/<NAME>/.ssh/service_terraform" -C "service_terraform_enterprise"

Do not specify a passphrase because Terraform cannot use SSH keys that require a passphrase.

Add an SSH key to Bitbucket

In the following steps, you must provide HCP Terraform with the private SSH key you created in Create an SSH key for Terraform. Although HCP Terraform does not display the text of the key to users after it is entered, it retains the key and uses it for authenticating to Bitbucket Data Center.

  1. If you are logged into Bitbucket Data Center as an administrator, log out before proceeding.
  2. Log in with the account that you want to enable HCP Terraform or Terraform Enterprise to log in with. Many organizations use a dedicated service user account for this purpose. The account you use for connecting HCP Terraform must have admin access to any shared repositories of Terraform configurations because since creating webhooks requires admin permissions. Refer to Requirements for additional information.
  3. Open the SSH keys page and click the profile icon.
  4. Choose Manage account.
  5. Click SSH keys or enter https://<BITBUCKET INSTANCE HOSTNAME>/plugins/servlet/ssh/account/keys in the address bar to go to the SSH keys screen.
  6. Click Add key and enter the SSH public key you created in Create an SSH key for Terraform into the text field. Open the .pub file to get the key value.
  7. Click Add key to finish adding the key.

Add an SSH private key

Complete the following steps in HCP Terraform or Terraform Enterprise to request access to Bitbucket and add the SSH private key.

  1. Open the SSH keys settings page and click Add a private SSH key. A large text field appears.
  2. Enter the text of the SSH private key you created in Create an SSH key for Terraform and click Add SSH Key.

Next steps

After completing these instructions, you can create Terraform workspaces based on your organization's shared repositories. Refer to the following resources for additional guidance: