# Bitbucket Cloud
This page covers how to configure Pipelines-as-Code with Bitbucket Cloud through a webhook. Use this method to run Tekton pipelines triggered by pull requests and push events on repositories hosted on bitbucket.org.

## Prerequisites

- A running Pipelines-as-Code [installation](/docs/installation/installation.md)
- A Bitbucket Cloud scoped API token or repository access token (see below)
- The public URL of your Pipelines-as-Code controller route or ingress endpoint

## Create a Bitbucket Cloud API token

Bitbucket Cloud app passwords are deprecated. Use a scoped API token for new
setups and rotate existing app passwords to API tokens.

Follow the
[Bitbucket Cloud API token guide](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/)
to create an API token with scopes. Select **Bitbucket** as the app when
creating the token.

Check these boxes to add the permissions to the token:

- **read:workspace:bitbucket**
- **read:pullrequest:bitbucket**
- **read:repository:bitbucket**
- **write:repository:bitbucket**
- **write:webhook:bitbucket**

> [!NOTE]
>
> 
> Note: if you're contributing to PaC and want to run PaC E2E test locally you
> need one more permission, **write:pullrequest:bitbucket**, to create pull
> requests in E2E tests.
> 


Store the generated token in a safe place. Bitbucket Cloud shows it only once.

### Repository access tokens

