How to Add a User to the Bitbucket Repository

You built the repo. Now your team needs in — but Bitbucket’s permission structure trips up almost everyone the first time.

Whether you’re onboarding a new developer, giving a client read-only access, or looping in a contractor for a sprint, getting user management right saves you from headaches like accidental overwrites, permission gaps, and security risks.

This guide walks you through every method — workspace level, project level, and repo level — so you can add users exactly the right way, every time.

Why Bitbucket User Management Actually Matters

It’s tempting to just toss someone into a repo and move on. But Bitbucket’s permission layers exist for a reason.

According to Atlassian’s own data, over 10 million developers use Bitbucket to collaborate on code — and most collaboration failures trace back to misconfigured access, not technical breakdowns.

A few things go wrong when you skip proper user management:

• Developers push to branches they shouldn’t touch
• Contractors see sensitive environment configs
• Clients accidentally break staging pipelines
• Audit trails become impossible to reconstruct

Getting permissions right from day one isn’t bureaucracy — it’s how high-functioning teams protect their work.

Understanding Bitbucket’s Permission Structure

Before you add anyone, understand where permissions live. Bitbucket has three layers:

Workspace Level — Controls who can access your entire Bitbucket workspace. Anyone you add here can potentially see all repos unless repo-level restrictions are applied.

Project Level — Groups multiple repos under one umbrella. Useful for agencies, enterprise teams, or anyone managing multiple products under one workspace.

Repository Level — The most granular control. You set per-person permissions for a specific repo only.

Each layer has its own roles:

Pick the right level before you start. Adding someone at workspace level when you only need repo access is one of the most common mistakes teams make.

How to Add a User to a Bitbucket Repository (Step-by-Step)

Add a User at the Repository Level

This is the most common scenario — you want one person to access one specific repo.

Step 1 — Open Your Repository

Log into Bitbucket Cloud. From the left sidebar, navigate to the repository you want to share.

Step 2 — Go to Repository Settings

Click Settings in the left navigation menu inside the repo. This only appears if you have Admin access to that repo.

Step 3 — Click “User and Group Access”

Under the Access management section, select User and group access.

Step 4 — Add the User

In the Users field, type the person’s Atlassian account email or username. Bitbucket will suggest matching accounts.

Select the correct user from the dropdown.

Step 5 — Assign a Permission Level

Choose from:

• Read — view-only access
• Write — can push code
• Admin — full control of repo settings

Step 6 — Save

Click Add. The user receives an email notification with access instructions.

That’s it. They can now clone, push (if Write or Admin), and collaborate immediately.

Add a User at the Workspace Level

Need someone to access multiple repos across your workspace? Add them at the workspace level instead of repo-by-repo.

Step 1 — Open Workspace Settings

Click your workspace avatar in the bottom-left corner. Select Settings from the menu.

Step 2 — Go to “Members”

In the left sidebar under User management, click Members.

Step 3 — Invite a Member

Click the Invite members button. Enter the email address of the person you want to add.

Step 4 — Assign a Workspace Role

• Member — standard access, subject to individual repo permissions
• Admin — can manage workspace settings, billing, and all repos

Step 5 — Send the Invite

Click Send invite. The user gets an email to accept. Once they accept, they’re part of the workspace.

Note: Adding someone to the workspace doesn’t automatically give them access to all repos. You still control access at the repo level.

Add a User to a Bitbucket Project

If you use Bitbucket Projects to organize related repos, you can add users at the project level so they automatically inherit access to all repos in that project.

Step 1 — Navigate to the Project

From your workspace, go to Projects and open the relevant project.

Step 2 — Open Project Settings

Click the Settings gear icon inside the project.

Step 3 — Select “User and Group Access”

Under project settings, find the User and group access section.

Step 4 — Add the User

Search for the user by name or email. Assign the appropriate permission (Read, Write, or Admin).

Step 5 — Save Changes

The user now has inherited access to every repo inside that project.

How to Add a Group Instead of Individual Users

Managing 10+ people? Don’t add them one by one. Use Groups.

Step 1 — Go to Workspace Settings → Groups

Navigate to your workspace settings and find the Groups section under User management.

Step 2 — Create a New Group

Click Create group. Name it something descriptive like “Frontend Team” or “Client Read Access.”

Step 3 — Add Members to the Group

Add the relevant users to this group.

Step 4 — Assign the Group to a Repo or Project

Go to the repo or project’s User and group access settings. Add the group and assign a permission level.

Every current and future member of that group automatically inherits those permissions — no manual re-adding required.

This approach is how teams that manage 50+ contributors keep permissions clean without chaos. According to Atlassian, teams using groups report 40% less time spent on access management compared to per-user permission management.

Bitbucket Server vs. Bitbucket Cloud: Key Differences

If you’re on Bitbucket Server (also called Bitbucket Data Center), the steps are slightly different:

On Bitbucket Server, an admin typically manages users from the Administration panel → User management → Users section. LDAP integration means users may already exist in your directory — you just assign them to repos or groups.

Common Errors When Adding Users (And How to Fix Them)

“User not found” error The person hasn’t created an Atlassian account yet. Ask them to sign up at atlassian.com first, then try again with their registered email.

“You don’t have permission to manage users” You need Admin access at the workspace or repo level. Ask your workspace admin to either elevate your permissions or add the user themselves.

User can see the repo but can’t push They were added with Read access. Go back to User and group access, find their name, and change the permission to Write.

Invite email never arrived Check spam folders first. If still missing, go to workspace Settings → Members, find the pending invite, and resend it.

User accepted invite but still can’t access the repo Workspace membership doesn’t equal repo access. Make sure you also added them at the repository level with the correct permission.

Security Best Practices for Bitbucket User Access

Getting users in is one thing. Keeping your repos secure is another.

Principle of least privilege — Always start with Read access. Upgrade to Write or Admin only when explicitly needed. Research shows that 74% of data breaches involve privilege abuse or excessive permissions (Verizon DBIR).

Audit access regularly — Remove users who’ve left your team or finished their contract. Dormant accounts are a security liability.

Use branch permissions — Even with Write access, you can restrict who can push directly to main or production branches. Set this under Repository Settings → Branch permissions.

Enable two-factor authentication — Bitbucket supports 2FA at the workspace level. Enforce it for all members — especially anyone with Admin permissions.

Review third-party app access — If you’ve connected CI/CD tools or bots, audit what OAuth scopes they hold. Overpermissioned integrations are a growing attack surface.

How Many Users Can You Add on Bitbucket?

Bitbucket Cloud’s pricing scales by the number of users:

If you’re on the Free plan and already have 5 users, you’ll need to upgrade before adding more. The upgrade process is straightforward from Workspace Settings → Plan.

For Bitbucket Server/Data Center, licensing is typically annual and based on total user tiers (10, 25, 50, 100+).

Conclusion

Adding a user to a Bitbucket repository is straightforward once you understand the three permission layers: workspace, project, and repository.

For one-off access, use repo-level permissions. For team-wide access, use workspace members and groups. For project-based access, set permissions at the project level and let inheritance do the work.

Always follow least-privilege principles, audit access regularly, and enforce two-factor authentication — especially for anyone with Admin rights.

Now that your team has the right access, you can ship faster, collaborate cleaner, and keep your codebase secure.