- Real-time pull request checks — immediate scanning of new PRs.
- Inline feedback — actionable suggestions attached directly to your diffs.
- Automatic webhooks — event-driven architecture with no manual webhook setup required.
Step 1: Create the integration account
Register the account
Log out of your personal Bitbucket account and create a new user specifically for this integration.
Finalize the profile
- Set the username to something identifiable, such as
GPRABot. - Use a team alias email rather than a personal address. - Enable Two-Step Verification (2FA) if required by your company policy.
When you rotate the service account later, update the token in Garth and
re-enable repository tracking — no other reconfiguration is needed.
Step 2: Create an API token
Authenticate as the service account
Ensure you are logged into Bitbucket using the dedicated Garth service account.
Open API token settings
Go to Personal settings and select API Tokens under the Access
Management section.
Select token scopes
Grant the following permissions:
| Group | Required scope | Purpose |
|---|---|---|
| Account | read:account | Validates user identity |
| User | read:user:bitbucket | Validates user identity |
| Workspace | read:workspace:bitbucket, admin:project:bitbucket | Confirms workspace association |
| Repositories | read:repository:bitbucket, write:repository:bitbucket | Scans diffs and manages webhooks |
| Pull requests | read:pullrequest:bitbucket, write:pullrequest:bitbucket | Receives PR events and posts review comments |
| Webhooks | read:webhook:bitbucket, write:webhook:bitbucket | Installs and manages webhooks automatically |
Step 3: Link to Garth
Open Garth integrations
Log into the Garth dashboard and navigate to Settings → Integrations.
Bind the token
Select the Bitbucket tab. Enter your Bitbucket URL
(
https://bitbucket.org/your-workspace), Username (the service account’s
email), and Personal Access Token, then click Validate.Install repositories
After validation, select the repositories you want Garth to review and click Install Repositories.
Automatic webhooks: Garth installs webhooks on selected repositories automatically. No manual webhook configuration is required. Webhooks are also removed automatically when you uninstall a repository.
Network configuration
If your infrastructure requires IP allowlisting, permit the following address through your firewall:Troubleshooting
Webhook issues
Webhook issues
If Garth is not accessing repositories or reviewing pull requests:
- Check webhook status — go to your Bitbucket repository settings and verify the Garth webhook exists and is active.
- Manually delete the webhook if it exists but is not working.
- Refresh the repository page in the Garth app.
- Reinstall the webhook — uninstall and reinstall the repository from the Garth dashboard.
Installation problems
Installation problems
If you cannot install Garth on a repository:
- Verify workspace membership — confirm the service account is in the Bitbucket workspace with at least
Developeraccess. - Check token scopes — confirm all required scopes (especially
admin:project:bitbucketandwrite:repository:bitbucket) are granted. - Re-validate the token — go to Settings → Integrations → Bitbucket in Garth and re-enter your credentials.
- Toggle the repository — uninstall and reinstall the repository from the Garth app to force a fresh webhook setup.
Authentication errors
Authentication errors
If you receive authentication or permission errors:
- Check token expiry — Bitbucket API tokens can expire; regenerate and update the token in Garth if needed.
- Confirm the username field — the Username entered during setup must be the service account’s email address, not a display name.
- Verify 2FA compatibility — if Two-Step Verification is enabled, confirm the API token was generated under Personal Settings → API Tokens, not via a password-based approach.
- Re-authenticate — update the token in the Bitbucket integration settings in Garth and re-link with a freshly generated token.