GitHub-to-GitLab migration the easy way
To search repositories and projects, login to gitlab.com . Suggestions GitLab Duo Agent Platform Code Suggestions (AI) CI/CD GitLab on AWS GitLab on Google Cloud Why GitLab? Updated on: August 18, 2026 12 min read GitHub-to-GitLab migration the easy way Learn how easy it is to migrate from GitHub to GitLab using GitLab's project importer and GitLab Duo AI. Fernando Diaz CI/CD tutorial DevSecOps DevSecOps platform AI If you're evaluating a move to GitLab, the first question is almost always the same: How hard is the migration?
For most DevSecOps teams, the fear of "heavy lifting" is the biggest obstacle between them and a single, AI-native DevSecOps platform . Migrating to GitLab is easier than ever. GitLab's built-in importer moves the vast majority of your project data automatically and in the background. Additionally, translating your CI/CD pipeline, one part that has traditionally required a human, is now largely handled by GitLab Duo .
Duo, our AI-native assistant, can convert GitHub Actions workflows into GitLab CI/CD. In this post, I'll walk through the full migration end to end: What data migrates, and which items are automatic , work with caveats , or are manual The prerequisites you actually need in GitLab 18.x (fewer than you might think) Three ways to run the import: UI (OAuth), personal access token, and the REST API for bulk moves How to convert GitHub Actions to GitLab CI/CD — the traditional way and the fast way with GitLab Duo Other platforms GitLab can import from Let's get started.
What data migrates from GitHub to GitLab? GitLab's built-in GitHub importer is accessed directly from GitLab's project creation UI, and it runs as a background job, meaning you can kick off an import and walk away. Most of your project data comes across automatically. A smaller set of items are optional toggles or have caveats worth knowing about up front. The table below breaks down what migrates and how: Data Status Git repository, branches, tags, and commit history ✅ Automatic.
Includes fork branches for open pull requests. Issues ✅ Automatic Pull requests (become merge requests) ✅ Automatic. Includes reviews, review comments, suggestions, assigned reviewers, and "merged by" info. Issue and pull request comments ✅ Automatic Labels and milestones ✅ Automatic Release notes content ✅ Automatic Wiki pages ✅ Automatic Branch protection rules ✅ Automatic Issue and pull request events ✅ Automatic Collaborators (members) ⚠️ With caveats.
Optional toggle (on by default). Requires the read:org scope; GitHub roles are mapped to GitLab roles (see below). GitHub Enterprise Cloud custom roles aren't supported and are added manually. Markdown attachments (in descriptions, comments, releases) ⚠️ With caveats. Optional toggle. Attachments in private repos from before May 2023 can't be imported (a GitHub limitation); GitHub Enterprise Server imports only images and video.
Large comment volumes (~30,000+) ⚠️ With caveats. Enable the alternative comments import to work around GitHub's per-issue API limits. Comments from before 2017 may import as separate threads. Git LFS objects ⚠️ With caveats. LFS must be enabled on the destination project before the import runs, or objects are silently skipped. GitHub Actions workflows 🛠️ Manual (AI-assisted). Converted to .gitlab-ci.yml .
GitLab Duo can do most of this for you. Secrets → CI/CD variables 🛠️ Manual. Recreate secrets as CI/CD variables (mark them masked/protected) before running pipelines. Required status checks 🛠️ Manual. Recreate as external status checks . GitHub Organizations / groupings ❌ Not migrated. Structure GitLab groups and subgroups to match. How roles are mapped GitHub and GitLab use different naming conventions, so a mapping is performed during migration.
When collaborators are imported, GitHub roles map to GitLab roles as follows: GitHub role GitLab role Read Guest Triage Reporter Write Developer Maintain Maintainer Admin Owner Prerequisites The prerequisites have gotten simpler over the years. Notably, you no longer need every GitHub author to have a matching public email address on GitLab. GitLab now handles attribution automatically with user contribution mapping (GitLab 17.8+).
More on that below. To import from GitHub.com or GitHub Enterprise Server into either GitLab.com or a GitLab Self-Managed instance, you need: Access to the source GitHub project you want to import. The Maintainer or Owner role on the destination GitLab group. The GitHub import source enabled . This is on by default on GitLab.com; on GitLab Self-Managed, an administrator enables it under import sources . The GitHub organization must not restrict third-party application access (or you must grant access to it during authorization).
A couple of situational prerequisites: Importing Git LFS objects? Enable LFS on the destination project before you import. Importing collaborators? You need the read:org scope on your token and at least Write or Maintain access on the GitHub project. You don't need matching emails anymore Previously, contribution history only carried over cleanly if each GitHub user's public email matched their GitLab email. Today, GitLab creates placeholder users for any GitHub author, assignee, or reviewer without a matching GitLab account, and preserves their contributions.
After the import, a group Owner or Maintainer goes to Members → Placeholders and reassigns each placeholder to the real GitLab user, who then accepts the reassignment. This means you can migrate first and sort out attribution afterward. Performing the import There are three ways to run the import. Pick the one that fits your source and scale. Method 1: The UI with GitHub OAuth (recommended for GitLab.com) This is the fastest path for most teams.
Go to a group and select Create project → Import project → GitHub (or start directly at gitlab.com/projects/new#import_project ). Press the Authenticate with GitHub button and approve the OAuth application. For organization repositories, click Grant next to the organization name to authorize access. Filter your repositories using the Owner / Collaborated / Organization tabs, then select the repositories to import.
You can rename them and choose the target GitLab namespace. Configure the optional toggles (see table below), then click Import . The import runs as a background job; you can navigate away and check back later. Optional toggles: Toggle Default Use it when Import collaborators On You want project members brought over with role mapping. Import Markdown attachments Off You want images and files embedded in descriptions, comments, and releases.
Use alternative comments import Off Your project has ~30,000+ comments and you're hitting GitHub API limits. Method 2: Personal access token (when OAuth isn't configured) If OAuth isn't configured, authenticate with a token instead. Create a classic personal access token at github.com/settings/tokens/new with the repo scope (add read:org if you're importing collaborators or LFS). Note: Fine-grained tokens aren't supported.
In GitLab, go to a group and select Create project → Import project → GitHub . Paste the token, select Authenticate , then complete the same selection and configuration steps as the OAuth method. Method 3: The REST API (bulk imports and scripting) For migrating many repositories at once, scripting a move, or importing public repos you don't own, use the import API . curl --request POST \ --url "https://gitlab.com/api/v4/import/github" \ --header "PRIVATE-TOKEN: $GITLAB_TOKEN " \ --header "Content-Type: application/json" \ --data '{ "personal_access_token": "<github_classic_pat>", "repo_id": 12345678, "target_namespace": "my-group", "new_name": "imported-project", "optional_stages": { "single_endpoint_notes_import": true, "attachments_import": true, "collaborators_import": true } }' Track progress with: curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN " \ "https://gitlab.com/api/v4/
The rest of this page is on the live site.