Skip to content


The prefect-bitbucket library makes it easy to interact with Bitbucket repositories and credentials.

Getting Started


Install prefect-bitbucket

pip install -U prefect-bitbucket

Register newly installed block types

Register the block types in the prefect-bitbucket module to make them available for use.

prefect block register -m prefect_bitbucket


In the examples below, you create blocks with Python code. Alternatively, blocks can be created through the Prefect UI.

Store deployment flow code in a private Bitbucket repository

To create a deployment and run a deployment where the flow code is stored in a private Bitbucket repository, you can use the BitbucketCredentials block.

A deployment can use flow code stored in a Bitbucket repository without using this library in either of the following cases:

  • The repository is public
  • The deployment uses a Secret block to store the token

Create a Bitbucket Credentials block:

from prefect_bitbucket import BitbucketCredentials

bitbucket_credentials_block = BitbucketCredentials(token="x-token-auth:my-token")"my-bitbucket-credentials-block")

Difference between Bitbucket Server and Bitbucket Cloud authentication

If using a token to authenticate to Bitbucket Cloud, only set the token to authenticate. Do not include a value in the username field or authentication will fail. If using Bitbucket Server, provide both the token and username values.

Access flow code stored in a private Bitbucket repository in a deployment

Use the credentials block you created above to pass the Bitbucket access token during deployment creation. The code below assumes there's flow code stored in a private Bitbucket repository.

from prefect import flow
from import GitRepository
from prefect_bitbucket import BitbucketCredentials

if __name__ == "__main__":

Alternatively, if you use a prefect.yaml file to create the deployment, reference the Bitbucket Credentials block in the pull step:

    - prefect.deployments.steps.git_clone:
        credentials: "{{ }}"

Interact with a Bitbucket repository

The code below shows how to reference a particular branch or tag of a Bitbucket repository.

from prefect_bitbucket import BitbucketRepository

def save_bitbucket_block():
    bitbucket_block = BitbucketRepository(

if __name__ == "__main__":

Exclude the reference field to use the default branch. Reference a BitbucketCredentials block for authentication if the repository is private.

Use the newly created block to interact with the Bitbucket repository.

For example, download the repository contents with the .get_directory() method like this:

from prefect_bitbucket.repositories import BitbucketRepository

def fetch_repo():
    bitbucket_block = BitbucketRepository.load("my-bitbucket-block")

if __name__ == "__main__":


For assistance using Bitbucket, consult the Bitbucket documentation.

Refer to the prefect-bitbucket API documentation linked in the sidebar to explore all the capabilities of the prefect-bitbucket library.