Custom configuration files

By default, Bitbucket Pipelines reads its configuration from bitbucket-pipelines.yml in the root of your repository. Custom configuration files let you specify an alternate YAML file for a pipeline run, enabling multiple pipeline definitions in a single repository — for example, separate configs for different environments, teams, or services in a monorepo.

Specifying a custom config file

In Bitbucket

When running a pipeline manually or creating a custom trigger, you can specify an alternate file path in the Run pipeline dialog:

Open your repository in Bitbucket.
Select Pipelines in the left sidebar.
Select Run pipeline.
Set Pipeline file to your custom path (for example, infra/deploy.yml).
Select the branch and pipeline to run.

Using the Bitbucket API

Trigger a pipeline with a custom config file using the Bitbucket API:

curl -X POST \
  "https://api.bitbucket.org/2.0/repositories/{workspace}/{repo}/pipelines/" \
  -H "Content-Type: application/json" \
  -u "$BITBUCKET_USERNAME:$APP_PASSWORD" \
  -d '{
    "target": {
      "type": "pipeline_ref_target",
      "ref_type": "branch",
      "ref_name": "main",
      "selector": {
        "type": "custom",
        "pattern": "deploy-production"
      }
    },
    "configuration_file": {
      "path": "deploy/production.yml"
    }
  }'

File Path Requirements

Requirement	Details
Location	Must be within the repository
Format	Valid Bitbucket Pipelines YAML
Default path	`bitbucket-pipelines.yml` (root)
Subdirectory support	✅ e.g., `infra/pipelines/deploy.yml`
File name	Any `.yml` or `.yaml` file name

Custom config files must be committed to the repository at the specified path and branch. Bitbucket reads the file from the commit being built, not from the working directory.

Common Patterns

Separate Deploy Pipeline

Keep build and deploy logic in separate files:

repository/
├── bitbucket-pipelines.yml          # Default: build and test
└── deploy/
    ├── staging.yml                  # Custom: deploy to staging
    └── production.yml               # Custom: deploy to production

deploy/staging.yml:

image: node:20
pipelines:
  custom:
    deploy-staging:
      - step:
          name: Deploy to Staging
          deployment: staging
          script:
            - ./scripts/deploy.sh staging
    rollback-staging:
      - step:
          name: Rollback Staging
          deployment: staging
          trigger: manual
          script:
            - ./scripts/rollback.sh staging

Trigger from the UI or API specifying deploy/staging.yml as the config file.

Monorepo Per-Service Configs

In a monorepo, each service can have its own pipeline file:

monorepo/
├── bitbucket-pipelines.yml          # Parent orchestrator
└── services/
    ├── payment-api/
    │   └── pipeline.yml             # Service-specific pipeline
    ├── email-worker/
    │   └── pipeline.yml
    └── admin-frontend/
        └── pipeline.yml

services/payment-api/pipeline.yml:

image: node:20
pipelines:
  default:
    - step:
        name: Test Payment API
        script:
          - cd services/payment-api
          - npm ci
          - npm test
  custom:
    deploy-payment-api:
      - step:
          name: Build Payment API
          script:
            - cd services/payment-api
            - npm run build
          artifacts:
            - services/payment-api/dist/**
      - step:
          name: Deploy Payment API
          deployment: production
          trigger: manual
          script:
            - ./scripts/deploy-service.sh payment-api

The parent pipeline can trigger these service-specific pipelines using the trigger step. Service teams can also run their service's pipeline independently.

Environment-Specific Configs

repository/
├── bitbucket-pipelines.yml          # Default CI pipeline
├── pipelines/
│   ├── deploy-dev.yml
│   ├── deploy-staging.yml
│   └── deploy-prod.yml

This separates CI (automatic on every commit) from CD (manual deployment runs), giving you fine-grained control over what runs when.

Using Custom Configs with Parent/Child Pipelines

A parent pipeline can trigger a child pipeline using a custom config file via the API trigger step:

# bitbucket-pipelines.yml (parent)
pipelines:
  branches:
    main:
      - step:
          name: Run Build Tests
          script:
            - npm test
      - step:
          name: Trigger Deploy
          type: pipeline
          custom: deploy-production   # Custom pipeline name in deploy/production.yml

The deploy-production custom pipeline must be defined under pipelines: custom: in the same config file being used for the pipeline run.

Custom Config in Self-Hosted Runners

Custom config files work with self-hosted runners without additional configuration. The runner reads the specified file from the repository at the relevant commit.

Constraints

Constraint	Value
File must exist in repository	✅ Required at commit time
Supports all pipeline features	✅ Full feature parity
Supports `definitions: imports:` within custom file	✅ Yes
Triggered by webhooks/push	❌ Only the default file is used for push-triggered pipelines
Triggered manually or via API	✅ Custom file path can be specified

Push-triggered pipelines (on commit, pull request, tag) always use bitbucket-pipelines.yml. Custom config files are only used for manually triggered or API-triggered pipeline runs.

Best Practices

Use for deployment pipelines — Keep CI in the default file; put environment-specific deploy logic in custom files
Namespace file paths clearly — Use pipelines/, deploy/, or infra/ directories to distinguish custom configs from application code
Document custom files — Add a comment at the top of each custom file explaining when and how to trigger it
Keep custom files focused — Each custom file should have a single, clear purpose (e.g., "deploy to production")
Version alongside the code — Custom pipeline files are committed to the repo and versioned with the code they deploy

Triggers reference — Manual triggers and scheduled pipelines
Parent/Child Pipelines reference — Orchestrate pipelines across repos
YAML sharing reference — Share common steps across multiple pipeline files

Was this helpful?

It wasn't accurateIt wasn't clearIt wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community