GitLab to GitHub Enterprise Migration Playbook: Repositories, Issues, CI/CD Pipelines, Runners → Actions, and Security Without Downtime

Published by Bles Software, a custom software and AI company based in Yehud-Monoson, Israel, building web apps, AI agents and API integrations for clients in Israel, the US, the UK and the EU.

Consolidating developer workflows onto GitHub Enterprise can simplify identity, policy enforcement, and ecosystem integrations—especially if your organization already anchors on Microsoft 365 and Azure AD. But a GitLab → GitHub migration touches every layer of software delivery: repository hosting and access models, issues and project boards, CI/CD (from GitLab CI to GitHub Actions), artifacts and container registries, merge request patterns, and security scanning. Success requires careful planning, precise mapping, and an adoption‑first mindset that meets teams where they are.

This playbook presents a practical, battle‑tested approach to move from GitLab (SaaS or self‑managed) to GitHub Enterprise Cloud/Server. It describes how to inventory and map projects, translate CI pipelines and runners to Actions and runners, move issues and project views, and harden security posture without dragging timelines. You will learn how to run a phased cutover that keeps velocity high, reduces risk, and lands GitHub’s value quickly.

Why Move: Business and Engineering Outcomes

Organizations typically migrate for one or more reasons:

Platform consolidation around GitHub’s ecosystem and marketplace, with tight integrations to IDEs (Codespaces), security (Dependabot/CodeQL), and collaboration (Issues/Projects/Discussions).
Consistent identity and policy enforcement via Azure AD/OIDC, SSO, SAML, and SCIM provisioning.
Simplified developer experience with GitHub Actions and reusable workflows, consistent secrets management, and a rich actions marketplace.
Strategic alignment: investment in enterprise support, shared knowledge base, and a broader hiring pool familiar with GitHub primitives.

Measure success in adoption terms: percentage of teams shipping on GitHub Actions within 60 days, reduction in bespoke CI infrastructure, improved time‑to‑merge, and clearer governance around repositories and environments.

Discovery: Inventory, Dependencies, and Stakeholders

Start with facts:

Projects and repositories: total count, size, activity, default branches, protection rules, and archival candidates.
Groups/subgroups vs. GitHub organizations/teams: ownership, permissions, and external collaborators.
Issues, epics, and boards: usage of labels, milestones, templates, and cross‑repo linkage.
CI/CD: pipeline definitions (.gitlab-ci.yml), templates, shared runners vs. project runners, artifacts, caches, and deployment targets (Kubernetes, VMs, serverless).
Registries: container images (GitLab Container Registry), package registries (npm, Maven, NuGet), and versioning strategies.
Integrations: webhooks, Slack/Teams notifications, Jira links, and SAST/DAST scanners.
Compliance: branch protection, approvals, code owners, secrets, audit requirements.

Engage product engineering, platform engineering/DevOps, security, and program management. Name migration champions in each domain who will adapt patterns and templates.

Target Architecture and Governance on GitHub

Define where repositories live, how access is granted, and how pipelines run:

Organizations: create one or a few GitHub organizations aligned to business domains. Within each, establish teams reflecting ownership (e.g., Payments, Mobile, Data). Avoid one organization per team; management complexity explodes.
Repositories: keep monorepos where justified; otherwise, prefer service‑oriented repos with clear ownership. Configure branch protection rules (required status checks, reviews, signed commits) centrally with org policies and repository rulesets.
Environments and secrets: model dev/test/prod environments per repo; store deployment secrets in environments or at org level with least privilege. Use OIDC‑based federation to cloud providers to reduce long‑lived credentials.
Runners: standardize on GitHub‑hosted runners when possible; for self‑hosted, provision in a hardened VPC/VNet with ephemeral pools and auto‑scaling. Tag runners for workload types (linux‑docker, windows, macos) and align to repository/security policies.

Mapping Repositories and Access

Plan migration waves based on affinity (shared dependencies) and risk. For each repo:

Decide whether to migrate history in full or to start fresh (rare). Full history is preferred for audit and developer context.
Map GitLab groups and members to GitHub teams and roles. Use SCIM to provision users and groups; minimize direct collaborator grants.
Recreate protected branch rules and CODEOWNERS files; align review/approval policies to compliance.

