GitHub Actions to Bitbucket Pipelines

Convert GitHub Actions workflows to bitbucket-pipelines.yml. Translates jobs, branch filters, caching, artifacts, services, and Bitbucket pipes. Side-by-side diff and audit log, all in your browser.

Migrating from GitHub Actions to Bitbucket Pipelines

Bitbucket Pipelines is the simplest of the four platforms structurally — a single YAML file with a single `pipelines:` block split by trigger (default, branches, tags, pull-requests, custom). Converting from GitHub Actions therefore means inverting the model: rather than naming jobs and giving them `on:` filters, you list the pipeline-per-trigger and put steps inside.

The converter routes each GitHub job to the most-specific Bitbucket pipeline section that fits its trigger filter. Caching maps to Bitbucket's built-in cache catalogue (`node`, `pip`, `composer`, `gradle`, `maven`, `bundler`, `dotnetcore`) when the cached paths match; otherwise you'll get a manual-review note suggesting you define a custom cache.

Syntax cheat sheet

ConceptGitHub ActionsBitbucket Pipelines
Imageruns-on: ubuntu-latest container: node:20image: node:20
Triggeron: push: branches: [main]pipelines: branches: main:
Stepjobs.test.steps: - run: npm testpipelines.default: - step: script: [npm test]
Cache- uses: actions/cache@v4 with: { path: node_modules }- step: caches: [node]
Artifact- uses: actions/upload-artifact@v4 with: { path: dist }- step: artifacts: [dist/**]
Manualenvironment.required-reviewers: [...]pipelines: custom: deploy: - step: trigger: manual
Variable${{ secrets.TOKEN }}$TOKEN

Gotchas to watch for

  • Schedules are configured in the UI

    Bitbucket pipeline schedules live in repository Pipelines → Schedules, not in YAML. The converter emits a manual-review note for every `on: schedule:` entry.

  • Use built-in caches first

    For matching cache paths, Bitbucket has built-in cache names (`node`, `pip`, `gradle`, etc.). The converter maps to these where it can.

  • Parallel groups instead of needs:

    GitHub `needs:` between jobs becomes sequential `step:` entries. To parallelise, the converter wraps sibling jobs in a `parallel:` group.

  • Services are global

    Bitbucket service containers are declared in `definitions.services`, not per-step. The converter flags this for review and emits a comment with the original service definitions.

  • Build minutes are limited

    Bitbucket Cloud has stricter build-minute and concurrency limits than GitHub-hosted runners. Right-size your pipeline before importing.

Worked examples

Node test → Bitbucket

One default pipeline, native node cache, single step.

GitHub Actions
name: CI
on:
  push:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test
Bitbucket Pipelines
image: node:20
pipelines:
  default:
    - step:
        name: Test
        caches: [node]
        script:
          - npm ci
          - npm test

Frequently asked questions

Does it support Bitbucket pipes?

Yes for emission. The converter emits Bitbucket pipes for Slack notifications, AWS S3 deploys, and CloudFront invalidations when it detects equivalent GitHub Actions. For pipes without a clear GitHub Action analog, it falls back to shell.

How are matrix builds handled?

Bitbucket has limited matrix support — the converter expands matrices into explicit parallel steps (one per combo). For more than ~10 combos, switch to a single step with a script that fans out internally.

What about deploy environments?

`deployment:` blocks in Bitbucket require pre-configured environments in the repository UI. The converter emits a comment listing the environments to create.

Also useful: JSON Schema GeneratorAI Coding Rules