Bitbucket Custom Pipeline Requires Manual Trigger

By Daniel Zoghalchali·Latchkey

A pipeline defined under pipelines: custom: does not run on a push or pull request. Custom pipelines are triggered manually (Run pipeline), via the API, or by a schedule - never automatically by repository events.

What this error means

You push expecting a pipeline to run, but nothing starts, because the work is under custom:. The pipeline only appears as a manual "Run pipeline" option.

pipelines:
  custom:
    deploy-prod:        # only runs from "Run pipeline", the API, or a schedule
      - step:
          script: [ ./deploy.sh ]

Common causes

Work placed under pipelines: custom:

Custom pipelines are intentionally manual. Anything under custom: is excluded from automatic event-based triggering.

Expecting a push to start a custom pipeline

Only default, branches, pull-requests, and tags sections respond to repository events. A push never starts a custom: pipeline on its own.

How to fix it

Move auto-run work to an event section

Put logic that should run on push under branches:/default:, and keep manual-only flows under custom:.

pipelines:
  branches:
    main:
      - step: { script: [ ./build.sh ] }   # runs on push to main
  custom:
    deploy-prod:
      - step: { script: [ ./deploy.sh ] }   # manual only

Trigger the custom pipeline deliberately

1. Use the "Run pipeline" UI and select the custom pipeline.
2. Or start it via the Pipelines REST API for automation.
3. Or attach a schedule to run it on a cadence.

How to prevent it

• Keep manual-only flows under custom: and auto-run flows under event sections.
• Use schedules or the API to run custom pipelines without manual clicks.
• Document which pipelines are manual vs automatic.

Frequently asked questions

Related guides

References

• GitHub Actions documentation