Migrating From Bitbucket to GitLab? Here’s How to Keep Your Teams Moving Without Missing a Beat

Written by superorange0707 | Published 2025/05/29
Tech Story Tags: devops | bitbucket | gitlab | bitbucket-to-github | migration | github-repository-mirroring | bitbucket-webhooks | gitlab-ci

TLDRKeeping Bitbucket and GitLab repositories in sync ensures nothing gets lost, avoids disruption, and allows for a gradual migration. Using GitLab's built-in mirroring is the simplest way to sync repositories fromBitbucket. Sync using GitLab CI/CD pipelines and Bit bucket webhooks is the other way to do it.via the TL;DR App

During transitions from Bitbucket to GitLab, teams may still push code to Bitbucket. Keeping both Bitbucket and GitLab repositories in sync ensures nothing gets lost, avoids disruption, and allows for a gradual migration.

Here's a practical guide detailing two reliable ways to achieve this, making the migration far less disruptive for your development teams.

📖 Table of Contents

  • Introduction
  • Prerequisites
  • Option 1: Using GitLab Repository Mirroring
  • Option 2: Sync Using GitLab CI/CD and Bitbucket Webhooks
  • Comparing Your Options
  • Testing Your Setup
  • Benefits
  • Conclusion

Introduction

When moving from Bitbucket to GitLab, teams often can't immediately stop using Bitbucket. Developers still push changes, open pull requests, and merge branches, which makes synchronization crucial.

Keeping repositories in sync ensures development continuity without forcing an immediate platform switch, giving your team more breathing room to adapt to GitLab gradually.

Prerequisites

  • Basic access (developer or maintainer permissions) to both your Bitbucket and GitLab repositories.
  • Permission to configure webhooks and CI/CD pipelines on both platforms.

Option 1: Using GitLab Repository Mirroring

GitLab's built-in mirroring is the simplest way to sync repositories from Bitbucket.

Steps to Set Up Mirroring:

  1. In your GitLab project, navigate to Settings > Repository.

  2. Expand the Mirroring repositories section.

  3. Enter your Bitbucket repository URL:

    https://bitbucket.org/username/repository.git
    
  4. Provide your Bitbucket username and password or access token.

  5. Choose Pull to sync from Bitbucket to GitLab.

  6. Select your desired sync interval (e.g., every 5 minutes).

  7. Click Mirror repository to enable mirroring.

Option 2: Sync Using GitLab CI/CD and Bitbucket Webhooks

If repository mirroring isn't available in your GitLab instance, or you require more customization, you can set up synchronization using GitLab CI/CD pipelines and Bitbucket webhooks.

Step 1: Add .gitlab-ci.yml to Both Bitbucket and GitLab

Create a .gitlab-ci.yml file and add it to both Bitbucket and GitLab repositories. This prevents synchronization issues that could occur when mirroring overwrites your pipeline configuration.

Here's the YAML configuration:

stages:
  - sync 

sync_from_bitbucket:
  stage: sync 
  only:
    - schedules  # Trigger via GitLab scheduled pipelines
    - triggers   # Trigger via external trigger tokens (e.g., webhooks)
    - web        # Allow manual web-triggered runs from the GitLab UI
  script:
    - git config --global user.name "your_username"  
    - git config --global user.email "your_email@example.com" 
    - git clone --mirror https://${BITBUCKET_USER}:${BITBUCKET_TOKEN}@bitbucket.org/username/repository.git bitbucket-mirror  # Clone Bitbucket repo as a bare mirror
    - cd bitbucket-mirror  # Navigate into the cloned mirror
    - git push --mirror https://${GITLAB_USER}:${GITLAB_TOKEN}@gitlab.com/${CI_PROJECT_PATH}.git  # Push mirror to GitLab

Update "your_username" and "your_email@example.com" with your actual Git details.

Note: All secrets (tokens, usernames) should be stored securely in GitLab CI/CD variables and referenced in the script to avoid hardcoding sensitive data.

Step 2: Configure GitLab CI/CD Variables

Navigate to GitLab: Settings > CI/CD > Variables, then add:

  • BITBUCKET_USER: Your Bitbucket username
  • BITBUCKET_TOKEN: Your Bitbucket access token or app password
  • GITLAB_USER: Your GitLab username
  • GITLAB_TOKEN: Your GitLab personal access token (scope: write_repository)

Step 3: Create a Pipeline Trigger Token in GitLab

  1. In GitLab, navigate to: Settings > CI/CD > Pipeline triggers.
  2. Generate a new trigger token.
  3. Note your GitLab project's project ID from your project home page.

Step 4: Add a Webhook in Bitbucket

In Bitbucket:

  1. Navigate to your repository settings (Repository settings > Webhooks).

  2. Add a webhook using the URL format:

    https://gitlab.com/api/v4/projects/{project_id}/ref/{branch_name}/trigger/pipeline?token={trigger_token}
    

Replace placeholders accordingly:

  • {project_id}: Your GitLab project ID
  • {branch_name}: Your main branch (main or master)
  • {trigger_token}: The pipeline trigger token from GitLab.
  • Choose push or merge events (or others as needed) to trigger synchronization.

Comparing Your Options

Feature

GitLab Repository Mirroring

GitLab CI/CD + Webhook

Complexity

Easy

Moderate

Available without Mirroring

No

Yes

Customization

Limited

High

Trigger Type

Scheduled

Webhook & scheduled

Maintains Repository History

Yes

Yes

Testing Your Setup

To verify synchronization:

  • Push changes to your Bitbucket repository.
  • Use GitLab’s CI/CD pipeline logs or Bitbucket's webhook testing tools to confirm synchronization.
  • Adjust as needed based on pipeline feedback or errors.

Benefits

Setting up synchronization provides:

  • Continuous integration across platforms during migration.
  • Full preservation of repository history, tags, and branches.
  • Minimal disruption to developer workflows.
  • Flexibility in migration timelines.

Conclusion

Synchronizing repositories between Bitbucket and GitLab doesn't have to be complicated. Using either GitLab's built-in mirroring or CI/CD pipelines with webhooks, you can ensure smooth migrations and minimize headaches for developers.


Written by superorange0707 | AI/ML engineer blending fuzzy logic, ethical design, and real-world deployment.
Published by HackerNoon on 2025/05/29