Your CI/CD pipeline doesn’t have to live in a YAML file anymore. With on-demand pipelines, you can generate pipeline definitions programmatically, from scripts, services, or automation tools – and execute them instantly via the Pipelines API.
No commit. No pull request. No static configuration to modify. Just build the YAML your situation demands and run it.
Why generate pipelines programmatically?
A static bitbucket-pipelines.yml works well for predictable workflows, but real-world CI/CD is rarely that simple. Teams frequently need pipelines that adapt to context: the services being deployed, the environment being targeted, the tests that are relevant, or conditions detected at runtime.
On-demand pipelines solve this by accepting YAML in the API request body. This means any system that can make an HTTP call can construct and execute a pipeline – your CLI tools, internal platforms, webhook handlers, orchestration services, or even other pipelines.
How to trigger an on-demand pipeline
Use the Bitbucket Pipelines REST API to start a run and include your YAML as the request body with the appropriate content type.
- Endpoint: /repositories/{workspace}/{repo_slug}/pipelines
- Headers: set Content-Type: application/yaml
- Target selection: provide target parameters (branch or commit) as query parameters. If you previously used JSON payload fields for targets, convert them to query parameters using the JSON path as the key.
Example: run an on-demand pipeline on a branch
curl -X POST -sS \
--user '<user>:<API_token>' \
--header 'Content-Type: application/yaml' \
'https://api.bitbucket.org/2.0/repositories/<workspace>/<repo_slug>/pipelines?target.type=pipeline_ref_target&target.ref_type=branch&target.ref_name=main' \
-d '
pipelines:
default:
- step:
name: One-off check
script:
- echo "Running an on-demand pipeline"'
Example: run against a specific commit
curl -X POST -sS \
--user '<user>:<API_token>' \
--header 'Content-Type: application/yaml' \
'https://api.bitbucket.org/2.0/repositories/<workspace>/<repo_slug>/pipelines?target.type=pipeline_commit_target&target.commit.hash=<commit_sha>&target.selector.type=default' \
-d '
pipelines:
default:
- step:
name: Check specific commit
script:
- echo "Inspecting commit <commit_sha>"'Using variables
Pass pipeline variables via query parameters and reference them in your YAML. This is useful for parameterizing ad-hoc jobs like environment, service versions, or feature flags.
curl -X POST -sS \
--user '<user>:<API_token>' \
--header 'Content-Type: application/yaml' \
'https://api.bitbucket.org/2.0/repositories/<workspace>/<repo_slug>/pipelines?target.type=pipeline_ref_target&target.ref_type=branch&target.ref_name=main&target.selector.type=custom&target.selector.pattern=security-scan&variables[0].key=ENV&variables[0].value=prod&variables[1].key=SERVICE&variables[1].value=test-service' \
-d '
pipelines:
custom:
security-scan:
- variables:
- name: ENV
- name: SERVICE
- step:
script:
- echo "Inspecting $SERVICE in $ENV"'
Security and branch restrictions
To run on a branch, the requester must have write access to that branch. This prevents bypassing reviews and accidental exposure of branch-scoped secrets. If restrictions block the run, the API returns a 403 Forbidden error.
Popular use cases and patterns
- Ad-hoc quality gates: Linting, SAST/DAST, dependency audits, SBOM, or flaky-test probes without committing YAML.
- Safe experimentation: Try new images, caches, or step options; iterate on temporary YAML, then commit.
- Event-driven automation: Trigger tailored pipelines from webhooks, schedulers, chat commands, or other systems.
- Dynamic workflows: Generate or tweak YAML on the fly from another pipeline, service, or your own tooling and execute it immediately.
Quick reference summary
| Action | Query parameters | Notes |
|---|---|---|
| Trigger on a branch | target.type=pipeline_ref_target target.ref_type=branch target.ref_name=<branch> | Write access to the branch is required |
| Trigger on a specific commit | target.type=pipeline_commit_target target.commit.hash=<commit_hash> target.selector.type=<selector_type> | Selector is required when targeting a commit |
| Pass variables | variables[0].key=foo variables[0].value=bar variables[1].key=hello variables[1].value=world | Only custom pipelines support variables (same as in bitbucket-pipelines.yml) |
Try on-demand pipelines today
On-demand pipelines gives your team a more flexible way to run CI/CD in Bitbucket, without being constrained by a single, static bitbucket-pipelines.yml file. By generating YAML programmatically and triggering runs via the Pipelines API, you can adapt checks to the exact service, commit, or environment you care about, while still respecting branch protections and permissions.
Want to learn more? Check the updated docs for the Bitbucket Cloud REST API.
