How-To Guide · Repository Migration

How to Migrate from GitHub to GitLab — Step by Step

GitLab ships a built-in GitHub importer that brings across the repository, issues, pull requests as merge requests, wiki, milestones and labels. It works well, but it has real limitations that are much cheaper to discover before a cutover than after one — particularly around user attribution and comment history. This guide covers what actually transfers, what quietly does not, the two authentication routes and why the easier one is the one GitLab advises against, and how to verify a migration properly before you tell a team to stop pushing to GitHub.

Steps

Inventory what you are actually moving: Before touching the importer, list every repository with its size, whether it uses Git LFS, how many open issues and pull requests it carries, and what CI it runs. Repositories are rarely the hard part — CI configuration, webhooks, deploy keys, branch protection rules and integrations with issue trackers or chat are, and none of them come across in an import. Migrate in batches, starting with a low-traffic repository as a rehearsal.
- Flag large repositories and anything using Git LFS early — both need extra handling and time
- List webhooks, deploy keys and branch protection rules per repository; these are rebuilt manually on the GitLab side
- GitHub Actions workflows do not convert — every repository needs a `.gitlab-ci.yml` written
- Pick one small, active-but-not-critical repository as the rehearsal before committing to a schedule
Choose your authentication route — and understand the trade-off: The importer accepts either the GitHub integration (OAuth) or a personal access token. The token route is faster to set up and it is the one GitLab explicitly advises against, because a PAT-based import cannot reliably associate activity with matching GitLab users. Importing into a personal namespace is worse still: contributions are all assigned to a single non-functional account called Import User and cannot be reassigned afterwards. If attribution matters to you at all, use the GitHub integration and import into a group namespace.
- Prefer the GitHub integration over a personal access token — GitLab recommends it for a reason
- Import into a group namespace, never a personal one, if you want contributions attributed correctly
- PAT imports into a personal namespace assign everything to "Import User" permanently — this is not fixable later
- Have your GitLab users created and their GitHub email addresses matching before you import, so mapping can succeed
Run the import: In GitLab, choose New project → Import project → GitHub, authenticate, and select the repositories to bring across. The importer pulls the repository description, full git history, issues, pull requests (converted to merge requests), wiki pages, milestones and labels. Large repositories take a while and the import runs in the background — you can leave the page. Import in small batches so a failure affects one repository rather than forty.
- New project → Import project → GitHub is the whole entry point
- Full git history transfers — commits, branches and tags are intact
- Pull requests become merge requests, keeping the discussion thread where it can be mapped
- Batch imports in groups of five to ten so a failure is contained and easy to retry
Know what the importer does not bring: This is the step that saves the project. Issue and pull request events — opened, closed, renamed, labelled and unlabelled — are not imported by default, and comments may be skipped. GitHub Actions workflows, branch protection rules, webhooks, deploy keys, GitHub Apps and repository settings do not transfer at all. Nothing warns you loudly about any of this; it simply is not there afterwards. Decide before cutover whether the missing history matters enough to keep GitHub in read-only archive mode.
- Issue and PR events are not imported by default, and comments can be skipped — check a busy issue specifically
- GitHub Actions workflows do not convert to `.gitlab-ci.yml` — budget rewrite time per repository
- Branch protection, webhooks, deploy keys, environments and secrets are all rebuilt by hand on the GitLab side
- Keeping the GitHub org read-only for a few months is cheap insurance against lost discussion context
Rebuild CI/CD as .gitlab-ci.yml: This is usually the largest piece of real work in the migration. GitHub Actions and GitLab CI/CD express similar ideas with entirely different syntax, so workflows are rewritten rather than converted. The mapping is reasonably clean: Actions jobs become GitLab jobs, `runs-on` becomes an `image` plus runner tags, repository secrets become masked CI/CD variables. Rebuild the pipeline before cutover and run both in parallel for a few days so you can compare results on the same commits.
- Jobs map to jobs; `runs-on` maps to `image` plus runner tags; steps map to `script` lines
- Recreate GitHub secrets as masked, protected CI/CD variables under Settings → CI/CD → Variables
- Run GitLab pipelines in parallel with Actions for several days and diff the outcomes before you trust them
- Take the opportunity to add caching and parallel test jobs — most migrated pipelines are faster than the originals
Verify before you cut over: Check the things that are easy to assume and expensive to get wrong. Confirm commit counts and branch and tag lists match between the two remotes. Open a busy issue and a busy pull request and confirm the comment thread actually came across. Check that contributions are attributed to real GitLab users rather than Import User. Confirm LFS objects resolve. Only once that passes should you announce a freeze date.
- Compare `git rev-list --count --all` and the branch and tag lists on both remotes
- Spot-check the busiest issue and the busiest pull request for comment loss specifically
- Verify user attribution on a sample of merge requests — Import User attribution cannot be fixed later
- If the repository used LFS, clone fresh and confirm large files actually pull down
Cut over and archive the source: Announce a freeze window, do a final incremental import to pick up anything pushed since the first pass, then set the GitHub repositories to read-only or archived rather than deleting them. Update every remote your team and infrastructure use — developer clones, deployment scripts, CI in other systems, documentation links and any integration pointing at the old URL. Keep GitHub archived for at least a few months.
- Freeze GitHub, run a final incremental import, then flip GitHub to read-only or archived
- Developers update remotes with `git remote set-url origin <new-gitlab-url>` — send the exact command
- Hunt down deployment scripts, external CI, documentation links and chat integrations pointing at the old URL
- Do not delete the GitHub org for several months — that unimported event history is your only archive of it