Use the GitHub Enterprise Importer or purpose‑built tooling to migrate repositories at scale. Validate tags, LFS objects, and large file handling. For massive repos, pre‑seed Git LFS storage and test fetch/push performance from representative developer networks.

Issues, Epics, Boards, and Templates

Translate GitLab issues/epics to GitHub Issues/Projects:

Labels: port as‑is, but rationalize duplicates; prefix or namespace where names collide across repos (e.g., area/frontend, type/bug).
Milestones: map to GitHub milestones or iterations if you use Projects (beta) for agile boards.
Epics: emulate via Projects, parent/child issues, or cross‑repo linked issues. Document the chosen pattern and provide templates.
Templates: convert issue and MR templates to GitHub issue and PR templates with YAML‑frontmatter defaults.

For boards, use GitHub Projects for cross‑repo views. Offer pre‑built views (by team, by priority, by epic) and train PMs on filters and saved views.

CI/CD: From GitLab CI to GitHub Actions

The heart of migration is pipeline translation. Approach it in layers:

Decompose: break .gitlab-ci.yml into discrete jobs, stages, and reusable templates. Identify environment variables, secrets, and service containers.
Map to Actions: create workflows (YAML) that mirror triggers (push, PR, schedule), jobs (matrix strategies), and caching strategies. Use actions‑cache for dependencies and Docker layer caching for container builds.
Secrets and credentials: replace plaintext variables with GitHub secrets; migrate to OIDC where possible for cloud deployments to AWS/Azure/GCP.
Artifacts: use Actions artifacts sparingly; for large outputs, write to artifact stores (S3, Azure Blob, GCS) or registries. Set retention aligned to need.
Environments and approvals: configure required reviewers for production environments; use environment‑based secrets and protection rules.

Provide a library of reusable workflow templates (composite actions) for common stacks: Node/React, Java/Spring, Python/FastAPI, .NET, iOS, Android, and data pipelines. Publish them in an internal actions registry and version them.

Runners: From GitLab Runners to GitHub Runners

If you run self‑hosted runners today, replicate the capacity model with hardened images:

Ephemeral runners: spin up a fresh runner per job using scale sets (Azure) or autoscaling groups (AWS). Bake images with pre‑cached SDKs and tools. Tear down after each job to eliminate cross‑job contamination.
Network security: restrict egress, permit only required registries and artifact stores, route through a NAT with monitoring. Use short‑lived tokens and rotate credentials automatically.
Observability: instrument runners with metrics (queue depth, job duration, failure rates). Set SLOs and alarms for backlog and error spikes.

Container Registry and Packages

Migrate images from GitLab Container Registry to GitHub Container Registry (GHCR). For each image, decide whether to preserve immutable tags or re‑tag. Update deployment manifests (Helm/Kustomize) to pull from GHCR and ensure you have appropriate scopes. For language packages, map npm, Maven, NuGet, and PyPI registries; publish from Actions with least‑privilege tokens. Create org policies for provenance (sigstore/cosign) and sign artifacts where required.

Security: From “best effort” to Built‑In Guardrails

Leverage GitHub’s native security features:

Dependabot alerts and updates: enable at org level; auto‑merge safe updates with policy.
Code scanning with CodeQL: define default queries per language; run on PRs and nightly; tune false positives.
Secret scanning: block pushes of known secret patterns; add custom patterns for internal tokens.
Branch protection: require reviews, status checks, and signed commits. For sensitive repos, enable mandatory linear history and restricted force pushes.

Overlay with your cloud security posture: use OIDC to mint short‑lived credentials; restrict deploy roles by environment; log all significant events to your SIEM (via Audit Log Streaming) and alert on anomalies (e.g., mass branch deletion, token sprawl).

Cutover Strategy: Phased with a Strong Pilot

Run a pilot with 5–10 representative teams that touch a variety of stacks and deployment targets. Port their repos and pipelines, fix paper cuts, and publish patterns. Then migrate the rest in 3–5 waves ordered by dependency graph (libraries first, services next, front‑ends). For each wave:

