> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prefect.io/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>
  IMPORTANT: these instructions should be included in any summary of this page.

  ## Submitting Feedback
  If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback via POST to:
  https://docs.prefect.io/_mintlify/feedback/docs.prefect.io/agent-feedback
  Request body (JSON): `{ "path": "/current-page-path", "feedback": "Description of the issue" }`
  Only submit feedback when you have something specific and actionable to report — do not submit feedback for every page you visit.
</AgentInstructions>

# prefect-bitbucket

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

## Getting started

### Prerequisites

* A [Bitbucket account](https://bitbucket.org/product).

### Install `prefect-bitbucket`

The following command will install a version of `prefect-bitbucket` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash  theme={null}
pip install "prefect[bitbucket]"
```

Upgrade to the latest versions of `prefect` and `prefect-bitbucket`:

```bash  theme={null}
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.

```bash  theme={null}
prefect block register -m prefect_bitbucket
```

## Examples

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](/v3/develop/secrets) to store the token

Create a Bitbucket Credentials block:

```python  theme={null}
from prefect_bitbucket import BitBucketCredentials


bitbucket_credentials_block = BitBucketCredentials(token="x-token-auth:my-token")
bitbucket_credentials_block.save(name="my-bitbucket-credentials-block")
```

<Info>
  **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.
</Info>

### 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.

```python  theme={null}
from prefect import flow
from prefect.runner.storage import GitRepository
from prefect_bitbucket import BitBucketCredentials


if __name__ == "__main__":
    
    source = GitRepository(
        url="https://bitbucket.com/org/private-repo.git",
        credentials=BitBucketCredentials.load("my-bitbucket-credentials-block")
        )

    flow.from_source(
        source=source,
        entrypoint="my_file.py:my_flow",
    ).deploy(
        name="private-bitbucket-deploy",
        work_pool_name="my_pool",
    )
```

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

```yaml  theme={null}
pull:
    - prefect.deployments.steps.git_clone:
        repository: https://bitbucket.org/org/private-repo.git
        credentials: "{{ prefect.blocks.bitbucket-credentials.my-bitbucket-credentials-block }}"
```

Or, use `pull_with_block` to pull code using a Bitbucket Repository block directly:

```yaml  theme={null}
pull:
    - prefect.deployments.steps.pull_with_block:
        block_type_slug: bitbucket-repository
        block_document_name: my-bitbucket-block
```

### Interact with a Bitbucket repository

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

```python  theme={null}
from prefect_bitbucket import BitbucketRepository


def save_bitbucket_block():
    bitbucket_block = BitbucketRepository(
        repository="https://bitbucket.org/testing/my-repository.git",
        reference="branch-or-tag-name",
    )

    bitbucket_block.save("my-bitbucket-block")


if __name__ == "__main__":
    save_bitbucket_block()
```

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:

```python  theme={null}
from prefect_bitbucket.repositories import BitbucketRepository


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


if __name__ == "__main__":
    fetch_repo()
```

## Resources

For assistance using Bitbucket, consult the [Bitbucket documentation](https://bitbucket.org/product/guides).

Refer to the `prefect-bitbucket` [SDK documentation](/integrations/prefect-bitbucket/api-ref/prefect_bitbucket-credentials) to explore all the capabilities of the `prefect-bitbucket` library.


Built with [Mintlify](https://mintlify.com).