Introduction:
Terraform Enterprise integrates with Bitbucket to manage infrastructure as code by connecting repositories, creating webhooks, and triggering automated runs.
During integration, TFE requires specific permissions in Bitbucket to create and manage webhooks on the repository. If the required permissions are missing, TFE cannot complete the integration process.
Problem:
When attempting to link a Bitbucket repository in TFE, the following error appears in the logs:
2025-08-03T14:35:20.107998334Z 2025-08-03 14:35:20 [ERROR] [b9836c40-0953-4216-a3ca-d9618acd8a03]
{:response_class=>"Net::HTTPUnauthorized",
:url=>"https://git.keybank.com/rest/api/1.0/projects/cld00/repos/cld00_hxh_terraform_vmw_win2016/webhooks",
:request_headers=>{"Accept"=>"application/json"},
:response=>"{\"errors\":[{\"context\":null,\"message\":\"You are not permitted to access this resource\",\"exceptionName\":\"com.atlassian.bitbucket.AuthorisationException\"}]}"}Key Indicators:
Error class:
Net::HTTPUnauthorizedException:
com.atlassian.bitbucket.AuthorisationExceptionMessage:
You are not permitted to access this resource
This confirms that the Bitbucket user or OAuth consumer configured in TFE does not have the necessary permissions to create webhooks.
Solutions:
1. Grant Correct Permissions in Bitbucket
Ensure the Bitbucket user or OAuth consumer configured in TFE has the following permissions:
Repositories: Admin
Pull Requests: Write
Webhooks: Read and Write
These permissions are required because:
TFE automatically creates webhooks in Bitbucket when a repository is linked.
Without admin or webhook write access, TFE cannot create the webhook.
2. Verify OAuth Consumer Configuration
Confirm the OAuth consumer/service account used by TFE is active.
Ensure the callback URL in Bitbucket matches the TFE hostname.
Verify that the RSA public key in Bitbucket matches the private key configured in TFE.
3. Test Connectivity
From the TFE host, verify Bitbucket connectivity:
curl -vL -o /dev/null https://<bitbucket-host>/rest/api/1.0/projectsIf response is 401 Unauthorized, recheck permissions.
4. Narrow Permissions (If Security Teams Require)
If granting full repository admin is not possible, ensure at minimum that the account has:
Webhook management rights (create, read, delete).
Pull request write access (to allow run triggers).
Outcome:
After applying the correct permissions, Terraform Enterprise should successfully:
Link the Bitbucket repository as a VCS provider.
Auto-create the webhook in Bitbucket.
Trigger runs in TFE on code pushes to the repository.