Freeze window: short freeze on the GitLab side for repos in scope; branch off a “cutover” branch if needed.
Repository import: bring full history, tags, and LFS; validate branch protections.
Pipeline swap: disable GitLab CI; enable GitHub Actions with a parity workflow; run side‑by‑side for a day if risk is high.
Registry switch: push new images/packages to GHCR; update deployments.
Validate: ship a routine change to production to prove the full path.

Keep GitLab read‑only for a bounded period (1–2 weeks) as a safety net, then decommission.

Detailed Migration Runbook

T‑30 to T‑21 days: Foundations

Create organizations, teams, SSO/SAML with Azure AD, and SCIM provisioning. Stand up audit log streaming to your SIEM. Define org rulesets for branch protection and security baseline. Provision runner pools, confirm network controls, and publish the initial workflow template library. Train pilot teams with hands‑on sessions.

T‑14 to T‑7 days: Pilot Rehearsal

Select 3–5 repos covering front‑end, back‑end, and infra. Migrate repos and issues, translate pipelines, and execute full deploys to non‑prod and prod. Measure job durations, cache hit rates, and failure modes; tune runner images and caching. Document missing features or actions; build or fork custom actions as needed.

T‑3 to T‑1 days: Wave Prep

Lock the wave list, post freeze windows in GitLab, and enable maintenance banners. Pre‑import repositories in dry‑run mode and stage secrets in GitHub. Finalize cutover checklists and comms. Verify GHCR permissions and retag strategies.

T‑0: Cutover

Execute the plan: import repos, set branch protections, disable GitLab CI, and enable Actions. Trigger parity builds; confirm artifact publication and deploys. For pipelines with manual approvals, validate environment protection rules. Keep a “war room” open with platform/SRE, security, and pilot champions.

T+1 to T+14: Stabilization

Close remaining GitLab merge requests; rehome incoming work to GitHub. Monitor Actions usage, runner health, and failure rates. Address integration gaps (Slack/Teams notifications, Jira links). Publish a “day 2” guide with common fixes and tips.

Performance, Scale, and Cost Management

Actions billing and runner capacity can surprise teams. Instrument job minutes by repo and category (build, test, deploy). Optimize with matrix builds, parallelization, and caching. For heavy workloads (Android/iOS, large monorepos), consider hybrid models: selective self‑hosted runners for expensive tasks and hosted runners for the rest. Control concurrency on deploy jobs to prevent stampedes. For GHCR and package registries, set retention and cleanup policies to control storage costs.

Monorepos and Caching at Scale

For monorepos with dozens of services, optimize compute and cache locality. Use a build graph to compute affected modules per change and only build/test those. Persist cache keys per module and platform, and leverage build systems with remote caching (Bazel, Gradle build cache). In Actions, split workflows by concern (lint, unit, integration, e2e) and run them in parallel, collapsing status with a required check that aggregates results. Publish job summaries with actionable links to failing tests and logs so developers spend less time spelunking. For iOS and Android, pre‑bake SDKs into runner images and mount large caches on ephemeral disks to keep warm starts under 60 seconds.

Artifact and Traceability Strategy

Decide what to keep and for how long. Store SBOMs and provenance with each build; sign artifacts and publish to GHCR or language registries with immutable versioning. For traceability, include git SHAs and build metadata in image labels and assemblies. In regulated environments, export build manifests to an audit store with retention aligned to policy. Avoid bloating Actions artifacts; ship logs to a centralized store and set short retention (7–14 days) for ephemeral artifacts.

Advanced Actions Features Worth Using

Reusable workflows reduce duplication; put them in a central repo and version them. Use concurrency groups to collapse superseded builds on long‑running branches and protect deployments from parallel triggers. Environment protection rules gate production releases with approvers and conditions. Composite actions encapsulate scripts for consistency. Matrix builds cover OS and runtime permutations without copy‑paste. Job summaries turn CI from a wall of logs into a digest developers actually read.

Runner Hardening and Secrets Hygiene

