How to Trigger a Pipeline via API in Bitbucket Pipelines

By Daniel Zoghalchali·Latchkey

A POST to the pipelines REST endpoint launches a build on a chosen branch, including custom pipelines.

Define a custom pipeline that only the API runs, then POST a target and selector to the pipelines endpoint with an app password or access token.

Define a custom pipeline

A custom pipeline runs only when triggered explicitly, including via the API.

bitbucket-pipelines.yml

pipelines:
  custom:
    nightly-e2e:
      - step:
          name: E2E
          script:
            - npm ci && npm run test:e2e

Trigger it with curl

POST the target branch and the custom pipeline selector to the REST API.

trigger.sh

curl -X POST -u "$USER:$APP_PASSWORD" \
  -H "Content-Type: application/json" \
  https://api.bitbucket.org/2.0/repositories/myteam/myrepo/pipelines/ \
  -d '{ "target": { "type": "pipeline_ref_target", "ref_type": "branch", "ref_name": "main", "selector": { "type": "custom", "pattern": "nightly-e2e" } } }'

Verify it actually works

Bitbucket validates bitbucket-pipelines.yml on push, and a schema error disables the pipeline rather than failing a build, which can look like nothing happened at all.

Terminal

# validate before pushing
curl -X POST -H "Content-Type: application/x-yaml" \
  --data-binary @bitbucket-pipelines.yml \
  https://api.bitbucket.org/2.0/repositories/<workspace>/<repo>/pipelines/validate

# confirm which pipeline definition matched
# Pipelines -> the run -> "Configuration" tab

Constraints that catch people out

Each step runs in a fresh container. Nothing persists between steps unless it is declared as an artifact or a cache.
The default memory allocation per step is limited, and service containers share that budget, so adding a database service can push a previously passing build into an out-of-memory failure.
Only branches with a matching branches: definition run; a push to an unmatched branch silently runs nothing.
Artifacts are passed forward only to later steps in the same pipeline, not between pipelines.

Frequently asked questions

How do I trigger a Pipeline via API in Bitbucket Pipelines?

Define a custom pipeline that only the API runs, then POST a target and selector to the pipelines endpoint with an app password or access token.

Define a custom pipeline?

A custom pipeline runs only when triggered explicitly, including via the API.

Trigger it with curl?