How to migrate from GitHub Enterprise Cloud to GitLab
Move GitHub Enterprise Cloud to self-managed GitLab: design the groups first, import with GitLab’s importer, reassign users, rewrite Actions as pipelines.
In short
- GitLab’s GitHub importer brings branches, issues, pull requests with their reviews, labels, milestones, wikis, release notes and LFS objects, and maps branch protection rules to GitLab settings.
- Organisations and teams are not imported, so the GitLab group structure is designed first, and every repository is imported into a group rather than a personal namespace.
- Contributions arrive against placeholder users, which an Owner of the top-level group reassigns to real accounts once people have signed in through your identity provider.
- Each Actions workflow is rewritten as a .gitlab-ci.yml pipeline run by your own runners, and every secret is entered again, because GitHub never returns its value.
On this page (13)
Moving from GitHub Enterprise Cloud to GitLab is an import for the repositories and a rewrite for CI. GitLab’s GitHub importer reads each repository through GitHub’s API and brings its branches, pull requests, reviews, issues and wiki with it. It does not bring the structure around them: organisations and teams are designed again as GitLab groups, secrets, required status checks, webhooks and apps are created again, and every Actions workflow becomes a .gitlab-ci.yml pipeline. This guide covers the order we run the move in, onto a self-managed GitLab Community Edition, and the places it usually goes wrong.
Why teams move from GitHub Enterprise Cloud to GitLab
Three reasons come up again and again.
- Code, pipelines and images in one place you can name. GitLab keeps repositories, CI/CD and its own container and package registries in one application, on your hardware or in a region you choose. Source code, build logs and the images you ship stay together.
- CI next to what it deploys. GitLab Runner executes jobs on machines you register, inside the network where the databases, clusters and servers they deploy to already are. CI costs the machines it runs on, not minutes.
- One application, no per-user fee. Merge requests, pipelines, registries, issues, boards and wikis come in one product. Community Edition is MIT-licensed, and sign-in through OpenID Connect, SAML or LDAP needs no subscription.
What you give up is real. GitHub is where outside contributors already have accounts, and its Marketplace holds actions and apps written for it. GitHub-hosted runners cover Linux, Windows and macOS without a machine of your own. Codespaces and Copilot have no counterpart in Community Edition, and several controls teams rely on in GitHub Enterprise Cloud, such as required approvals and code owners, are GitLab Premium. GitLab is also a large application to run, which is the part Pilae takes on. If your teams mostly need a forge, Forgejo is the lighter system to run, and our GitHub to Forgejo guide covers that move.
Step 1: list what the importer leaves behind
GitLab’s importer reads a fixed set of things from each repository. Everything else needs an owner and a decision before the first batch moves.
What the GitLab GitHub importer brings across
Imported
- The Git history, every branch, and the fork branches of open pull requests
- Git LFS objects
- Pull requests, with reviews, review comments, suggestions and who merged them
- Issues, labels and milestones, with their comments
- Wiki pages, release notes and the repository description
- Branch protection rules, mapped to GitLab settings
- Direct collaborators, as members, if you choose
- Markdown attachments, if you tick the option
Stays behind
- Organisations, teams and outside collaborators
- Actions secrets, variables and environments
- Required status checks and rulesets
- Webhooks, deploy keys and GitHub Apps
- Packages and container images
- Discussions, Projects and GitHub Pages
For each repository you move, list:
- Workflows: the
runs-onlabels they ask for, the actions theyuses:, the events that start them and the environments they deploy to. - Secrets and variables, by name.
gh secret listshows a repository’s secret names; GitHub’s API returns a secret’s name and dates but never its value, so note where each value comes from: a vault, a cloud console, the system that issued it. - Branch protection and rulesets, with the reviews, status checks, code owner rules and signed commits each one enforces. The importer reads branch protection rules; rulesets are recorded by hand.
- Webhooks, deploy keys and GitHub Apps, with what each one feeds and who owns it.
- Packages on GitHub Packages and images on ghcr.io, and every system that pulls them.
- References to github.com in the code:
.gitmodules, module paths, package manifests, image names, deployment scripts and badges. - Custom repository roles. GitLab documents that the importer does not support them and that a repository using one imports only partially.
Each line ends with a target: rebuilt in GitLab, replaced by another tool, or dropped, with the GitLab tier it needs. Those tiers decide the edition.
Step 2: design the groups and sign-in
The importer creates projects, not structure: GitLab’s documentation says that importing does not migrate any type of group or organisation from GitHub. Build the structure first, because permissions in GitLab inherit down the group tree and each repository should land where its access is already right.
| GitHub | GitLab |
|---|---|
| Organisation | Top-level group |
| Enterprise with several organisations | Several top-level groups, or one with a subgroup per organisation |
| Repository | Project |
| Team | Subgroup, or a group invited to projects with a maximum role |
| Repository roles Read, Triage, Write, Maintain, Admin | Guest, Reporter, Developer, Maintainer, Owner, as the importer maps them |
| Outside collaborator | Member of the project only |
| SSH keys and personal access tokens | Added again by each person in their user settings |
Three rules shape the design:
- Membership inherits downwards. A member of a group is a member of every subgroup and project below it, and GitLab does not let a membership lower in the tree carry a lower role than one inherited from above.
- Invited groups are capped. When a group is invited to a project, its members get the lower of the maximum role you set and their role in their own group. Members of its subgroups get nothing unless the subgroup is invited too.
- Import into groups, never personal namespaces. Contributions in a project imported into a personal namespace are assigned to its owner and cannot be reassigned later. In a group, they wait for step 6.
Sign-in. Community Edition signs people in through OpenID Connect, SAML or LDAP without a subscription. An administrator adds Keycloak or Entra ID as an OmniAuth provider in /etc/gitlab/gitlab.rb, and allowing single sign-on for that provider creates each account at the person’s first sign-in. For Keycloak, GitLab requires HTTPS and recommends tokens signed with a public key algorithm such as RS256, set under Realm Settings, Tokens, Default Signature Algorithm.
# /etc/gitlab/gitlab.rb (excerpt): sign-in through a Keycloak realm
gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_providers'] = [
{
name: 'openid_connect',
label: 'Keycloak',
args: {
name: 'openid_connect',
scope: ['openid', 'profile', 'email'],
response_type: 'code',
issuer: 'https://sso.acme.internal/realms/acme',
client_auth_method: 'query',
discovery: true,
uid_field: 'preferred_username',
pkce: true,
client_options: {
identifier: 'gitlab',
secret: '<client secret>',
redirect_uri: 'https://gitlab.acme.internal/users/auth/openid_connect/callback'
}
}
}
]
Group membership is the part that needs Premium: group sync from LDAP or SAML, and OpenID Connect rules that require a directory group or grant roles from one. Without Premium, people sign in with their directory account and their group memberships are set in GitLab, by hand or through the API. The directory does not reach SSH keys or personal access tokens, so offboarding also blocks the account in GitLab.
Step 3: import the repositories in batches
Prepare the instance. An administrator turns on GitHub under Admin, Settings, General, Import and export settings, Import sources. Whoever runs the import needs the Maintainer or Owner role on the destination group.
Choose how GitLab reads GitHub. The importer accepts two kinds of credential:
- A classic personal access token with the
reposcope, plusread:orgto import collaborators or LFS objects. GitLab supports classic tokens only. On an organisation that enforces SAML single sign-on, GitHub requires the token to be authorised for the organisation under Configure SSO before it can read it. Thereposcope also grants write access, so create the token on an account that can read every repository being moved, and revoke it when the move is over. - GitHub OAuth, once GitHub is set up as a provider on the instance, which can serve imports without serving sign-in. Have your Enterprise Cloud organisation own the OAuth app, not a personal account: GitLab documents that this gets a higher GitHub API rate limit. Clear Expire user access tokens on it, because GitLab notes that long imports can fail when an expiring token runs out.
Trial first. Import a few representative repositories as a trial, including the one with the longest pull request and issue history. The largest one tells you how long its batch will take; the others give step 4 real projects to build pipelines on. Re-import creates a new copy under a new name, so delete the trial projects before the real batch.
One batch from the screen. In the upper-right corner, select Create new, then New project/repository, Import project and GitHub. The Organization tab lists the repositories of an organisation you belong to, and a name filter narrows the list: Import all repositories imports what the filter matched. Each row proposes the GitHub name as its target; point it at the group designed in step 2. Two options apply:
- Import Markdown attachments is off by default to keep imports fast. Without it, images and files in issues, pull requests and release notes stay links to GitHub, which break once GitHub removes them. Tick it. On an organisation that enforces SAML single sign-on, GitLab warns that attachments can fail to import, and its workaround is adding the account that runs the import to the repository as an outside collaborator.
- Import collaborators is on by default and imports direct collaborators as members, with roles as high as Owner. Untick it when access comes from the groups you built in step 2.
A batch by script. The import API takes the same options and a target namespace per repository, so a list from the inventory drives the whole move. GitLab rate-limits the endpoint per user, together with imports started from the screen, so the loop pauses between requests:
# repos.tsv: GitHub repository ID, then the target GitLab group, one repository per line
# gh api --paginate orgs/acme/repos --jq '.[] | [.id, .name] | @tsv' lists the IDs
while IFS=$'\t' read -r repo_id target; do
curl -sS --request POST "https://gitlab.acme.internal/api/v4/import/github" \
--header "Authorization: Bearer ${GITLAB_TOKEN}" \
--header "Content-Type: application/json" \
--data "{
\"personal_access_token\": \"${GITHUB_TOKEN}\",
\"repo_id\": ${repo_id},
\"target_namespace\": \"${target}\",
\"optional_stages\": { \"attachments_import\": true, \"collaborators_import\": false }
}"
sleep 10 # stay under the import endpoint's rate limit
done < repos.tsv
The rate limit sets the pace. GitHub caps the API requests a token can make each hour, and GitLab’s developer documentation says that when the importer runs out, it reschedules its work until the limit resets. The same page says the request count depends mostly on the number of distinct people in the history, whose details the importer looks up, not on the size of the code, so a large project can take days. An administrator can give the importer’s Sidekiq queues more processes; GitLab notes that this does not shorten the clone itself.
Freeze each batch as it moves. The importer reads each repository once: an issue or pull request opened on GitHub after its stage has run does not follow. Archive the batch’s repositories on GitHub just before their import: an archived repository is read-only for everyone and still readable, and rolling back is unarchiving it. The largest repositories start days ahead of their batch, either archived for the whole import, or imported with GitHub still open and their branches pushed again at the switch, with issues opened in between left readable on GitHub.
Check every project. Each import ends as Complete, Partially completed or Failed, and Details lists what did not come across. One difference shows in the result: GitHub uses # for both issues and pull requests, while GitLab writes ! for merge requests, so in imported comments GitLab links #123 to issues only, and in descriptions it creates no links at all.
Step 4: rewrite the workflows as pipelines
CI is the long part of the move, so this work starts on the trial imports from step 3, while GitHub is still where people work, and each batch’s .gitlab-ci.yml is ready when the batch moves. GitLab publishes a guide to migrating from GitHub Actions and is explicit that some of its equivalents are not exact matches.
| GitHub Actions | GitLab CI/CD |
|---|---|
Files in .github/workflows |
.gitlab-ci.yml at the root, and the files it includes |
on: events |
workflow: rules and job rules, on $CI_PIPELINE_SOURCE |
| A job | A job in a stage; needs: lets it start before its stage |
runs-on: |
tags:, matched against the tags of a runner |
steps: and run: |
script:, one command per line |
uses: an action |
A script, an include: or a CI/CD component |
env: |
variables: |
secrets.NAME |
A CI/CD variable set in the project, masked and protected |
strategy: matrix |
parallel: matrix |
| Upload and download artifact | artifacts: with expire_in:; later jobs receive the files |
actions/cache |
cache: |
GITHUB_TOKEN |
CI_JOB_TOKEN, valid only while the job runs |
permissions: id-token: write |
id_tokens: with the audience the cloud provider expects |
schedule: and workflow_dispatch: |
Pipeline schedules, and manual jobs (when: manual) |
A typical test and deploy workflow becomes this. The runner fetches the repository before the script runs, so actions/checkout has no counterpart.
# .gitlab-ci.yml: a test and deploy workflow, rewritten
default:
image: registry.acme.internal/ci/node # was container:, or the tools on GitHub's runner
tags: [linux] # was runs-on: ubuntu-latest
stages: [test, deploy]
workflow:
rules: # was on: pull_request, and on: push to main
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
test:
stage: test
script:
- npm ci
- npm test
deploy:
stage: deploy
needs: [test]
environment: production
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
script:
- ./deploy.sh # DEPLOY_TOKEN is a masked, protected CI/CD variable
Secrets become variables
Each secret from the step 1 list is entered under Settings, CI/CD, Variables, by a Maintainer. Mark it Masked so it stays out of job logs, or Masked and hidden so it can never be displayed again after it is saved, and Protected so only pipelines on protected branches and tags receive it. Never put a secret in .gitlab-ci.yml, which everyone with access to the project can read. GitHub environment secrets become variables scoped to an environment, which works per project in every tier; scoping a group variable to an environment, protected environments and deployment approvals are Premium.
Actions become scripts, includes or components
Marketplace actions have no counterpart to import into. Most setup actions become a line in the script or a tool baked into the job image. Configuration that several projects share becomes a CI/CD component or an include: of a file in a common project. Actions that call GitHub’s API, to comment on a pull request or create a release, are the ones most likely to break: rewrite them against GitLab’s API with CI_JOB_TOKEN or a project access token. A job token reaches another project only once that project allows it.
Runners
A job runs on a runner whose tags match its tags:. Each runner is created in GitLab, for the instance, a group or a project, with its tags, then registered on its machine with the token GitLab shows. GitLab Runner installs on Linux, Windows and macOS, so jobs that ran on GitHub’s Windows or macOS runners need machines of those kinds registered for them.
Container builds need a decision. A job that runs docker build needs a Docker daemon. GitLab documents the options: Docker-in-Docker, which gives each job its own daemon but needs privileged mode; binding the host’s Docker socket, which it warns can expose the host to privilege escalation; or a builder that needs no daemon, such as Buildah or rootless BuildKit, which is what GitLab points to when privileged mode is not an option.
Step 5: rebuild protection, webhooks and packages
Work through the step 1 list, project by project, before the batch’s developers switch.
| GitHub | GitLab |
|---|---|
| Require a pull request before merging | Imported: Allowed to push and merge set to No one |
| Required status checks | Pipelines must succeed, under Settings, Merge requests, Merge checks |
| Required approvals | Approval rules, Premium; in Community Edition approvals do not block a merge |
| Code owners | CODEOWNERS at the root, in docs/ or in .gitlab/; code owners are Premium |
| Require signed commits | Imported as the Reject unsigned commits push rule, Premium |
| Rulesets across an organisation | Protected branches per project; protected branches for a whole group are Premium |
| Webhooks | Project webhooks, recreated; group webhooks are Premium |
| Deploy keys | Deploy keys in each project |
| GitHub Apps | A project integration, a webhook, or a bot with a project access token |
| Dependabot | Renovate, which supports GitLab as a platform; dependency scanning is Ultimate |
| GitHub Packages and ghcr.io | The package and container registries of each project |
| Discussions | Readable in the archived repository; decisions worth keeping copied into issues |
Status checks. GitLab does not import the required status checks rule. Its counterpart for checks that run in GitLab is Pipelines must succeed, which blocks a merge until the merge request’s pipeline passes; leave Skipped pipelines are considered successful off unless you mean it. Checks run by an outside system become external status checks, which are Ultimate.
Code owners. GitHub reads CODEOWNERS from .github/ first; GitLab looks at the root, then docs/, then .gitlab/, so a file under .github/ is moved. Code owners are a Premium feature, and the file decides approvals only on a protected branch with code owner approval switched on.
Webhooks. Create each one again under Settings, Webhooks. The payloads are GitLab’s own, with an X-Gitlab-Event header and no X-Hub-Signature-256: GitLab sends either a secret token in plain text in X-Gitlab-Token, which it no longer recommends for new webhooks, or, with a signing token, an HMAC-SHA256 signature in a webhook-signature header. Change and test each receiver before the GitHub webhook is removed.
Packages and images. GitLab says moving container images into its registry is not supported as such and points to third-party tools: each image is pulled from ghcr.io and pushed again with a copy tool such as skopeo, under GitLab’s naming, <registry>/<group>/<project>[/<path>]. For packages, GitLab publishes Packages Importer, an open-source tool that copies npm, NuGet, Maven and PyPI packages between registries. Then every reference changes: image names in deployments, .npmrc and other client settings, and the jobs that publish.
Step 6: reassign contributions to real accounts
Every author, reviewer and assignee in the imported history arrives as a placeholder user, and imported memberships wait on placeholders too. On a self-managed instance there is no limit on placeholders unless an administrator sets one.
- People sign in once through the identity provider from step 2, which creates their GitLab account.
- An Owner of the top-level group opens Manage, Members, Placeholders. On Awaiting reassignment, they choose each person’s account under Reassign placeholder to and select Reassign. For many people, Reassign with CSV downloads a prefilled file to complete with each GitLab username or public email address.
- Each person approves. They receive an email and approve the reassignment in GitLab; the link in the email does not start it. On a self-managed instance, an administrator can turn on Skip confirmation when administrators reassign placeholder users under Admin, Settings, General, Import and export settings, and reassign without that step.
- Leavers stay as placeholders. Do not reassign, or Keep all as placeholders, keeps their contributions in the history, attributed to the placeholder.
Reassignment is permanent: GitLab says it cannot be undone. Check the CSV against your directory before uploading it.
Step 7: switch remotes and archive GitHub
When a batch has been imported, its pipelines pass and what stayed behind is rebuilt, its developers switch.
Switching one batch, with a way back
- Freeze: The batch’s GitHub repositories are archived, read-only for everyone.
- Import: Each repository is imported into its group, and its pipelines run.
- Rebuild: Variables, protection and webhooks are in place, and owners compare branches, tags and merge requests.
- Switch: Developers point their clones at GitLab, and deployments pull from it.
- Roll back if needed: The GitHub repository is unarchived and the GitLab project deleted.
Each developer adds their SSH key in their GitLab user settings and points every clone at the new address:
git remote set-url origin git@gitlab.acme.internal:acme/billing/billing-api.git
Then the references from step 1: .gitmodules entries followed by git submodule sync, module paths and package manifests, image names that pointed at ghcr.io, and every deployment or script that clones from github.com.
Archive what is left on GitHub from each repository’s Settings, under Danger Zone, Archive this repository. GitHub’s documentation describes an archived repository as read-only for all users, with code, issues and pull requests still readable. Keep the archives until each owner signs off, and longer where imported issues still link to anything left on GitHub. Once the last batch has moved, revoke the import token, delete the OAuth app, and remove GitHub as an import source and sign-in provider.
Running GitLab in production
A forge that every engineer pushes to and every deployment pulls from needs more than the package.
- PostgreSQL, the only database GitLab supports, bundled in the Linux package. Its own upgrades are part of GitLab’s upgrade path.
- Repositories on local disks. Gitaly needs at least as much disk as all repositories combined, and GitLab warns that NFS and cloud file systems can significantly affect performance.
- Buckets from the first day. Artifacts, LFS objects, uploads, packages and container images go to S3-compatible object storage, one bucket per type. Moving them off local disk later is a migration of its own.
- Runners on machines of their own. GitLab advises against running CI jobs on the GitLab host, for security and for performance.
- Backups of three things. The backup command writes the database and the repositories, not the buckets and not
/etc/gitlab, wheregitlab-secrets.jsonholds the key to CI/CD variables and two-factor secrets. Without that file, the variables you entered in step 4 cannot be decrypted after a restore. - An SMTP relay for notifications and for the reassignment requests of step 6.
- Upgrades along the path. GitLab publishes required upgrade stops, and background migrations must finish before the next step.
Pilae operates GitLab this way: Community Edition unless your requirements need a paid tier, buckets in the same location from the first day, and runners on machines of their own, registered over the private network with one pool per level of trust. The backup archive, the buckets and /etc/gitlab with the SSH host keys go offsite daily, encrypted, to a location in the country your contract names, and on Enterprise a restore test every month brings all three back into a scratch instance of the same version, recorded in the console. Probes read GitLab’s readiness check every 60 seconds and alert an engineer. The Pilae Agent rehearses each step of the upgrade path on a copy, waits for your approval and applies it in your window. GitLab runs on your premises or on dedicated machines in Pilae Cloud, answering only on your private network.
Let Pilae run the move
Pilae runs GitHub Enterprise Cloud to GitLab migrations at a fixed price: the inventory of what stays behind, the group structure and sign-in, the import in batches, runners and the pipeline rewrite, the rebuild of variables, protection and webhooks, the reassignment of contributions, and the switch of every batch. Where your requirements need GitLab Premium or Ultimate, the subscription is named in the proposal and held in your name with GitLab. Then we operate GitLab for you under a contract that, from the Business plan, includes a monthly availability commitment with service credits. See migration services for what the fixed price covers, or tell us about your GitHub organisation and we will scope it.
Questions
What does the GitLab importer bring across from GitHub?
What stays behind on GitHub?
Will our GitHub Actions workflows run on GitLab?
Which GitLab features need a paid tier?
Is GitLab open source?
How long does a GitHub to GitLab migration take?
Let us run the move for you
An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.
- Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
- CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.