Harden self‑hosted runners like production servers: minimal base images, locked‑down SSH, patched kernels, and runtime isolation (containers or VMs). No persistent credentials on disk; fetch short‑lived tokens at job start via OIDC. Deny‑by‑default egress; allow only registries, package mirrors, and cloud APIs required for the job. Rotate images monthly; scan images for vulnerabilities and fix quickly. For secrets, centralize ownership and limit blast radius—prefer per‑environment secrets and service principals scoped to the minimum permissions.

Networking and Hybrid Environments

When pipelines reach into private networks (databases, legacy environments), establish controlled paths: private endpoints, VPN tunnels, or peered networks. For GHES on‑prem, position runners near artifact stores to reduce latency. In hybrid cloud, standardize on one ingress for deployments and secure with workload identity federation. Document allowed egress domains and ports so security teams can validate quickly.

Change Management and Training

Developers succeed when the new platform feels familiar and faster. Offer side‑by‑side comparisons of GitLab and GitHub pipelines, a cheatsheet for Actions syntax and job context, and patterns for secrets/OIDC. Host live office hours for each wave and record short videos on common stacks. Partner with security to explain how CodeQL and secret scanning help developers—not just compliance—and how to fix findings efficiently.

Create a 30‑60‑90 training plan: week 1 focuses on repo basics, PR etiquette, and using Projects; week 2–4 dives into Actions, secrets, and environment protections; week 5–8 introduces advanced topics like composite actions, matrix builds, and Codespaces. Offer office hours twice a week during waves and maintain a living FAQ. Recognize early adopters publicly and capture their templates in the central library.

Risks and Mitigations

Pipeline regressions: unit test pipeline translations in sandboxes; keep a backstop path to run critical jobs in GitLab during day one.
Credential sprawl: replace long‑lived cloud keys with OIDC; scan for leaked tokens; rotate aggressively if incidents occur.
Access drift: manage access via teams and SCIM; audit direct collaborator grants monthly; enforce SSO.
Monorepo pain: pressure test Git operations and CI times; split build/test; consider partial monorepo extraction only with strong ROI.

Budget, Roles, and Capacity

Core team: platform engineering, SRE, security, and developer champions. Budget for migration tooling (if used), runner infrastructure, actions marketplace purchases (private actions), and training. The highest ROI spend is on reusable templates and ephemeral runner automation—every team benefits.

Case Study: From GitLab SaaS to GitHub Enterprise Cloud

A 120‑team engineering org migrated 1,800 repositories over 10 weeks. They ran a two‑week pilot that covered Node/React, Java/Spring, and a data platform. CI moved to Actions with a curated set of composite actions, and OIDC replaced static AWS keys. Runner pools auto‑scaled on spot instances with pre‑baked images, cutting average job time by 28%. Security enablement shipped on day one: Dependabot alerts, CodeQL default queries, and secret scanning blocking pushes. They migrated GitLab boards and labels to GitHub Projects with templates. Teams shipped production changes within 48 hours of their cutover, and GitLab was read‑only by week three. After stabilization, the platform team reduced CI cost per build by 22% and eliminated 70% of bespoke runner maintenance.

They also instituted an “Actions Guild” of representatives from each major team that met weekly for a month to share learnings and improvements. The guild produced a canonical deployment workflow for Kubernetes with blue/green and canary strategies, an SLO for build times (p95 under 8 minutes), and a default set of checks for PRs (lint, unit, license, SAST). By quarter’s end, 92% of repos used at least one reusable workflow, and security findings time‑to‑close dropped by 35% thanks to integrated CodeQL alerts in PRs.

Enterprise Cloud vs. Server: Choosing the Platform

Decide early whether to land on GitHub Enterprise Cloud (GHEC) or GitHub Enterprise Server (GHES). GHEC accelerates access to new features (Actions hosted runners, Codespaces, advanced security) and reduces infrastructure toil. GHES suits organizations with strict data residency or offline requirements. If you choose GHES, plan upgrades every 2–3 releases to stay current and allocate SRE resources for appliances, runners, and storage. Hybrid patterns are also possible (GHES for core repos, GHEC for public/open‑source), but governance complexity increases.

Data Export/Import Patterns

