GitHub to GitLab Migration: A Practical Guide

Moving a repository from GitHub to GitLab involves a series of well‑defined steps that minimize disruption. The process covers project import, role mapping, and converting automation scripts. By following a structured plan, teams can retain history, issues, and collaboration settings while adopting GitLab’s integrated CI/CD engine.

Prerequisites and Planning

Before starting, confirm that you have administrator rights on both platforms and a Personal Access Token with appropriate scopes. Verify that target GitLab instance (cloud or self‑managed) meets version requirements for the importer. Document existing GitHub Actions workflows to ensure feature parity after migration.

Access Requirements

Generate a token on GitHub with repo scope and store it securely. In GitLab, ensure the user account can create projects and assign permissions. Align email addresses between systems GitLab uses the public email for user verification.

Data Mapping Considerations

Map GitHub collaborators to GitLab roles: Owner → Maintainer, Write → Developer, Read → Reporter. This mapping is handled automatically by the importer but should be reviewed after the import completes.

Using GitLab’s Built‑in Importer

The GitLab UI provides a direct import path from GitHub or GitHub Enterprise. The importer copies repository data, issues, merge requests, and wiki pages. External references, such as the GitHub and GitLab platform pages, clarify terminology for newcomers.

Step‑by‑Step Project Import

1. Open the GitLab Project Creation Interface and select the “Import project” checkbox.
2. Choose “GitHub” under “Import project from”.
3. Authenticate with GitHub either via OAuth or by entering the previously created token.
4. Grant GitLab access to the desired GitHub organization or personal repositories.
5. Select the repositories to import and configure which components (issues, pull requests, wiki) to include.
6. Click “Import” and monitor progress the status changes to “Complete” when finished.

After import, verify that the repository, issue tracker, and merge request history appear as expected.

Migrating GitHub Actions to GitLab CI

GitHub Actions are defined in .github/workflows YAML files. To run equivalent jobs in GitLab, translate each workflow into a .gitlab-ci.yml job definition. This manual step ensures that linting, testing, and deployment stages continue without interruption.

Mapping Workflows to Jobs

Create a .gitlab-ci.yml at the repository root. Define stages such as lint, test, and smoke. For each GitHub Action, add a job that replicates the Docker image, environment setup, and script commands. Example conversion for a lint job:

stages:
  - lint

lint_job:
  stage: lint
  image: python:3.10
  script:
    - pip install --upgrade pip
    - pip install flake8
    - if [ -f requirements.txt ] then pip install -r requirements.txt fi
    - flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics

Repeat for smoke and unit tests, adjusting the script sections to match the original Action commands.

Reference Implementation Guides

For deeper insight into handling sub‑issue structures during migration, see the GitHub sub‑issues implementation guide. Network‑related considerations, such as outage mitigation, are discussed in the Cloudflare BYOIP outage analysis, which can inform resilience planning for CI pipelines.