Frequently Asked Questions

What actually transfers from GitHub to GitLab?

The GitHub importer brings the repository description, the complete git history including branches and tags, issues, pull requests converted to merge requests, wiki pages, milestones and labels. That covers the substance of most repositories. What it does not bring is repository configuration — webhooks, deploy keys, branch protection, environments and secrets — or GitHub Actions workflows, all of which are rebuilt manually on the GitLab side.

Will we lose comment history?

Possibly, and this is the limitation worth testing before committing. GitLab documents that issue and pull request events — opened, closed, renamed, labelled, unlabelled — are not imported by default, and that comments may be skipped. Import one busy repository first and inspect its most-discussed issue and pull request specifically. If context matters to your team, keep the GitHub organisation archived and read-only rather than deleting it.

Why does GitLab advise against using a personal access token?

Because a PAT-based import cannot reliably associate imported activity with matching GitLab users. Issues and pull requests end up attributed incorrectly, and when you import into a personal namespace all contributions are assigned to a single non-functional account called Import User which cannot be reassigned afterwards. The GitHub integration route handles user mapping properly. Given the attribution damage is permanent, the extra setup is worth it.

Do GitHub Actions workflows convert to GitLab CI?

No — they are rewritten. The two systems express similar concepts in incompatible syntax, so each workflow becomes a hand-written `.gitlab-ci.yml`. The mapping is straightforward once you have done one: Actions jobs to GitLab jobs, `runs-on` to an `image` plus runner tags, steps to `script` lines, repository secrets to masked CI/CD variables. Budget real time for this per repository, and run both pipelines in parallel before you trust the new one.

How long does a GitHub to GitLab migration take?

The import itself is minutes to a couple of hours per repository depending on size and history. The project around it is what takes time: inventorying repositories, rebuilding CI, recreating webhooks and branch protection, updating remotes across developer machines and deployment scripts, and verifying. A handful of repositories is comfortably a day or two. A large organisation with dozens of active repositories and complex CI is a multi-week project run in batches.

Can you run the migration for us?

Yes — repository migration is one of the projects we run for Indian teams moving to GitLab, alongside the licensing. That covers inventory and batching, running imports with correct user mapping, rebuilding CI/CD as `.gitlab-ci.yml`, recreating branch protection and webhooks, verification, and cutover coordination so the freeze window is short. WhatsApp +91 98119 98370 with your repository count and CI complexity for a scoped quote in INR with GST invoice.