What Norma can do — and cannot do #

When you authorise Norma on Bitbucket, we request read-only access to your repository contents. Specifically, Norma can:

• Read source files in the repositories your account or workspaces grant access to.
• List your repositories and branches (to populate the picker when you add a new repo).
• Read pull request metadata for the Pro tier’s PR scanning feature, when applicable.

Norma cannot:

• Push commits, open pull requests, or write to your code in any way.
• Access repositories outside the Bitbucket workspaces you authorised.
• Read your personal email, billing, or admin settings.
• Persist your code beyond the duration of a scan — clones are deleted as soon as the scan finishes.

Norma connects to Bitbucket Cloud through OAuth, with read-only access to the repositories you choose. You can connect both public and private repos. Bitbucket Server (self-hosted) is not yet supported.

Connecting for the first time #

1. From the Repositories page, click + Add Repository in the top right.
2. Click Connect Bitbucket. You’re redirected to bitbucket.org to authorise Norma.
3. On the Bitbucket authorisation screen, review the permissions requested and click Grant access.
4. You’re back in Norma on the Select repository screen, which lists every repository Norma can now see across your authorised Bitbucket workspaces.
5. Pick a repository to scan first.

The Bitbucket connection is saved at the Norma workspace level, so subsequent + Add Repository flows skip straight to picking a repo.

Bitbucket workspaces vs Norma workspaces #

Bitbucket organises repositories under workspaces (which used to be called “teams”). Norma also has the concept of a workspace, but they’re separate things:

• A Bitbucket workspace is a group of repositories on Bitbucket — e.g. acme-engineering.
• A Norma workspace is a group of Norma repositories — e.g. your Personal workspace, or an Acme Engineering workspace on a Pro plan.

When you authorise Norma on Bitbucket, you can grant access to one or more Bitbucket workspaces. Repositories from any of them can then be added to any Norma workspace you belong to. The mapping is many-to-many.

Adding more repositories later #

If Norma already has a Bitbucket connection in this workspace, + Add Repository skips OAuth and goes straight to the Select repository screen.

If the repository you want is missing, the most common reason is that you haven’t granted Norma access to the Bitbucket workspace it lives in. Re-run the connection flow and add the missing workspace.

Changing which workspaces or repositories Norma can see #

1. Go to bitbucket.org → Personal settings → Application authorizations.
2. Find Norma in the list.
3. Click Revoke, then re-authorise from Norma if you want to change the workspace scope.

Bitbucket doesn’t expose per-repository fine-grained access for OAuth apps the way GitHub does, so revoke-and-reconnect is the way to change scope.

Revoking Norma’s access #

To remove Norma’s access entirely:

1. bitbucket.org → Personal settings → Application authorizations.
2. Click Revoke next to Norma.

Norma stops being able to read any Bitbucket code. Existing scan history is preserved; no future scans will run until you reconnect.

Troubleshooting #

The repository I want is not in the picker.
The repository’s Bitbucket workspace isn’t authorised. Revoke and re-authorise; on the consent screen, make sure the right workspace is included.

OAuth fails with “Could not connect to Bitbucket”.
Most often this is a cookie or multi-account issue. Try in an incognito window. Atlassian SSO can also interfere if your account is part of an enterprise Atlassian organisation — talk to your IT admin.

A scan fails with a permissions error.
You’ve revoked Norma’s access since the repository was imported. Re-authorise on Bitbucket.

I have Bitbucket Server / Data Center (self-hosted), not Bitbucket Cloud.
Self-hosted Bitbucket isn’t supported yet. If you need it, get in touch — it’s on the roadmap.

Related #

• Connect GitHub — the parallel walkthrough for GitHub.
• Repositories overview — what to do once you’ve connected your first repo.
• Repository providers — the high-level reference covering all providers.