Bitbucket to GitLab

Migrating from Bitbucket Server/Data Center to GitLab involves moving Git repositories, pull request history, CI/CD pipelines, and user permissions. The scope of migration depends on how much metadata (beyond raw Git data) needs to be preserved.

Bitbucket Server stores projects and repositories in a PROJECT/repo hierarchy. GitLab uses Groups and Subgroups with a similar hierarchy, so structural mapping is straightforward. The main complexity lies in migrating pull request discussions, inline comments, and CI/CD pipelines (Bamboo/Jenkins to GitLab CI).

Method comparison

Bitbucket Server and GitLab use different terminology for similar concepts. This mapping helps plan the structural migration.

GitLab repository limits

GitLab LFS limits

Bitbucket Server export limits

GitLab import rate limits

The simplest migration path. Clone each Bitbucket repo as a bare mirror and push to a new GitLab project. This preserves all commits, branches, tags, and refs.

Single repo

# Clone bare mirror from Bitbucket
git clone --mirror https://bitbucket.example.com/scm/PROJECT/repo.git

# Create the project in GitLab (via API or UI)
# Then push the mirror
cd repo.git
git push --mirror https://gitlab.example.com/group/repo.git

Bulk migration script

#!/bin/bash
# Bulk migrate all repos from a Bitbucket project to a GitLab group
BB_URL="https://bitbucket.example.com"
BB_PROJECT="MYPROJECT"
BB_TOKEN="your-bitbucket-pat"

GL_URL="https://gitlab.example.com"
GL_GROUP_ID="42"
GL_TOKEN="your-gitlab-pat"

# List all repos in the Bitbucket project
repos=$(curl -s -H "Authorization: Bearer $BB_TOKEN" \
  "$BB_URL/rest/api/1.0/projects/$BB_PROJECT/repos?limit=1000" \
  | jq -r '.values[].slug')

for repo in $repos; do
  echo "Migrating: $repo"

  # Clone bare mirror
  git clone --mirror "$BB_URL/scm/$BB_PROJECT/$repo.git" "/tmp/$repo.git"

  # Create GitLab project
  curl -s --request POST \
    -H "PRIVATE-TOKEN: $GL_TOKEN" \
    "$GL_URL/api/v4/projects" \
    -d "name=$repo&namespace_id=$GL_GROUP_ID" > /dev/null

  # Push mirror
  cd "/tmp/$repo.git"
  git push --mirror "$GL_URL/group-path/$repo.git"
  cd -

  # Cleanup
  rm -rf "/tmp/$repo.git"
done

GitLab includes a built-in importer for Bitbucket Server that can migrate repositories along with pull request metadata.

What it migrates

• Repository — full Git history, all branches and tags
• Pull requests — converted to merge requests, including title, description, state (open/merged/declined)
• PR comments — general and inline comments preserved with author attribution
• PR reviewers — mapped to GitLab reviewers where users match

What it does NOT migrate

• Branch permissions / protected branch rules
• Webhooks
• Repository settings (default branch must be set manually if not main/master)
• CI/CD pipelines (Bamboo/Jenkins configs)
• Git LFS objects (must be pushed separately)
• Attachments on PR comments

Setup steps

1. In Bitbucket, create a Personal Access Token with PROJECT_READ and REPO_READ permissions
2. In GitLab, go to New Project → Import project → Bitbucket Server
3. Enter Bitbucket Server URL and the personal access token
4. Select repositories to import — choose target namespace/group
5. Click Import and monitor progress

For maximum control, use the Bitbucket Server REST API to export data and the GitLab REST API to import it. This approach is useful when you need to transform data, handle complex user mapping, or migrate metadata the built-in importer doesn't support.

Bitbucket Server API endpoints

GitLab API endpoints

Git LFS objects are not included in a standard git clone --mirror and are not migrated by the GitLab Bitbucket Server importer. They must be handled separately.

Migrating LFS objects

# Clone with LFS from Bitbucket
GIT_LFS_SKIP_SMUDGE=0 git clone https://bitbucket.example.com/scm/PROJECT/repo.git
cd repo

# Fetch all LFS objects for all refs
git lfs fetch --all origin

# Add GitLab as new remote
git remote add gitlab https://gitlab.example.com/group/repo.git

# Push all LFS objects to GitLab
git lfs push --all gitlab

# Push Git refs
git push --mirror gitlab

CI/CD pipelines do not migrate automatically. Bamboo plans and Jenkins jobs must be manually converted to .gitlab-ci.yml files. This is typically the most time-consuming part of the migration.

Bamboo to GitLab CI mapping

Example conversion

Plan: Build & Deploy
  Stage: Build
    Job: Maven Build
      Task: mvn clean package
      Task: Archive artifact
  Stage: Deploy
    Job: Deploy to Staging
      Task: scp target/*.jar

stages:
  - build
  - deploy

maven-build:
  stage: build
  image: maven:3.9-eclipse-temurin-21
  script:
    - mvn clean package
  artifacts:
    paths:
      - target/*.jar

deploy-staging:
  stage: deploy
  script:
    - scp target/*.jar user@staging:/app/
  environment:
    name: staging

Pre-migration

• Inventory all Bitbucket projects and repositories — note sizes, LFS usage, and activity
• Identify which repos are active vs. archived — archive inactive repos rather than migrating them
• Create GitLab groups matching Bitbucket project structure
• Ensure all users exist in GitLab with matching email addresses for attribution
• Estimate total storage needed (Git repos + LFS objects)
• Plan maintenance window for cutover
• Choose migration method based on metadata requirements

During migration

• Set Bitbucket repos to read-only to prevent new commits
• Run migration (mirror, importer, or API scripts)
• Migrate LFS objects separately if applicable
• Verify commit counts, branch counts, and tag counts match
• Spot-check PR/MR history on critical repos

Post-migration

• Configure protected branches to match Bitbucket branch permissions
• Set up webhooks for integrations (Slack, Jira, etc.)
• Convert CI/CD pipelines to .gitlab-ci.yml
• Update any hardcoded Bitbucket URLs in documentation, scripts, and configs
• Update DNS/proxy if migrating from self-hosted Bitbucket to self-hosted GitLab
• Communicate new repo URLs to all developers
• Keep Bitbucket running in read-only mode for a transition period
• Decommission Bitbucket after confirming all teams have switched