Scheduled and manually triggered pipelines

Overview

Bitbucket allows teams to execute multiple pipelines through two primary triggering mechanisms: manual initiation and time-based scheduling. These features provide flexibility in managing CI/CD workflows beyond standard commit-triggered builds.

Automatic Triggers

By default, pipelines run automatically on:

Commits to any branch
Pull requests creation or update
Tags creation

pipelines:
  default:
    - step:
        script:
          - npm test
  branches:
    main:
      - step:
          script:
            - npm run build
            - npm run deploy
  pull-requests:
    '**':
      - step:
          script:
            - npm run lint
            - npm test
  tags:
    'v*':
      - step:
          script:
            - npm run release

Manual Pipeline Steps

Purpose

Manual steps allow you to customize your CI/CD pipeline by making some steps run only if they are manually triggered. This approach works well for deployment stages requiring human verification before execution.

Configuration

Add trigger: manual to individual steps:

pipelines:
  branches:
    main:
      - step:
          name: Build
          script:
            - npm run build
          artifacts:
            - dist/**
      - step:
          name: Deploy to Production
          deployment: production
          trigger: manual
          script:
            - ./deploy.sh production

The initial step of any pipeline cannot be configured as manual since pipelines activate upon commits.

Multiple Manual Steps

pipelines:
  branches:
    main:
      - step:
          name: Build
          script:
            - npm run build
          artifacts:
            - dist/**
      - step:
          name: Deploy to Staging
          deployment: staging
          trigger: manual
          script:
            - ./deploy.sh staging
      - step:
          name: Deploy to Production
          deployment: production
          trigger: manual
          script:
            - ./deploy.sh production

Custom Pipelines

Custom pipelines do not run automatically on a commit to a branch and only execute when explicitly triggered or scheduled.

Define Custom Pipeline

pipelines:
  custom:
    deploy-staging:
      - step:
          name: Deploy to Staging
          deployment: staging
          script:
            - ./deploy.sh staging
    deploy-production:
      - step:
          name: Deploy to Production
          deployment: production
          script:
            - ./deploy.sh production
    database-backup:
      - step:
          name: Backup Database
          script:
            - ./backup-db.sh

Custom Pipelines with Variables

Custom pipelines can receive variable values at run time. When triggering a custom pipeline manually from the Bitbucket UI, you are prompted to enter values for any variables referenced in the pipeline's steps. No special YAML declaration is needed — the UI detects $VARIABLE references in your scripts automatically.

pipelines:
  custom:
    deploy-to-environment:
      - step:
          name: Deploy
          script:
            - echo "Deploying version $VERSION to $ENVIRONMENT"
            - ./deploy.sh $ENVIRONMENT $VERSION

When run manually, the UI will prompt for VERSION and ENVIRONMENT values before starting.

Running Pipelines Manually

Users with repository write permissions can trigger pipelines through three interfaces:

From Branches View

Navigate to Repository, and then Branches.
Find the branch you want to build.
Select the ... (options menu).
Select Run pipeline.
Choose which pipeline to run.

From Commits View

Navigate to Repository, and then Commits.
Find the specific commit.
Click the ... (options menu).
Select Run pipeline.
Choose which pipeline to run.

From Pipelines Page

Navigate to Repository, and then Pipelines.
Click Run pipeline button.
Select:
- Branch or tag
- Pipeline to run
- (Optional) Variable values for custom pipelines
Click Run.

Scheduled Pipeline Execution

Capabilities

Scheduled pipelines allow you to run a pipeline at hourly, daily, or weekly intervals. These schedules operate alongside commit-triggered and manually-initiated builds, providing consistent, recurring CI/CD execution.

Setup Process

Navigate to Repository, then Pipelines, and then select Schedules.
Click Create schedule.
Configure the schedule:
- Schedule name: Descriptive name
- Branch: Which branch to build
- Pipeline: Which pipeline configuration to use
- Frequency: Hourly, daily, or weekly
- Time: When to run (in your local timezone, executes in UTC)

Schedule Configuration Examples

Daily Build

# Runs automatically at scheduled time
pipelines:
  default:
    - step:
        name: Nightly Build
        script:
          - npm install
          - npm test
          - npm run build

Schedule settings:

Frequency: Daily
Time: 2:00 AM
Branch: main

Weekly Report

pipelines:
  custom:
    weekly-report:
      - step:
          name: Generate Weekly Report
          script:
            - ./generate-report.sh
            - ./send-report.sh

Schedule settings:

Frequency: Weekly
Day: Monday
Time: 9:00 AM
Branch: main
Pipeline: weekly-report

Hourly Health Check

pipelines:
  custom:
    health-check:
      - step:
          name: System Health Check
          script:
            - ./health-check.sh
            - ./alert-if-unhealthy.sh

Schedule settings:

Frequency: Hourly
Branch: main
Pipeline: health-check

Management

Administrators can:

View schedules: See all configured schedules
Edit schedules: Modify timing and configuration
Delete schedules: Remove using the trash icon
View history: See past scheduled runs

API-created schedules display as cron expressions for reference.

Conditional Execution

Branch Conditions

pipelines:
  branches:
    main:
      - step:
          script:
            - npm run deploy
    feature/*:
      - step:
          script:
            - npm test

Changeset Conditions

Only run when specific files change:

pipelines:
  default:
    - step:
        name: Backend Tests
        condition:
          changesets:
            includePaths:
              - "backend/**"
        script:
          - cd backend && npm test
    - step:
        name: Frontend Tests
        condition:
          changesets:
            includePaths:
              - "frontend/**"
        script:
          - cd frontend && npm test

Combined Conditions

pipelines:
  branches:
    main:
      - step:
          name: Deploy API
          condition:
            changesets:
              includePaths:
                - "api/**"
          deployment: production
          script:
            - cd api && ./deploy.sh

Common Patterns

Nightly Builds

pipelines:
  custom:
    nightly-build:
      - step:
          name: Full Test Suite
          script:
            - npm install
            - npm run test:unit
            - npm run test:integration
            - npm run test:e2e
          artifacts:
            - test-results/**
      - step:
          name: Performance Tests
          script:
            - npm run test:performance
      - step:
          name: Security Scan
          script:
            - npm audit
            - npm run scan:security

Schedule: Daily at 2:00 AM on main branch

Weekend Deployment

pipelines:
  custom:
    weekend-deploy:
      - step:
          name: Deploy to Staging
          deployment: staging
          script:
            - ./deploy.sh staging
      - step:
          name: Run Smoke Tests
          script:
            - ./smoke-tests.sh
      - step:
          name: Deploy to Production
          deployment: production
          trigger: manual
          script:
            - ./deploy.sh production

Schedule: Weekly on Saturday at 10:00 PM

Database Maintenance

pipelines:
  custom:
    db-maintenance:
      - step:
          name: Backup Database
          script:
            - ./backup-database.sh
      - step:
          name: Optimize Tables
          script:
            - ./optimize-tables.sh
      - step:
          name: Vacuum Database
          script:
            - ./vacuum-database.sh

Schedule: Weekly on Sunday at 3:00 AM

Dependency Updates

pipelines:
  custom:
    update-dependencies:
      - step:
          name: Check for Updates
          script:
            - npm outdated
            - npm audit
      - step:
          name: Update Dependencies
          trigger: manual
          script:
            - npm update
            - npm test
            - git add package*.json
            - git commit -m "Update dependencies"
            - git push

Schedule: Weekly on Monday at 9:00 AM

Best Practices

Use manual triggers for production - Require human approval for critical deployments
Schedule maintenance during low traffic - Run heavy operations when users aren't active
Add notifications - Alert teams when scheduled pipelines fail
Test schedules - Verify scheduled pipelines work before setting live
Document schedules - Keep a record of what runs when and why
Monitor scheduled runs - Review logs regularly for issues
Use custom pipelines for maintenance - Keep maintenance scripts separate from CI
Set reasonable frequencies - Don't over-schedule to conserve build minutes
Name schedules clearly - Descriptive names help with management
Clean up old schedules - Remove schedules that are no longer needed

Troubleshooting

Schedule Not Running

Cause: Schedule may be disabled or branch deleted

Solution:

Check schedule is enabled in settings
Verify branch still exists
Check pipeline configuration is valid

Wrong Time Execution

Cause: Timezone confusion (displays local time, executes UTC)

Solution: Account for UTC offset when setting schedule time

Manual Step Not Appearing

Cause: First step cannot be manual

Solution: Ensure manual trigger is on subsequent steps, not the first

Custom Pipeline Not Found

Cause: Pipeline name mismatch

Solution: Verify pipeline name matches exactly in YAML and UI

Next Steps

Configure Deployments with manual approval
Set up Variables for custom pipelines
Use Pipes for notifications
Learn about Configuration for advanced conditions

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