GitLab CI to Bitbucket Pipelines

Convert .gitlab-ci.yml to bitbucket-pipelines.yml. Translates stages, jobs, rules, parallel matrix, cache, and artifacts to Bitbucket's pipelines/branches/tags model.

Migrating from GitLab CI to Bitbucket Pipelines

GitLab's flexible `rules:` system condenses into Bitbucket's simpler trigger taxonomy: `pipelines.default` (every push), `pipelines.branches.<pattern>`, `pipelines.tags.<pattern>`, `pipelines.pull-requests.<pattern>`, and `pipelines.custom.<name>` (manual). The converter routes each GitLab job to the most-specific Bitbucket section that fits its rules.

Syntax cheat sheet

ConceptGitLab CIBitbucket Pipelines
Triggerrules: - if: $CI_COMMIT_BRANCH == "main"pipelines: branches: main:
Stagestages: [test, deploy](implicit via step order)
Cachecache: paths: [node_modules]- step: caches: [node]
Artifactartifacts: paths: [dist]- step: artifacts: [dist/**]
Manual jobwhen: manual- step: trigger: manual

Gotchas to watch for

  • Stages collapse to step order

    Bitbucket has no notion of stages. The converter chains jobs sequentially or wraps siblings in `parallel:`.

  • Custom cache definitions

    When GitLab cache paths don't match a built-in Bitbucket cache, the converter recommends declaring a custom cache in `definitions.caches:` at the top of the file.

  • Schedules require UI configuration

    Schedule rules become a comment in the Bitbucket output, since schedules live in repository settings.

Worked examples

GitLab Node test → Bitbucket

Single stage, single step.

GitLab CI
stages:
  - test
test:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm test
Bitbucket Pipelines
image: node:20
pipelines:
  default:
    - step:
        name: test
        script:
          - npm ci
          - npm test

Frequently asked questions

Does it convert GitLab Pages?

No. Bitbucket has no equivalent of GitLab Pages. The converter flags such jobs as unsupported.

How are GitLab services handled?

GitLab `services:` (e.g. postgres) become a recommendation to declare a Bitbucket `definitions.services:` block. Reference the service from your step's `services:` list.

Also useful: JSON Schema GeneratorAI Coding Rules