> For the complete documentation index, see [llms.txt](https://docs.devicecloud.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devicecloud.dev/ci-cd-integration/bitbucket-pipelines.md).

# Bitbucket Pipelines

DeviceCloud ships a [Bitbucket Pipe](https://support.atlassian.com/bitbucket-cloud/docs/pipes/) that runs your Maestro flows on devicecloud.dev directly from your Bitbucket Pipelines.

## Quick Start

Add the pipe to a step in your `bitbucket-pipelines.yml`:

```yaml
image: atlassian/default-image:4

pipelines:
  default:
    - step:
        name: E2E tests
        script:
          - pipe: docker://moropo/device-cloud-for-bitbucket:1.1.0
            variables:
              API_KEY: $DEVICE_CLOUD_API_KEY
              APP_FILE: 'build/app-release.apk'
              WORKSPACE: '.maestro'
              ANDROID_DEVICE: 'pixel-6'
              ANDROID_API_LEVEL: '34'
```

Store your DeviceCloud API key as a **Secured Repository variable** in *Repository settings → Repository variables*. Reference it as `$DEVICE_CLOUD_API_KEY` and pass it to the pipe as `API_KEY`.

Find your API key at [console.devicecloud.dev/settings](https://console.devicecloud.dev/settings).

## Platform Examples

### Android

```yaml
- pipe: docker://moropo/device-cloud-for-bitbucket:1.1.0
  variables:
    API_KEY: $DEVICE_CLOUD_API_KEY
    APP_FILE: 'build/app-release.apk'
    WORKSPACE: '.maestro'
    ANDROID_DEVICE: 'pixel-7'
    ANDROID_API_LEVEL: '34'
    REPORT: 'junit'
```

### iOS

```yaml
- pipe: docker://moropo/device-cloud-for-bitbucket:1.1.0
  variables:
    API_KEY: $DEVICE_CLOUD_API_KEY
    APP_FILE: 'build/MyApp.app.zip'
    WORKSPACE: '.maestro'
    IOS_DEVICE: 'iphone-16-pro'
    IOS_VERSION: '18'
```

## Variables

The pipe variables map 1:1 to the [`dcd cloud`](https://github.com/devicecloud-dev/docs/blob/main/ci-cd/dcd-cloud.md) CLI flags. The full list lives in the pipe's [README](https://bitbucket.org/devicecloud-dev/device-cloud-for-bitbucket/src/main/README.md). Required: `API_KEY`. Common ones:

| Variable                              | Description                                                 |
| ------------------------------------- | ----------------------------------------------------------- |
| `API_KEY`                             | DeviceCloud API key (required, secured).                    |
| `APP_FILE`                            | Path to the app binary to upload.                           |
| `APP_BINARY_ID`                       | Reuse a previously uploaded binary.                         |
| `WORKSPACE` / `FLOWS`                 | Path to your Maestro flows folder/file.                     |
| `ANDROID_DEVICE`, `ANDROID_API_LEVEL` | Android device + API level.                                 |
| `IOS_DEVICE`, `IOS_VERSION`           | iOS device + version.                                       |
| `ENV_LIST`                            | Newline-separated `KEY=VALUE` env vars injected into flows. |
| `INCLUDE_TAGS` / `EXCLUDE_TAGS`       | Filter flows by Maestro tag.                                |
| `REPORT`                              | `junit`, `html`, `html-detailed`, `allure`.                 |
| `DOWNLOAD_ARTIFACTS`                  | `ALL` or `FAILED` — downloads logs/screenshots/videos.      |
| `ASYNC`                               | `"true"` to fire-and-forget.                                |
| `RUNNER_TYPE`                         | `m1` or `m4` for premium runners.                           |

## Bitbucket context auto-attached

The pipe auto-attaches Bitbucket context (commit SHA, repo, branch, PR number) as metadata on every run and are included on the Console UI so you know what triggered each run.

If you would prefer not to include this metadata, set `INCLUDE_BITBUCKET_CONTEXT: 'false'`.

## Outputs

The pipe writes a `dcd-result.env` file into the repo's working directory. Subsequent script lines in the same step can `source` it:

```yaml
- pipe: docker://moropo/device-cloud-for-bitbucket:1.1.0
  variables:
    API_KEY: $DEVICE_CLOUD_API_KEY
    APP_FILE: 'app.apk'
    WORKSPACE: '.maestro'

- source ./dcd-result.env
- echo "Console: $DEVICE_CLOUD_CONSOLE_URL"
- echo "Status:  $DEVICE_CLOUD_UPLOAD_STATUS"
```

Exported: `DEVICE_CLOUD_CONSOLE_URL`, `DEVICE_CLOUD_UPLOAD_STATUS`, `DEVICE_CLOUD_FLOW_RESULTS`, `DEVICE_CLOUD_APP_BINARY_ID`, `DEVICE_CLOUD_UPLOAD_ID`.

The pipe exits non-zero on test failures so the build fails by default.

## Passing env vars into flows

```yaml
- pipe: docker://moropo/device-cloud-for-bitbucket:1.1.0
  variables:
    API_KEY: $DEVICE_CLOUD_API_KEY
    APP_FILE: 'app.apk'
    WORKSPACE: '.maestro'
    ENV_LIST: |
      USERNAME=test@example.com
      PASSWORD=$TEST_PASSWORD
      ENVIRONMENT=staging
```

`$TEST_PASSWORD` is interpolated by Bitbucket from your repo variables before the pipe runs.

## Reports as build artifacts

To expose a report as a Bitbucket artifact (and have Bitbucket pick up the test results UI), declare it on the step. For example, if you would like a JUnit report, set up your pipe like this:

```yaml
- step:
    name: E2E tests
    script:
      - pipe: docker://moropo/device-cloud-for-bitbucket:1.1.0
        variables:
          API_KEY: $DEVICE_CLOUD_API_KEY
          APP_FILE: 'app.apk'
          WORKSPACE: '.maestro'
          REPORT: 'junit'
    artifacts:
      - report.xml
```

## Source

[bitbucket.org/devicecloud-dev/device-cloud-for-bitbucket](https://bitbucket.org/devicecloud-dev/device-cloud-for-bitbucket).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.devicecloud.dev/ci-cd-integration/bitbucket-pipelines.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.