You can use a [repository access token](https://support.atlassian.com/bitbucket-cloud/docs/create-a-repository-access-token/) instead of a personal API token. .

Grant these permissions when you create the token:

- **Repository: Read**
- **Pull requests: Read**
- **Repository: Write**
- **Webhooks: Write**

> [!WARNING]
>
> 
> A repository access token cannot list workspace members, so workspace
> membership does not let a pull request author run PipelineRuns. Add the author's
> Bitbucket account ID to the `OWNERS` or `OWNERS_ALIASES` file on the default
> branch, or ask someone listed there to comment `/ok-to-test` on the pull
> request.
> 


To find a user's account ID, use one of these:

- When Pipelines-as-Code blocks a pull request, it records a
  `RepositoryPermissionDenied` event in the Repository namespace with the
  author's nickname and account ID:

  ```bash
  kubectl get events -n <namespace> --field-selector reason=RepositoryPermissionDenied
  ```

- Users can look up their own account ID with a personal API token that has
  the **read:user:bitbucket** scope:

  ```bash
  curl -s -u "<email>:<api-token>" https://api.bitbucket.org/2.0/user | jq -r .account_id
  ```

- The repository access token can read the author of a pull request:

  ```bash
  curl -s -H "Authorization: Bearer <access-token>" \
    https://api.bitbucket.org/2.0/repositories/<workspace>/<repository>/pullrequests/<id> \
    | jq -r .author.account_id
  ```

> [!NOTE]
>
> 
> The Repository CR still requires `git_provider.user` when you use a repository
> access token. Pipelines-as-Code only writes the value to its logs and never
> sends it to Bitbucket.
> 


## Webhook Configuration using the CLI

Use the [`tkn pac create repo`](/docs/cli.md) command to
configure a webhook and create the Repository CR in one step.

You need a scoped Bitbucket Cloud API token. `tkn pac` uses this token to
configure the webhook and stores it in a secret in the cluster, which the
Pipelines-as-Code controller uses for accessing the repository.

Below is the sample format for `tkn pac create repo`

```shell script
$ tkn pac create repo

? Enter the Git repository url (default: https://bitbucket.org/workspace/repo):
? Please enter the namespace where the pipeline should run (default: repo-pipelines):
! Namespace repo-pipelines is not found
? Would you like me to create the namespace repo-pipelines? Yes
✓ Repository workspace-repo has been created in repo-pipelines namespace
✓ Setting up Bitbucket Webhook for Repository https://bitbucket.org/workspace/repo
? Please enter your Bitbucket Cloud Atlassian account email:  <email@example.com>
ℹ ️You now need to create a Bitbucket Cloud API token with scopes, please checkout the docs at https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/ for the required permissions
? Please enter the Bitbucket Cloud API token:  ************************************
👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.awscl2.aws.ospqa.com
? Do you want me to use it? Yes
✓ Webhook has been created on repository workspace/repo
🔑 Webhook Secret workspace-repo has been created in the repo-pipelines namespace.
🔑 Repository CR workspace-repo has been updated with webhook secret in the repo-pipelines namespace
ℹ Directory .tekton has been created.
✓ A basic template has been created in /home/Go/src/bitbucket/repo/.tekton/pipelinerun.yaml, feel free to customize it.
ℹ You can test your pipeline by pushing the generated template to your git repository

```

## Webhook Configuration (Manual)

If you prefer to configure the webhook yourself, follow these steps.

- From the left navigation pane of your Bitbucket Cloud repository, go to **Repository settings** -->
  **Webhooks** tab and click on the **Add webhook** button.

  - Set a **Title** (i.e: Pipelines-as-Code)

  - Set the **URL** to the Pipelines-as-Code controller public URL. On OpenShift, get the public URL of the Pipelines-as-Code
  controller like this:

    ```shell
    echo https://$(oc get route -n pipelines-as-code pipelines-as-code-controller -o jsonpath='{.spec.host}')
    ```

  - The individual events to select are:
    - Repository -> Push
    - Repository -> Updated
    - Repository -> Commit comment created
    - Pull Request -> Created
    - Pull Request -> Updated
    - Pull Request -> Merged
    - Pull Request -> Declined
    - Pull Request -> Comment created
    - Pull Request -> Comment updated

[Refer to this screenshot](/images/bitbucket-cloud-create-webhook.png) to verify you have properly configured the webhook.

- Click on **Save**.

### Create the Secret

Create a Kubernetes secret containing your API token in the `target-namespace`
(the namespace where your pipeline CI runs):

```shell
kubectl -n target-namespace create secret generic bitbucket-cloud-token \
        --from-literal provider.token="BITBUCKET_CLOUD_API_TOKEN" \
        --from-literal webhook.secret="YOUR_WEBHOOK_SECRET"
```

### Create the Repository CR

Create a [`Repository` CR](/docs/guides/repository-crd.md) with the secret and webhook secret fields referencing it:

```yaml
  ---
  apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
  kind: Repository
  metadata:
    name: my-repo
    namespace: target-namespace
  spec:
    url: "https://bitbucket.com/workspace/repo"
    git_provider:
      user: "your_atlassian_account_email"
      secret:
        name: "bitbucket-cloud-token"
        # Set this if you have a different key in your secret
        # key: "provider.token"
      webhook_secret:
        # required when IP-Based validation is disabled in pipelines-as-code configmap.
        name: "bitbucket-cloud-token"
        # Set this if you have a different key in your secret
        # key: "webhook.secret"
```

The Repository CR requires the `user` field. With an API token, set it to your
Bitbucket/Atlassian account email address, which Pipelines-as-Code sends with
the token for basic auth. With a repository access token (`ATCT` prefix), the
value only appears in logs.

To find your email address, click on your profile icon at the top-left corner
in the Bitbucket Cloud UI (see image below), go to **Account Settings**, and
scroll down to locate your email address.
![Bitbucket Cloud Account Settings](/images/bitbucket-cloud-account-settings.png)

## Notes

- The `git_provider.secret` key cannot reference a secret in another namespace.
  Pipelines-as-Code always assumes it is in the same namespace where the
  Repository CR has been created.

- The `tkn pac create` and `tkn pac bootstrap` commands are not supported on Bitbucket Cloud.

> [!NOTE]
>
> 
> You can only reference a user by the `ACCOUNT_ID` in a owner file. For reason see here:
> 
> <https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-changes-gdpr/#introducing-atlassian-account-id-and-nicknames>
> 


> [!NOTE]
>
> 
> 
> ### IP-based validation (defense-in-depth)
> 
> Pipelines-as-Code verifies that webhooks originate from Bitbucket Cloud IP addresses by fetching the
> IP list from <https://ip-ranges.atlassian.com/>.
> 
> - To add extra IP addresses or networks, set the
>   `bitbucket-cloud-additional-source-ip` key in the `pipelines-as-code`
>   ConfigMap. You can add multiple networks or IPs separated by a comma.
> 
> - To disable IP checking, set `bitbucket-cloud-check-source-ip` to `false`
>   in the `pipelines-as-code` ConfigMap.
> 


### Webhook Secret Validation

In addition to IP-based validation, Pipelines-as-Code can also verify
Bitbucket Cloud supports HMAC webhook secrets. When you configure a
webhook secret on the Repository CR, Pipelines-as-Code validates the
signature header on every incoming webhook to verify the payload was
sent by Bitbucket Cloud and has not been tampered with.

Note: If IP-Based validation is disabled, Pipelines-as-Code falls back to
webhook secret validation to protect PipelineRuns being triggered from unverified source.

Pipelines-as-Code checks the `X-Hub-Signature-256` header (HMAC-SHA256)
first and falls back to `X-Hub-Signature` (HMAC-SHA1) if the SHA256 header
is not present.

Make sure the same secret value is configured in your Bitbucket Cloud webhook
settings under **Repository settings → Workflow → Webhooks → Edit → Secret**.

The `bitbucket-cloud-check-source-ip` setting picks which check runs:

```mermaid
flowchart LR
%% title: How the controller checks a Bitbucket Cloud webhook
%% autoplay
  BB@{ img: "/icons/repository.svg", label: "Bitbucket Cloud", w: 48, h: 48, constraint: "on" }
  Ctrl@{ img: "/icons/controller.svg", label: "Controller", w: 48, h: 48, constraint: "on" }
  IPs@{ img: "/icons/network.svg", label: "Allowed IP ranges", w: 48, h: 48, constraint: "on" }
  Sec@{ img: "/icons/secret.svg", label: "Repository secret", w: 48, h: 48, constraint: "on" }
  Sig@{ img: "/icons/shield.svg", label: "Signature", w: 48, h: 48, constraint: "on" }
  Ok@{ img: "/icons/success.svg", label: "Processed", w: 48, h: 48, constraint: "on" }
  No@{ img: "/icons/refuse.svg", label: "Refused", w: 48, h: 48, constraint: "on" }
  BB -->|webhook| Ctrl
  Ctrl ipon@-->|check on| IPs
  IPs inrange@-->|in range| Ok
  IPs outrange@-->|unknown IP| No
  Ctrl ipoff@-->|check off| Sec
  Sec --> Sig
  Sig sigok@-->|valid| Ok
  Sig sigbad@-->|missing or wrong| No

%% play: IP check on
%% skip Sec Sig No
%% BB -> Ctrl : event
%% Ctrl -> IPs @ipon : source IP | The last address in X-Forwarded-For is compared with ip-ranges.atlassian.com and bitbucket-cloud-additional-source-ip
%% IPs -> Ok @inrange | This is the default, and the signature is not checked at all
%% play: Unknown IP
%% skip Sec Sig Ok
%% BB -> Ctrl : event
%% Ctrl -> IPs @ipon : source IP
%% IPs -> No @outrange | A request from outside those ranges is refused
%% play: IP check off
%% skip IPs No
%% BB -> Ctrl : event
%% Ctrl -> Sec @ipoff | With the IP check turned off, the webhook secret from the Repository secret is required
%% Sec -> Sig : HMAC | X-Hub-Signature-256 is checked, or X-Hub-Signature when it is missing
%% Sig -> Ok @sigok
%% play: No signature
%% skip IPs Ok
%% BB -> Ctrl : event
%% Ctrl -> Sec @ipoff
%% Sec -> Sig
%% Sig -> No @sigbad | No signature header or an empty webhook secret is refused
```

## Add Webhook Secret

If the webhook secret for an existing Repository CR has been deleted, or you want to add a new webhook to your project settings, use the `tkn pac webhook add` command. This command adds a webhook to the project repository settings and updates the `webhook.secret` key in the existing secret without modifying the Repository CR.

Below is the sample format for `tkn pac webhook add`

```shell script
$ tkn pac webhook add -n repo-pipelines

✓ Setting up Bitbucket Webhook for Repository https://bitbucket.org/workspace/repo
? Please enter your Bitbucket Cloud Atlassian account email:  <email@example.com>
👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.awscl2.aws.ospqa.com
? Do you want me to use it? Yes
✓ Webhook has been created on repository workspace/repo
🔑 Secret workspace-repo has been updated with webhook secret in the repo-pipelines namespace.

```

> [!NOTE]
>
> 
> If the `Repository` exists in a namespace other than the `default` namespace, use `tkn pac webhook add [-n namespace]`.
> In the above example, the `Repository` exists in the `repo-pipelines` namespace rather than the `default` namespace, so the webhook was added in the `repo-pipelines` namespace.
> 


## Update Token

There are two ways to update the provider token for an existing Repository CR.

### Update using the CLI

Use the [`tkn pac webhook update-token`](/docs/cli.md) command to
update the provider token for an existing Repository CR. For Bitbucket Cloud,
the command also prompts for your Atlassian account email and updates the
`git_provider.user` field in the Repository CR.

Below is the sample format for `tkn pac webhook update-token`

```shell script
$ tkn pac webhook update-token -n repo-pipelines

? Please enter your Bitbucket Cloud API token:  ************************************
? Please enter your Bitbucket Cloud Atlassian account email: (user@example.com) user@example.com
🔑 Secret workspace-repo has been updated with new Bitbucket Cloud API token and account email in the repo-pipelines namespace.

```

> [!NOTE]
>
> 
> If the `Repository` exists in a namespace other than the `default` namespace, use `tkn pac webhook update-token [-n namespace]`.
> In the above example, the `Repository` exists in the `repo-pipelines` namespace rather than the `default` namespace, so the webhook token was updated in the `repo-pipelines` namespace.
> 


### Update using kubectl

When you have regenerated an API token, you must update it in the cluster. You
can find the secret name in the Repository CR:

  ```yaml
  spec:
    git_provider:
      secret:
        name: "bitbucket-cloud-token"
  ```

Replace `$api_token` and `$target_namespace` with your values:

```shell
kubectl -n $target_namespace patch secret bitbucket-cloud-token -p "{\"data\": {\"provider.token\": \"$(echo -n $api_token|base64 -w0)\"}}"
```

If your `git_provider.user` field needs to be updated, patch the Repository CR
as well:

```shell
kubectl -n $target_namespace patch repository my-repo --type merge \
  -p '{"spec":{"git_provider":{"user":"your_atlassian_account_email"}}}'
```


