Help Center

Bitbucket Integration

Connect Bitbucket webhooks so commits and pull requests appear in issue activity.

Before you start

  • Git integrations are available on Team plan workspaces.
  • You need workspace permission to manage integrations.
  • Create the repository connection in Ouraboard first, then configure Bitbucket webhook.
  • Repository owner and name must match Bitbucket workspace/repository exactly.

Step 1: Connect repository in Ouraboard

  1. Open Workspace Settings → Git.
  2. Set provider = Bitbucket.
  3. Fill:
    • Repository owner (for bitbucket.org/acme/my-repo it is acme)
    • Repository name (for bitbucket.org/acme/my-repo it is my-repo)
    • Webhook secret (or use Generate)
    • Default branch (usually main)
  4. Click Connect.
  5. Copy full Webhook URL from connected repository row.

Step 2: Create Bitbucket webhook

  1. Open repository in Bitbucket.
  2. Go to Repository settings → Webhooks.
  3. Create webhook and paste URL copied from Ouraboard.
  4. Add the same secret value you set in Ouraboard.
  5. Select events:
    • Repository push
    • Pull request created / updated / merged
  6. Save webhook.

Step 3: Verify end-to-end

  1. Create or pick issue in Ouraboard (example slug: PRJ-123).
  2. Push commit with slug in message (example: fix: PRJ-123 bitbucket test).
  3. Optionally create PR with slug in title or description.
  4. Open issue → Development tab and verify linked activity.

Issue linking rule

Use issue slug in commit messages or pull request text (example: PRJ-123) to attach activity to the issue.

Recommended commit formats

  • fix: PRJ-123 correct webhook signature check
  • feat(PRJ-456): add PR auto-move guard
  • docs: update setup notes [PRJ-789]

If no issue slug is found, the push/PR is stored but not linked to any issue.

Default branch behavior

  • Issue linking works on any branch.
  • Default branch is used only when branch guard for auto-move is enabled.

Security checks

  • Incoming signature/secret must match.
  • Unregistered repositories are rejected.
  • Duplicate payloads are ignored.

Troubleshooting

  • Webhook repository does not match configured integration: check owner/repo fields in Ouraboard against Bitbucket repository URL.
  • 401/403 signature or secret failures: ensure webhook secret is identical in both systems.
  • No issue linked: verify commit/PR includes issue slug (for example PRJ-123).
  • If only branch-like strings are detected, review commit format and keep slug explicit in message title.

Screenshot

Bitbucket add new webhook form
Bitbucket webhook form — add URL, secret, and enable Push + Pull request triggers.