GitHub to GitLab Migration Guide

A practical guide for engineers in the middle of a migration.

GitLab 18.x Last updated April 2026

What Is Migrated

Reference for what migrates automatically, what migrates with caveats, and what's manual.

Reference for what the GitLab importer brings across, what migrates with caveats, and what you have to rebuild by hand.

At a glance

Automatic

Imports without action

Code, history, issues, MRs, comments, milestones, wiki, releases, and members.

 With caveats

Imports, but check

References, attachments, mentions, custom roles, and SSO accounts.

 Manual

Rebuild required

Actions, Projects, Dependabot, Advanced Security, status checks, webhooks, secrets.

Migrated automatically

Repository content

  • All branches, tags, and commit history
  • Fork branches associated with open pull requests
  • Git LFS objects (only if LFS is enabled on the destination project before import)
  • Wiki pages, with edit history
  • Release notes and the repository description

Project metadata

  • Issues — title, description, comments, state, labels, assignees, timestamps
  • Issue events (label changes, milestone changes, etc.)
  • Pull requests, becoming merge requests, with reviews, review comments, reviewers, approvals, and merge info
  • Comments on issues and PRs
  • Labels, with colors
  • Milestones — title, description, due date, state, and attached issues
  • Branch protection rules, mapped to GitLab equivalents
  • Collaborators, with role mapping (see below)
  • Attachments in comments, descriptions, and releases (when the toggle is enabled)

Imported items show an Imported badge in the UI (GitLab 17.2+).

Migrated with caveats

Item Caveat
PR → MR references GitHub uses #NNN for both issues and PRs. GitLab uses # for issues and ! for MRs. The importer can't always tell — references in imported comments default to issues, and references inside descriptions don't autolink.
Pre-2017 PR review threads Import as separate threads, not inline diff notes (older GitHub API doesn't return in_reply_to_id). Text is preserved.
Username mentions Wrapped in backticks (`@octocat`) to avoid notification storms (GitLab 17.5+).
Auto-merged commits May show unverified in GitLab — they're signed with GitHub's internal GPG key.
Attachments before 2023-05-09 in private repos Cannot be imported (GitHub-side limit).
GitHub Enterprise Server attachments Only video and image attachments come across (GitLab 18.4+). Other file types skipped silently.
SAML SSO accounts Can fail to import Markdown attachments. Workaround: add the importing user as an outside collaborator on the GitHub repo for the duration of the import.
Custom GHE Cloud repository roles Not supported. Surface as partial failures during collaborator import; affected users need to be added manually.
Group restriction If the destination group has "Users cannot be added to projects in this group" enabled, collaborator import is skipped (honored from GitLab 18.4+).

Manual rebuild required

GitHub GitLab equivalent
GitHub Actions Rebuild as GitLab CI/CD (.gitlab-ci.yml).
GitHub Projects Use Issue Boards and Epics.
Dependabot Use Dependency Scanning and Renovate (or GitLab's dependency update flows).
GitHub Advanced Security Use GitLab SAST, DAST, Secret Detection, and Container Scanning.
Required status checks Recreate as merge request approval rules.
External status checks Configure manually.
Webhooks Reconfigure on the GitLab project.
Third-party integrations Reconfigure with GitLab credentials.
Deployment secrets Recreate as CI/CD Variables (Masked, Protected where applicable).
Environments and protected variables Recreate per environment.

Role mapping

When the importer brings collaborators in, GitHub roles map to GitLab roles:

GitHub GitLab
Read Guest
Triage Reporter
Write Developer
Maintain Maintainer
Admin Owner

Per-artifact verification

After import, verify each artifact type before announcing the migration is done.

Repository

  • git ls-remote against both remotes — branches, tags, and head SHAs match.
  • The default branch is set correctly on the GitLab project.
  • LFS-tracked files resolve (git lfs ls-files).

Issues

  • Plan → Issues count matches GitHub for each state (open, closed).
  • A sample of issues has the right description, comments, labels, assignees.
  • Manage → Labels shows all expected labels with the right colors.

Merge requests

  • Code → Merge requests count matches GitHub PR count.
  • A sample MR has discussion comments and review comments preserved.
  • Open MRs from forks have their fork branches present.

Milestones

  • Plan → Milestones lists all milestones with due dates and attached issues.

Wiki

  • Plan → Wiki renders all pages.
  • Internal links resolve (anchors and page paths sometimes shift).

Releases

  • Deploy → Releases lists each release with notes and tag.
  • Attachments downloaded successfully (subject to the caveats above).

Members

  • Collaborators landed under Manage → Members with the right roles.
  • Placeholder users were reviewed and reassigned where appropriate (flow).
  • Branch protection rules adjusted to GitLab equivalents.