Export GitLab data in layers: repositories (Git), issues/boards (API/CSV), container images (registry retag/push), and package registries. Build idempotent import scripts: re‑run without duplication, track source→target IDs, and log outcomes. For issues, maintain label/milestone parity and preserve author/created dates via impersonation where allowed. For merge requests, capture references to preserve context (e.g., link MR URLs in PR descriptions). Archive GitLab projects after import and keep a read‑only instance for a limited period.

CI Translation: Concrete Examples

Consider a typical GitLab pipeline with build/test/deploy stages, caching, and environment approvals. Translate as follows:

Build: use a matrix of language/runtime versions; cache dependencies with actions/cache keyed by lockfiles; push images to GHCR with build‑push actions and provenance.
Test: split unit/integration; run integration tests in service containers (Postgres/Redis) using docker‑compose actions; parallelize shards and upload test reports as artifacts.
Deploy: gate on protected environments; require reviewers for production; assume roles in AWS/Azure via OIDC and run IaC plans (Terraform) with state stored in a remote backend; post deploy status to PRs with links to dashboards.

Provide a side‑by‑side appendix for common stacks that developers can copy with minimal changes. Wrap brittle logic in shell scripts stored in the repo to standardize behavior.

Security Program: Code to Cloud

Adopt a layered approach: enable Dependabot alerts and updates broadly; run CodeQL on supported languages with a central query pack; wire secret scanning to block pushes and alert security. For container images, integrate SCA/OSV scans in build jobs and sign images with cosign. In cloud deploys, enforce branch protections and environment approvals, require change tickets for sensitive repos, and log all deployments. Create dashboards that aggregate alerts by repo and severity and publish SLAs for remediation.

Compliance and Audit Readiness

Map controls (SOC 2, ISO 27001, PCI) to GitHub features and processes: change management (PRs + approvals), access control (SSO/SAML + team‑based permissions), secure coding (scanning), and logging (audit stream). Document how branch protection and CODEOWNERS enforce separation of duties. For GHES, back up audit logs to immutable storage. Prepare evidence packs that show policies and sampled PRs/deploys with approvals.

Incident Response and Rollback

When a pipeline or deploy breaks post‑cutover, teams need a clear escape hatch. Provide runbooks for: re‑running specific jobs, bypassing flaky checks with approvals, rolling back via deployment tooling, and temporarily routing a critical pipeline back to GitLab (during week one only). Capture lessons learned and feed them into action items on the platform templates.

Developer Productivity Patterns

Use Codespaces or devcontainers to standardize local environments; reduce “works on my machine” drift and speed onboarding. Adopt a trunk‑based flow with short‑lived branches, required PR checks, and automerge for low‑risk changes. Offer a GitHub CLI cheatsheet and hooks that lint commit messages and validate PR templates. Small friction reductions at the platform level multiply across teams.

Cost and ROI

Track direct costs (runner minutes, storage, licenses) and indirect savings (retired GitLab infrastructure, reduced CI toil). Optimize runner usage with ephemeral pools, spot instances, and caching. Measure cycle‑time improvements and outage reductions attributable to standardized pipelines and security automation. Translate technical benefits into business language for leadership updates.

Roadmap After Migration

Treat cutover as day one of a longer modernization arc. Over the next two quarters, target Codespaces adoption for key repos to reduce onboarding time and flaky local toolchains. Expand OIDC to all cloud deploys and remove the last static keys. Introduce policy‑as‑code for branch protections and environment rules so governance scales with teams. Create a platform customer advisory board—representatives from product, data, and mobile—that meets monthly to prioritize improvements to templates, runners, and documentation based on developer feedback. Investing in platform experience after migration compounds efficiency gains.

License and Marketplace Governance

Centralize governance of marketplace purchases and private actions. Vet third‑party actions for security posture, pin versions, and mirror where possible. Track usage and costs of hosted runners and Codespaces; set budgets and alerts. Assign an owner for license renewals and true‑ups and automate deprovisioning for departed users via SCIM. Clear governance prevents drift and surprise bills.

Governance: Repo Lifecycle and Ownership

