Group repositories into projects

Bitbucket Cloud projects make it easier for members of a workspace to focus on a goal, product, or process by organizing your repositories into projects.

Only workspace administrators can create a project.

Private and public projects

Projects can be either visible or hidden from public view. Access to the members of your workspace, and the repositories in the project, are what determines access to the project itself.

Private projects

  • Can only contain private repositories.

  • Repositories and their associated wiki and issue tracker will only be visible to people who have access to the repository in question.

  • The title and details of a private project will only be visible to members of the workspace and people who have access to a repository in the project.

Public projects

  • Are visible to anyone. However the repositories contained in a public project can be private and hidden from public view.

  • Allow you to host public issue trackers and wiki's in public repositories.

Create a project

Every workspace that has projects enabled will have an initial untitled project which contains all the workspace's repositories. To start, give this initial project a meaningful name which you can reference as you create new projects and begin moving repositories. You must have workspace administration permissions to create projects.

To create a project:

  1. Click + in the global sidebar and select Project under Create a new. The Create a project page appears.

  2. Select the Workspace for the project. 

  3. Give the project a Name that is short and easily identifies the work your team will do in the project. The project name populates menus and dashboards.

  4. Note or modify the Key field. The key acts as a unique identifier used in the project URL.

  5. Add a meaningful description which describes the focus of the project. You can see the project description when viewing a list of projects.

  6. Select This is a private project if you only want the project name displayed to members of your workspace. For more information see, Private and public projects.

  7. Click Change avatar to add or change a custom avatar.

  8. Click Create project.

You can now add repositories to the project you just created using either the Create repository or Add existing repositories


Add repositories to a project

If you want to add a repository to a project it must already be in the workspace. To change ownership of a repository see Transfer repository ownership.

There are several ways to add repositories to a project:

  • In a new project you can use the Add existing repositories link, which will display a list of repositories in that workspace.

  • In the repository settings you can change the Project field to a different project, which will move the repository to that project.

  • Use the Create repository link on the Projects dashboard or from the Repositories menu. Once you have projects enabled you'll have to select a project for every new repository.

You cannot move a public repository to a private project.

To add an existing repository to a project

  1. Navigate to the repository you want to add to your project.

  2. Click Repository settings in the sidebar.

  3. Select the project from the Project menu, where you want to move the repository.

  4. Click Save repository details

You'll see that the project changes in the breadcrumb links at the top of the page. Click the second link to navigate to the project recently assigned to the repository.

Find and share projects

The quickest way to find a project you are currently working on is to click Projects in the left navigation sidebar and then select the project that you are working on from the list.

Find a project in a workspace:

  1. From your avatar in the bottom left, select the workspace or click All workspaces for a full list from which to choose.

  2. Click Projects in the sidebar.

  3. Select the project you want to view.

Finding the project from the breadcrumb links in a repository

If you know the repository you're looking for, but not the project, just navigate to the repository and in the breadcrumb links at the top of the page you will see: the workspace name / the project name / the repository name. Just click on the project name to see the project landing page and any repositories in the project to which you have access.

Sending a project link to someone

You can copy the URL of the project landing page and send that link to anyone that can access the project. The format of the link should look similar to this example:

Manage and edit existing projects

You can change your projects avatar, privacy setting, name, key, and description with a few simple steps.

To modify project settings

  1. Navigate to the project you want to modify.

  2. Click Project settings in the sidebar.

  3. Do one of the following:

    1. Select the Name field to modify the name of the project. Remember this will modify how the project appears in menus and dashboards so be sure the members of the workspace are aware of the changes.

    2. Select the Key field to modify the project key. The key acts as a unique identifier for the project for menu, dashboard, and breadcrumb links.

      Note: During this initial release of projects changing the Key field has a very low to no impact on your project and how Bitbucket functions. However the key will become a more important attribute as we continue to improve projects.

    3. Select the Description field to modify the project description. The description appears on dashboards and the project landing page.

    4. Select or clear the Privacy box to change the status of the project. A project is private when you select the option.

    5. Click Change avatar, then drag an image (*.png, *.jpg, or *.gif) into the field, and click Save to add a custom avatar.

Delete a project

To delete a project first you must remove or delete all the repositories contained within the project. Once you've done that you can delete the project by doing the following:

  1. Navigate to the project you want to modify.

  2. Click Project settings.

  3. Click Delete project located in the upper right of the page, then Delete in the confirmation dialog.

Last modified on Dec 29, 2020
Cached at 9:04 PM on Oct 23, 2021 |

Additional Help