Connect Bitbucket

A Bitbucket connection lets Faustine read the repositories it analyzes on Bitbucket Cloud. You create it in the Connect your code step when you create a Web Agent or create an API. The connection acts as the Bitbucket user who authorized it, and other agents and APIs in the workspace can reuse it.

What Faustine asks for

Faustine connects through OAuth. Bitbucket's consent page lists the access it requests.

Access	Used for
Read your account	Naming the connection after the user who authorized it.
Read your repositories	Listing workspaces, repositories and branches, reading files for the Advanced editor, and cloning the repository for analysis.
Webhooks	Creating the push webhook that automatic updates need.

Faustine does not push to your repositories.

Faustine stores the refresh token Bitbucket issues, encrypted, and exchanges it for a short-lived access token each time it needs to read.

To connect:

In the Connect your code step, select Bitbucket.
Select Connect Bitbucket. The browser goes to Bitbucket.
On Bitbucket, sign in as a user who can read the repositories you want analyzed, and grant access.

Bitbucket sends you back to the wizard with the new connection selected. It appears under Bitbucket connections as OAuth with the user's name.

Bitbucket has no personal access token option in Faustine.

Pick a repository and branch

With a connection selected:

In Repository, select a repository from the list. The list covers every Bitbucket workspace the user belongs to. To type it instead, select Enter owner/repo manually and enter it as workspace/repository.
In Branch, select a branch. Faustine preselects the repository's default branch. An empty branch also means the default branch.
For a monorepo, set the folder Faustine analyzes. The field is Frontend path for a Web Agent and API path for an API. Leave it empty for the repository root.

Automatic updates

When you turn on automatic updates for an agent, Faustine creates a push webhook on the Bitbucket repository. See Keep the agent up to date.

Disconnect

To delete a connection, open the Connect your code step of a new Web Agent or a new API, select the provider, and select the delete button on the connection's row. A connection that a Web Agent or an API uses cannot be deleted until you connect them to another source. Faustine also removes the webhooks it created on your repositories.

You can also revoke Faustine's access in your Bitbucket account settings. Analyses of that connection's repositories then fail until you connect again.

Troubleshooting

Symptom	Cause	Fix
A repository is not in the list	The Bitbucket user who authorized Faustine cannot read it.	Connect again as a user with access to the repository.
The agent shows `Your Bitbucket connection predates auto-update and can't create the push webhook`	The connection was authorized before Faustine requested webhook access.	Select Re-connect and grant access again.
`Couldn't load repositories`	The access was revoked on Bitbucket.	Connect again.

Next steps

Connect your code: the rest of the step for a Web Agent.
Keep the agent up to date: update the agent on every push.
Upload a ZIP instead of a repository: analyze code without a connection.