Bitbucket Integration
Connect your Bitbucket account to Devpilot via OAuth to deploy code and enable automatic deployments via repository webhooks.
Bitbucket Integration
The Bitbucket integration links your Bitbucket Cloud account to a Devpilot workspace using OAuth. Once connected, Devpilot can list your repositories and branches, pull source code for deployments, and register repository webhooks so deployments run automatically when you push.
Prerequisites
- A Bitbucket Cloud account with access to the repositories you want to deploy
- Admin permission on repositories where Devpilot should register webhooks
- An active Devpilot workspace
Connecting Bitbucket
Open Integration Settings
Navigate to Workspace Settings > Integrations and select Connect on the Bitbucket card under Source Control.
Authorize Devpilot on Bitbucket
Review the permissions Devpilot requests on Bitbucket's consent screen and select Grant access.
Confirm the Connection
Bitbucket redirects you back to Devpilot. The Integrations page shows Bitbucket as connected along with the Bitbucket username linked to the integration.
Bitbucket issues short-lived access tokens with refresh tokens. Devpilot refreshes your token automatically — you do not need to reconnect unless you revoke access from Bitbucket's Personal settings > App authorizations page.
Permissions Granted
Devpilot requests the following Bitbucket OAuth scopes:
| Scope | Why Devpilot needs it |
|---|---|
repository | Read repository content, branches, and metadata for deployments. |
account | Read your Bitbucket account details to label the integration. |
webhook | Register repository webhooks so pushes trigger deployments. |
Using Bitbucket for Deployments
Selecting a Repository and Branch
On the deployment form, the repository selector shows every Bitbucket repository accessible through the integration. Search by name to narrow the list. Branches are loaded live from Bitbucket after you pick a repository.
Build and Deploy
Devpilot clones the selected branch each time a deployment runs so the latest code is always used.
Webhook Support
How Webhooks Work
When auto-deploy is enabled, Devpilot registers a Bitbucket repository push webhook. Each push to the watched branch triggers a new deployment.
Enabling Webhooks
Toggle Auto-deploy on push in the deployment form and pick the branch to watch. Devpilot handles the webhook registration on your behalf.
You need Admin permission on the Bitbucket repository for webhook registration to succeed. Collaborators without admin access should request that a repository admin either grant them admin permission or add the webhook manually.
Troubleshooting
Repositories Not Appearing
- The integration only lists repositories your Bitbucket user can access. Request access for any missing repository from its admin.
- If you recently joined a workspace, refresh the deployment form so Devpilot re-fetches the repository list.
Token Errors
- If Devpilot reports the Bitbucket token is expired, open the integration and select Refresh Token. If the refresh fails, remove and reconnect the integration.
Webhook Delivery Failures
- Open Bitbucket > Repository settings > Webhooks and review the View requests log for each webhook to see the HTTP response from Devpilot.
- Confirm the pushed branch matches the branch configured on the deployment.
Disconnecting Bitbucket
Go to Workspace Settings > Integrations, open the Bitbucket integration, and select Remove. The stored access and refresh tokens are deleted. Existing webhooks created on Bitbucket repositories are not removed automatically — delete them manually from each repository's webhook settings.