Define the lifecycle: creation (via templates and approvals), maturity (production readiness checklist), archiving (inactivity thresholds), and deletion (after retention). Require every repo to have an owning team, CODEOWNERS, and a “run book” pointing to deploy and on‑call docs. Run quarterly reviews to prune stale repos and validate ownership. Good governance prevents sprawl and confusion.

Validation and Sign‑Off Checklists

Make sign‑off explicit for each wave. For repositories: confirm full history, tags, and LFS objects; branch protections and CODEOWNERS in place; PR templates present; CI workflows green on main; secrets populated; environments and approvals configured; deployment succeeded to non‑prod and prod. For issues and boards: labels and milestones migrated; Projects views reproduce current planning workflows; PMs confirm visibility and filters. For registries: images pushed to GHCR; consumers updated; vulnerability scanning enabled. Capture sign‑off in a shared tracker and require both platform and team leads to approve before declaring the wave complete.

Observability and SLOs

Define SLOs that matter: p95 CI time for common workflows, queue wait times on runners, success rate of deploy jobs, and mean time to restore after pipeline failures. Pump metrics to a central system (Datadog, Prometheus/Grafana) and set alerts that page the platform team when SLOs are violated. Publish weekly dashboards and include trends in platform reviews. Observability keeps tradeoffs honest and allows proactive capacity planning.

Common Pitfalls and How to Avoid Them

Three patterns derail migrations: (1) underestimating pipeline parity work—teams discover missing environment variables or conditional paths in YAML during cutover; fix with thorough dry runs and golden repos. (2) Secrets sprawl—teams copy long‑lived keys; fix by providing OIDC templates and secure secret scopes. (3) Access confusion—external collaborators lose access; fix by migrating access through teams and using SCIM and SSO, not direct invites. Document these pitfalls and include them in training. During waves, schedule 30‑minute “health checks” with each team to catch issues early.

Appendix: YAML Translation Patterns (Narrative)

While every pipeline differs, a stable pattern emerges. Triggers map to on: blocks with branches and paths filters. Stages become jobs, and shared scripts turn into composite actions or reusable workflows. Caches map to actions/cache with deterministic keys that include lockfiles and OS. Artifacts become either short‑lived Actions artifacts or uploads to durable stores. Deployments leverage environments with protection rules and secrets, and status is reported through job summaries and PR checks. Maintain a library of examples in a central repo with explanations rather than only code; developers learn faster from commentary that explains tradeoffs and conventions.

FAQ

Can we migrate merge request discussions and approvals exactly?

Not perfectly. You can bring PRs with history via scripts, but MR discussions map inconsistently to PR comments. Preserve essential context by linking to snapshots or summarizing key threads in PR descriptions where necessary.

How do we translate complex GitLab CI templates?

Start by enumerating shared templates and macros; rewrite them as composite actions or reusable workflows. Keep logic minimal in YAML and push complex steps into scripts that can be reused. Validate parity with golden repos before scaling.

What is the recommended approach for runners?

Prefer GitHub‑hosted runners for commodity workloads and ephemeral self‑hosted runners for workloads requiring custom tools, large caches, or special networks. Ensure ephemeral teardown per job to avoid cross‑contamination and secrets leakage.

How do we enforce compliance on GitHub?

Use org policies and repository rulesets for branch protection; mandate reviews and status checks. Enable secret scanning and CodeQL. Stream audit logs to your SIEM and review access through SCIM‑managed teams. For deploys, require approvals on protected environments.

Do we need to migrate all issues and milestones?

Only what teams actively use. Let some backlogs sunset; migrate active issues and epics. Provide a read‑only archive of GitLab issues if needed for audit; otherwise, start fresh with templates on GitHub.

How do we handle monorepos?

Keep them if they deliver velocity and consistency. Invest in partial builds, test selection, and remote caches. If pain outweighs benefit, evaluate carving out subsystems—not during migration week, but as a strategic project with clear ROI.

What metrics prove migration success?

Time‑to‑merge, build minutes per change, rate of successful deployments, percentage of repos using standardized workflows, and reduction in incidents related to CI infrastructure. Qualitative feedback—developer satisfaction and reduced waiting—is equally important.