Bitbucket Cloud · Pipelines · Checked October 31, 2026

Bitbucket Pipelines: run a custom pipeline with variables

A pipeline under custom: in bitbucket-pipelines.yml never runs on a push. You start it by hand, on a schedule, or from a script through the REST API, and it can ask for variables each time. From a script, the most common answer is HTTP 400 "bitbucket-pipelines.yml not found.", even though the file is there. Every public report of it below came down to the selector in the request.

Declare the variables

From Atlassian's pipeline start conditions: a custom pipeline may start with a variables list, and each variable has a name (required), and optionally a default, allowed-values and a description.

pipelines:
  custom:
    deploy-staging:            # the pipeline's name
      - variables:
          - name: VERSION
            description: "Tag or commit to deploy"
          - name: REGION
            default: "eu-west-1"
            allowed-values:
              - "eu-west-1"
              - "us-east-1"
      - step:
          script:
            - ./deploy.sh "$VERSION" "$REGION"

The name of the pipeline is its key under custom:, here deploy-staging. It is also what the API calls the pattern.
A variable left empty when the pipeline is run gets its default. Values set at run time are only for custom pipelines.
Atlassian asks you to keep secrets and passwords in repository or workspace variables (secured), not in these.

Run it on Bitbucket

From Atlassian's scheduled and manually triggered pipelines: open the repository's Pipelines page and choose Run pipeline. Pick the branch or tag, then the pipeline, fill in the variables, and choose Run. The Branches and Commits pages have Run pipeline in a branch's or commit's … menu too. Running a pipeline needs write access to the repository.

Run it with the REST API

Bitbucket's Pipelines API, Run a pipeline:

curl -X POST -u '<email>:<API token>' \
  -H 'Content-Type: application/json' \
  https://api.bitbucket.org/2.0/repositories/WORKSPACE/REPO/pipelines/ \
  -d '{
    "target": {
      "type": "pipeline_ref_target",
      "ref_type": "branch",
      "ref_name": "main",
      "selector": { "type": "custom", "pattern": "deploy-staging" }
    },
    "variables": [
      { "key": "VERSION", "value": "v2.4.1" },
      { "key": "REGION", "value": "us-east-1" }
    ]
  }'

Success is 201 Created, with the new pipeline in the body and its address in Location.
A variable is key and value here (name in the YAML), and may add "secured": true.
ref_name is the branch whose newest commit runs. To run an older commit, add "commit": { "type": "commit", "hash": "…" } to the target.
Sign in with your Atlassian account's email and an API token with the write:pipeline scope. App passwords can no longer be created since September 9, 2025 ("Token is invalid, expired, or not supported for this endpoint").

"bitbucket-pipelines.yml not found."

HTTP 400
{"error": {"message": "Bad request", "detail": "bitbucket-pipelines.yml not found.",
  "data": {"key": "result-service.pipeline.yml-not-found", "arguments": {}}}}

Bitbucket's API reference lists three reasons for a 400 here: Pipelines is not enabled for the account or repository, the file is not in the repository at that revision, or the body has an invalid property. In four public threads in Atlassian's community the file was there, Run pipeline on Bitbucket worked, and the request was the problem:

No selector. The request named only the branch, so Bitbucket looked for that branch's own pipeline (branches: or default:), not the custom one. Adding "selector": {"type": "custom", "pattern": "…"} fixed it (May 2019, August 2021).
The pattern was not the pipeline's name. One reporter sent "pattern": "Deploy to integration", worded like the "Deploy to production" in Atlassian's own examples, and another a sentence about what the pipeline does. Both worked once the pattern was the exact key under custom: (March 2023, October 2023).

So check, in this order: the target has a selector of type custom; its pattern is the key under custom:, letter for letter; and that key is in bitbucket-pipelines.yml on the branch in ref_name.

Run custom pipelines from IntelliJ IDEA

Pipeline Inbox for Bitbucket Pipelines, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, lists the pipelines of all your Bitbucket Cloud repositories in an IDE tool window. Its Run Pipeline… reads bitbucket-pipelines.yml on the branch you choose and offers that branch's own pipeline and each custom pipeline in it, so the name sent is always one the file has. Each declared variable gets a field, a choice when it lists allowed-values, with the default filled in, and the values can be remembered (never a secured one). When Bitbucket still refuses, the IDE shows Bitbucket's own words. The list, steps and logs are free; running, re-running and stopping are Pro (US$1.50 a month, with a 30-day trial).

Get it on JetBrains Marketplace

Atlassian, Bitbucket and Bitbucket Pipelines are trademarks of Atlassian; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by Atlassian or JetBrains.

More: Pipelines did not run after a push · Out of build minutes · "No online runner available" · "Permission denied to update branch" · "You have reached your pull rate limit" (Docker Hub) · "There is an error in your bitbucket-pipelines.yml" · "This pipeline was paused" (deployments) · Bitbucket Pipelines plugins for IntelliJ IDEA compared · 日本語