» Configuring Bitbucket Cloud Access
These instructions are for using Bitbucket Cloud for Terraform Enterprise (TFE)'s VCS features. Bitbucket Cloud is the cloud-hosted version of Bitbucket; self-hosted Bitbucket Server instances have separate instructions, as do the other supported VCS providers.
Connecting TFE to your VCS involves five steps:
|On your VCS||On TFE|
|Register your TFE organization as a new app. Get ID and key.|
|Tell TFE 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 Bitbucket Cloud-specific versions of these steps.
Note: Alternately, you can skip the OAuth configuration process and authenticate with an app password. This requires using TFE's API. For details, see the OAuth Clients API page.
» Step 1: On Bitbucket Cloud, Create a New OAuth Consumer
Open Bitbucket Cloud in your browser and log in as whichever account you want TFE 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 TFE must have admin access to any shared repositories of Terraform configurations, since creating webhooks requires admin permissions.
Navigate to Bitbucket's "Add OAuth Consumer" page.
This page is located at
https://bitbucket.org/account/user/<YOUR USERNAME>/oauth-consumers/new. You can also reach it through Bitbucket's's menus:
- In the lower left corner, click your profile picture and choose "Bitbucket settings."
- In the settings navigation, click "OAuth," which is in the "Access Management" section.
- On the OAuth settings page, click the "Add consumer" button.
This page has a form with four text fields and many checkboxes.
Fill out the text fields as follows:
Field Value Name Terraform Enterprise (
<YOUR ORGANIZATION NAME>)
Description Any description of your choice. Callback URL
https://example.com/replace-this-later(or any placeholder; the correct URI doesn't exist until the next step.)
https://app.terraform.io(or the URL of your private TFE install)
Ensure that the "This is a private consumer" option is checked. Then, activate the following permissions checkboxes:
Permission type Permission level Account Write Repositories Admin Pull requests Write Webhooks Read and write
Click the "Save" button, which returns you to the OAuth settings page.
Find your new OAuth consumer under the "OAuth Consumers" heading, and click its name to reveal its details. Take note of two items: the Key and the Secret. You'll copy and paste these unique strings in the next step. Leave this page open in a browser tab.
» Step 2: On TFE, Add an OAuth Client
Open TFE in your browser and navigate to the "OAuth Configuration" settings for your organization. Click the "Add an OAuth Client" 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 "
<ORGANIZATION>Settings" link, right below the name of your organization.
- On the next page, click "OAuth Configuration" in the left sidebar.
- Click the "Add an OAuth Client" button.
The next page has a drop-down and four text fields. Select "Bitbucket Cloud" from the drop-down, and enter the Key and Secret from the previous step. (Ignore the two disabled URL fields, which are used for on-premise VCSs.)
Click "Create connection." This will take you back to the OAuth Configuration page, which now includes your new Bitbucket 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 Bitbucket Cloud, Update the Callback URL
Go back to your Bitbucket Cloud browser tab. (If you accidentally closed it, you can reach your OAuth settings page through the menus: use the lower left menu > Bitbucket settings > OAuth.)
Locate your TFE OAuth consumer. Click the elipsis ("...") button on the far right, and choose "Edit" from the menu.
In the "Callback URL" field, paste the callback URL from TFE's OAuth Configuration page, replacing the "example.com" placeholder you entered earlier.
Click the "Save" button. A banner saying the update succeeded should appear.
» Step 4: On TFE, Request Access
Go back to your TFE browser tab and click the "Connect organization
<NAME>" button on the OAuth Configuration page.
This takes you to a page on Bitbucket Cloud, asking whether you want to authorize the app.
Click the green "Authorize" button at the bottom of the authorization page. This returns you to TFE's OAuth Configuration page, where the Bitbucket Cloud client's information has been updated.
At this point, Bitbucket Cloud access for TFE is fully configured, and you can create Terraform workspaces based on your organization's shared repositories.