Set up and use packages

What are packages?

Packages bring artifact management directly into Bitbucket Cloud workflows. Development teams can publish, manage and consume packages, including container images, npm packages, and Maven packages which can all be linked to specific repositories.

• Packages are private by default. Private packages are only available to users with access to the linked repository.

• Internal packages let repository admins make a package readable by every member of a Bitbucket Cloud workspace, without giving them access to the linked repository.

The Bitbucket package registry offers:

• A workspace-level namespace for packages integrated directly into Bitbucket Cloud.

• Repository-linked packages that inherit repository permissions (Admin, Write, Read).

• A unified developer experience, where source code, pipelines, and artifacts live together in one place.

• Internal packages allow repository admins to make a package readable by every member of a Bitbucket Cloud workspace, without giving them access to the linked repository.

Internal packages and how they work

Packages are private by default. Private packages are only available to users with access to the linked repository. Use internal packages to share common packages across a workspace without needing to open the source repository to consumers.

When a repository admin marks a package as internal:

• Workspace members can view, pull, download, and install it.

  • Push, publish, delete, and visibility changes require you to have at least ‘write’ permissions on the repository.

• Members without access to the linked repository of the package don’t see it in breadcrumbs, URLs, or package details.

• The package appears without the private lock icon in both the workspace and repository package listings.

Authentication

You can authenticate with packages using an API token or natively through the Bitbucket Pipelines integration.

Create an Atlassian API token in Bitbucket

Publishing and consuming packages requires you to authenticate your client with an Atlassian API token.

1. To create an API token, visit https://id.atlassian.com/manage-profile/security/api-tokens and select Create API token with scopes.

2. Enter a name and expiry for the token.

3. Select the required scope read:package:bitbucket.

4. You can also select the write:package:bitbucket scope if you want the token to allow publishing packages to the registry.

Bitbucket Pipelines integration

To authenticate to the Bitbucket package registry within Bitbucket Pipelines, you can use the BITBUCKET_PACKAGES_USERNAME and BITBUCKET_PACKAGES_TOKEN environment variables available to each step in your Bitbucket Pipeline runs. These variables are scoped to the same repository where the pipeline is running, so they only grant access to packages within that repository. Learn more about using variables to integrate with Pipelines.

Permissions:

The package registry operates within a workspace with packages linked to individual repositories. Package permissions align with the following repository roles: Admin, Write, and Read as described below.

Trace package versions back to Bitbucket Pipelines

If you publish packages through Bitbucket Pipelines using the native Bitbucket Pipelines authentication flow, Bitbucket displays which pipeline published a package version. This helps your team trace a published artifact back to the automation that created it.

You can use this information to validate releases, investigate unexpected package changes, and improve confidence in your software delivery process.

Workspace deletion impact on package registry

When you delete a Bitbucket workspace, all packages in the workspace become inaccessible. However, the packages will remain in our systems for up to 30 days. You will not be charged for storage during this 30-day period.

Repository deletion impact on package registry

When you delete a Bitbucket repository, all packages linked to the repository become inaccessible. The packages will remain in our systems for up to 30 days. You will be charged for storage and will not be able to reuse those image names during this 30-day period.