GitLab Production Architecture

Gitaly

Git storage RPC service — the I/O backbone of every GitLab instance

What is Gitaly?

Gitaly is a gRPC-based service that provides a high-level interface to Git repository storage. Every Git operation in GitLab — clones, pushes, merges, diffs, blame, file browsing — is dispatched as a gRPC call to Gitaly. No GitLab component touches the filesystem directly anymore; Gitaly is the sole gateway to on-disk Git data.

Gitaly was introduced to replace direct NFS access to Git repositories. The old model (multiple Rails/Sidekiq nodes mounting the same NFS share) suffered from locking issues, cache coherency problems, and terrible performance at scale. Gitaly moves all filesystem access to a dedicated service with proper concurrency control.

Architecture

In a simple deployment, Gitaly runs on the same node as the rest of GitLab (Omnibus bundles it). In production, Gitaly typically runs on dedicated nodes with fast local SSDs:

• Puma / Workhorse / Sidekiq → gRPC calls → Gitaly → local disk Git repositories
• Communication is over gRPC with token-based authentication (gitaly['auth_token'] in gitlab.rb)
• Each Gitaly node can host multiple storage paths (virtual storages), allowing you to spread repositories across disks

Gitaly Cluster (Praefect)

For high availability of Git repository data, GitLab provides Gitaly Cluster, which uses Praefect as a transparent proxy/router in front of multiple Gitaly nodes:

• Praefect is a gRPC proxy that sits between GitLab application nodes and Gitaly nodes. It routes reads and writes, tracks replication state, and coordinates failover.
• Replication model: Writes go to the primary Gitaly node first, then Praefect replicates to secondaries. You can configure strong consistency (synchronous — write acknowledged only after N replicas confirm) or eventual consistency (async replication).
• Praefect PostgreSQL: Praefect maintains its own PostgreSQL database to track which repositories live on which nodes and their replication state. This is separate from GitLab's main PostgreSQL.
• Minimum topology: 3 Praefect nodes (for Praefect HA) + 3 Gitaly nodes + 1 Praefect PostgreSQL (can be HA with Patroni).

GitLab App Nodes
      |
      v  (gRPC)
+------------------+
|    Praefect (3)   |  ← routes reads/writes, tracks replication
+--+------+------+--+
   |      |      |
   v      v      v   (gRPC)
Gitaly1  Gitaly2  Gitaly3   ← each stores full repo copies
  |        |        |
 SSD      SSD      SSD

Why Gitaly is usually the bottleneck

• Disk I/O intensive: Git operations (pack-objects, diff, blame on large files) are fundamentally I/O-bound. Gitaly performance is directly tied to disk latency and throughput.
• Large repositories: Monorepos or repos with extensive history generate massive pack operations. A single git clone of a 10GB repo can saturate disk I/O for minutes.
• CPU for pack operations: git pack-objects (used during clone/fetch) is CPU-intensive. Multiple concurrent clones can overwhelm a Gitaly node.
• Memory for pack windows: Git uses memory-mapped windows to compute deltas during packing. Large repos with many objects require significant RAM.

Sizing guidelines

• SSDs are non-negotiable. NFS was deprecated in GitLab 14.0 and removed in 15.0. Use NVMe SSDs where possible.
• Disk space: Plan for 2–4x the raw repository size (pack files, temporary objects, housekeeping)
• CPU: 4–8 vCPUs per Gitaly node for up to 5,000 users; 16+ for larger deployments
• RAM: 16–32 GB minimum. Git pack operations are memory-hungry.
• Network: Gitaly should be on a low-latency link to app nodes. 1 Gbps minimum, 10 Gbps for large instances.

Common issues

• High disk latency: The #1 cause of slow Git operations. Monitor gitaly_disk_* Prometheus metrics. Anything above 10ms average latency will degrade user experience.
• Large push operations: Pushes with many refs or large packfiles can time out. Tune gitaly['configuration']['git']['config'] for pack.threads and transfer limits.
• Repository housekeeping: GitLab runs periodic git gc and git repack via Sidekiq. These are I/O-heavy and can impact foreground operations. Schedule during off-peak hours.
• Praefect replication lag: In eventual consistency mode, check praefect dataloss command to identify repositories that are under-replicated.

# Check Gitaly health
sudo gitlab-rake gitlab:gitaly:check

# Check Praefect replication status
sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dataloss

# Monitor Gitaly disk performance (Prometheus query)
# gitaly_disk_read_bytes_total, gitaly_disk_write_bytes_total
# histogram_quantile(0.95, rate(gitaly_grpc_server_handling_seconds_bucket[5m]))

Sidekiq

Ruby background job processor — GitLab's asynchronous workhorse

What is Sidekiq?

Sidekiq is a Ruby background job processing framework that uses Redis as its job queue. In GitLab, it handles everything that shouldn't block a web request — which turns out to be a substantial portion of GitLab's functionality. If Puma is the front door, Sidekiq is the entire back office.

What Sidekiq does in GitLab

Nearly every asynchronous operation in GitLab flows through Sidekiq:

• CI/CD pipeline processing: Creating pipelines, scheduling jobs, processing pipeline status updates, sending notifications
• Email delivery: Notification emails, approval requests, pipeline results
• Repository maintenance: git gc, git repack, housekeeping tasks, repository size calculations
• Webhooks: Delivering webhook payloads to external services on push, merge, pipeline events
• Import/Export: Project imports (GitHub, Bitbucket), project exports, group migrations
• Cache invalidation: Clearing stale caches when projects, users, or configurations change
• Merge request processing: Diff generation, merge checks, approval rule evaluation
• Security scanning: Processing SAST/DAST/dependency scan results and creating vulnerabilities

Queue routing & urgency

GitLab categorizes Sidekiq jobs by urgency, which determines queue routing and latency expectations:

• High urgency: Must start within 10 seconds. Examples: pipeline creation, merge status updates. These affect user-perceived responsiveness.
• Low urgency: Can tolerate minutes of queue time. Examples: email delivery, repository cleanup, export jobs.
• Throttled: Rate-limited to prevent overload. Examples: bulk imports, large project exports.

In production HA deployments, you can run dedicated Sidekiq processes for specific queue groups:

# In gitlab.rb — dedicated Sidekiq workers by queue
sidekiq['queue_groups'] = [
  # Worker 1: high-urgency queues only
  'pipeline_processing,pipeline_creation,pipeline_default',
  # Worker 2: everything else
  '*'
]

# Or run separate Sidekiq nodes entirely:
# Node A (pipeline-focused):
sidekiq['queue_groups'] = ['pipeline_processing,pipeline_creation']
# Node B (general):
sidekiq['queue_groups'] = ['*']

Scaling Sidekiq

• Vertical: Increase sidekiq['max_concurrency'] (default 20). Each concurrent thread holds a database connection, so this is bounded by PostgreSQL connection limits and PgBouncer pool size.
• Horizontal: Add more Sidekiq processes on the same node (sidekiq['queue_groups'] with multiple entries) or add entirely separate Sidekiq nodes.
• On Kubernetes: Scale the Sidekiq Deployment replicas independently from webservice pods. Use HPA based on queue depth metrics.
• Monitor queue depth: The key metric is sidekiq_queue_size per queue. If high-urgency queues back up, users see delayed pipeline starts and slow MR updates.

Common issues

• Queue backlogs: Usually caused by insufficient Sidekiq workers or a slow dependency (PostgreSQL, Gitaly, external webhooks). Check which queues are growing and what jobs are consuming time.
• Memory bloat (Ruby GC): Ruby's garbage collector can cause Sidekiq processes to grow to several GB over time. Configure sidekiq['max_concurrency'] and use MALLOC_ARENA_MAX=2 to reduce memory fragmentation. GitLab also supports SIDEKIQ_MEMORY_KILLER_MAX_RSS to restart workers that exceed a memory threshold.
• Stuck jobs: Jobs that hang (waiting on external services, deadlocked database queries) block their thread. Monitor sidekiq_running_jobs and set up alerts for jobs running longer than expected.
• Redis memory pressure: All Sidekiq job data lives in Redis. A massive queue backlog can exhaust Redis memory. Monitor redis_used_memory_bytes and set Redis maxmemory with an appropriate eviction policy (though eviction will lose jobs).

Key metrics

• sidekiq_queue_latency_seconds — time from enqueue to start of processing. High-urgency queues should be under 10s.
• sidekiq_jobs_completion_seconds — how long jobs take to execute. Look for p95/p99 outliers.
• sidekiq_jobs_failed_total — failed job rate. Transient failures retry automatically; persistent failures indicate bugs or infrastructure issues.
• sidekiq_queue_size — number of jobs waiting per queue. The primary capacity signal.

Patroni

PostgreSQL HA with automatic failover via distributed consensus

What is Patroni?

Patroni is an open-source PostgreSQL high-availability solution that uses a Distributed Configuration Store (DCS) — typically etcd, Consul, or ZooKeeper — for leader election and cluster state management. It automates the hardest parts of PostgreSQL HA: leader election, automatic failover, and managed streaming replication.

In GitLab's architecture, Patroni replaces manual PostgreSQL replication setups. GitLab's Omnibus package bundles Patroni and uses Consul as the DCS by default.

How it works

• Patroni agent runs on each PostgreSQL node as a sidecar/supervisor process. It manages the local PostgreSQL instance (start, stop, promote, configure replication).
• Leader lock: The DCS (Consul in GitLab's case) holds a leader key. The node that holds the lock is the primary. If the primary fails to renew the lock (health check failure, network partition), another node acquires it and promotes itself.
• Streaming replication: Replicas stream WAL (Write-Ahead Log) from the primary in real-time. Patroni configures and manages replication slots automatically.
• Cluster bootstrap: Patroni handles initial cluster setup, including pg_basebackup for new replicas joining the cluster.

Architecture in GitLab

                 +-------------------+
                 |   Consul Cluster   |
                 |  (3 nodes, DCS)    |
                 +--------+----------+
                          |
            +-------------+-------------+
            |             |             |
    +-------v---+  +------v----+  +----v-------+
    |  Patroni   |  |  Patroni   |  |  Patroni   |
    | PostgreSQL |  | PostgreSQL |  | PostgreSQL |
    |  (Leader)  |  | (Replica)  |  | (Replica)  |
    +------+-----+  +-----------+  +-----------+
           |
    +------v------+
    |  PgBouncer   |  ← routes connections to current leader
    +--------------+

• Consul cluster (3 nodes): Provides the distributed consensus layer. Patroni uses Consul's key/value store for the leader lock and cluster metadata.
• Patroni nodes (3 minimum): One leader + two replicas. Each runs PostgreSQL with Patroni managing the lifecycle.
• PgBouncer: Connection pooler that routes application connections to the current leader. Consul DNS or service discovery directs PgBouncer to the active primary.

Switchover vs. failover

• Switchover (planned): Graceful leadership transfer for maintenance. Patroni ensures the best replica is caught up, then promotes it. Zero or near-zero downtime. Triggered via patronictl switchover.
• Failover (unplanned): Primary dies or becomes unreachable. Patroni detects the failure (missed DCS heartbeat), selects the most up-to-date replica, and promotes it. Typical detection + promotion time: 10–30 seconds.

# GitLab Omnibus Patroni commands
sudo gitlab-ctl patroni members          # Show cluster members and roles
sudo gitlab-ctl patroni switchover       # Initiate planned switchover
sudo gitlab-ctl patroni failover         # Force failover (use with caution)
sudo gitlab-ctl patroni reinitialize     # Re-bootstrap a failed replica
sudo gitlab-ctl patroni check-leader     # Verify current leader health

Split-brain prevention

Split-brain (two nodes believing they are the primary) is the worst failure mode in any database HA system. Patroni prevents it through the DCS:

• The leader must continuously renew its lock in the DCS (default TTL: 30 seconds). If it can't reach the DCS, it voluntarily demotes itself to read-only.
• A new leader can only be elected if the DCS confirms the old leader's lock has expired.
• watchdog (optional, Linux kernel feature): Patroni can use the kernel watchdog to forcibly reboot a node that loses DCS connectivity, preventing a zombie primary from accepting writes.

GitLab-specific configuration

# In gitlab.rb on each PostgreSQL/Patroni node
patroni['enable'] = true
patroni['scope'] = 'gitlab-pg-cluster'
postgresql['listen_address'] = '0.0.0.0'
patroni['consul']['url'] = 'http://consul.service.consul:8500'
patroni['postgresql']['max_connections'] = 300
patroni['postgresql']['wal_level'] = 'replica'
patroni['replication']['password'] = 'repl_password_here'

PgBouncer

Lightweight PostgreSQL connection pooler for high-concurrency environments

What is PgBouncer?

PgBouncer is a lightweight connection pooler for PostgreSQL. It sits between application clients (Rails/Puma, Sidekiq) and PostgreSQL, multiplexing many client connections over a smaller number of actual database connections. This is critical because PostgreSQL creates a new OS process for every connection, which becomes expensive at scale — hundreds or thousands of connections consume significant memory and CPU just for connection management.

Why GitLab needs it

In a GitLab HA deployment, multiple Puma and Sidekiq processes across multiple nodes all need database connections. Without PgBouncer:

• 3 Puma nodes × 60 workers × 4 threads = 720 potential connections
• 3 Sidekiq nodes × 20 concurrency = 60 more connections
• Plus Praefect, Geo, monitoring queries…
• Total: easily 800+ connections, each consuming ~5–10 MB of PostgreSQL backend memory

PgBouncer reduces this to a manageable pool (e.g., 100–200 actual database connections) while accepting many more client connections.

Pooling modes

• Session pooling: A server connection is assigned to a client for the entire session (connect to disconnect). Safest mode — all PostgreSQL features work. But it doesn't save many connections since each active session ties up a backend.
• Transaction pooling (recommended for GitLab): A server connection is assigned only for the duration of a transaction. Between transactions, the connection returns to the pool. This is the most effective mode for connection reduction. GitLab officially recommends transaction pooling.
• Statement pooling: Connection returned after every statement. Very aggressive pooling but breaks multi-statement transactions. Not compatible with GitLab.

GitLab-specific setup

GitLab Omnibus bundles PgBouncer. In an HA setup, PgBouncer runs on dedicated nodes (or co-located with application nodes) and uses Consul to discover the current Patroni leader:

# In gitlab.rb on PgBouncer node(s)
pgbouncer['enable'] = true
pgbouncer['listen_address'] = '0.0.0.0'
pgbouncer['listen_port'] = 6432

# Pool sizing
pgbouncer['default_pool_size'] = 60
pgbouncer['min_pool_size'] = 10
pgbouncer['reserve_pool_size'] = 5
pgbouncer['max_client_conn'] = 2048

# Transaction pooling (recommended)
pgbouncer['pool_mode'] = 'transaction'

# Consul-based discovery of Patroni leader
pgbouncer['databases'] = {
  gitlabhq_production: {
    host: "master.patroni.service.consul",
    port: 5432,
    pool_size: 100
  }
}

Sizing: key parameters

• max_client_conn: Maximum number of client connections PgBouncer will accept. Set this high enough for all Puma threads + Sidekiq workers + headroom. Default 2048 is usually sufficient.
• default_pool_size: Number of server connections per user/database pair. This is how many actual PostgreSQL connections PgBouncer maintains. Start with 60–100 and tune based on monitoring.
• reserve_pool_size: Extra connections allowed when the pool is exhausted. Acts as a burst buffer.
• pool_mode: transaction for GitLab. Session mode negates most of the pooling benefit.
• Rule of thumb: default_pool_size × number of databases should not exceed PostgreSQL's max_connections.

Common issues

• Prepared statements in transaction mode: PostgreSQL prepared statements are session-level objects. In transaction pooling mode, a client might prepare a statement on connection A, but the next transaction runs on connection B where the statement doesn't exist. GitLab handles this by using prepared_statements: false in its database configuration. If you see prepared statement "a1" does not exist errors, this setting is wrong.
• Long transactions blocking the pool: A single long-running query or transaction holds a server connection for its duration, reducing the effective pool size. Monitor pgbouncer_pools_server_active and pgbouncer_pools_server_used. Look for long-running transactions in pg_stat_activity.
• SET statements leak: In transaction mode, SET commands affect the server connection but persist after the transaction. The next client using that connection inherits the modified settings. GitLab avoids this by not using session-level SET, but custom queries (from Grafana, ad-hoc scripts) can trigger this.
• Connection storm after failover: When Patroni fails over, all PgBouncer connections to the old primary break. PgBouncer reconnects to the new primary, but the burst of new connections can overwhelm PostgreSQL. Tune server_login_retry and server_connect_timeout.

Monitoring PgBouncer

-- Connect to PgBouncer admin console
psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer

-- Key commands
SHOW POOLS;         -- active/waiting connections per pool
SHOW STATS;         -- request rate, query duration, bytes
SHOW DATABASES;     -- configured databases and pool sizes
SHOW CLIENTS;       -- connected clients and their state
SHOW SERVERS;       -- backend PostgreSQL connections

SAST — Static Application Security Testing

Find vulnerabilities in source code before the application runs — shift security left into the development workflow

What is SAST?

Static Application Security Testing analyzes source code, bytecode, or binaries for security vulnerabilities without executing the application. It works by parsing the code into an abstract syntax tree (AST) and applying pattern-matching rules, data flow analysis, and taint tracking to find issues like SQL injection, XSS, insecure deserialization, hardcoded credentials, and buffer overflows.

SAST is "white-box" testing — it sees the source code. This means it can find vulnerabilities deep in code paths that might not be reachable via external testing, but it can also produce false positives because it doesn't know runtime context.

How GitLab SAST works

• GitLab auto-detects the project language and selects the appropriate analyzer (container image)
• The primary analyzer is Semgrep (multi-language, with GitLab-managed rules). Legacy standalone analyzers like Bandit, ESLint, and Gosec have been consolidated into Semgrep. SpotBugs (Java/Scala/Groovy/Kotlin) remains as a separate analyzer. Advanced SAST (Ultimate) adds cross-function and cross-file taint analysis for deeper detection.
• The analyzer runs in a CI job, scans the source code, and outputs a standardized JSON report
• GitLab parses the report and surfaces findings in the merge request widget and vulnerability dashboard

Supported languages

C/C++, C#, Go, Java, JavaScript/TypeScript, Kotlin, Python, Ruby, Scala, Swift, PHP, and more. Semgrep covers most languages with community and GitLab-maintained rule packs.

Configuration

# Basic — just include the template
include:
  - template: Security/SAST.gitlab-ci.yml

# Customize — override variables
variables:
  SAST_EXCLUDED_PATHS: "spec,test,tests,vendor"
  SAST_EXCLUDED_ANALYZERS: "spotbugs"  # skip Java analyzer
  SEARCH_MAX_DEPTH: 10                  # scan depth for monorepos

# Custom rules — add your own Semgrep rules
  SAST_RULESET_GIT_REFERENCE: "main"
  # Point to a repo with custom .semgrep.yml rules

Strengths and limitations

• Strength: Catches issues early in development — before code is merged or deployed
• Strength: No running application needed — works on every commit
• Strength: Can find issues in code paths that are rarely exercised at runtime
• Limitation: False positives — flags code patterns that look dangerous but aren't exploitable in context
• Limitation: Can't find runtime issues (misconfigurations, auth bypass via deployment, SSRF to internal services)
• Limitation: Struggles with dynamically generated code, heavy metaprogramming, or complex frameworks

DAST — Dynamic Application Security Testing

Black-box security testing against a running application — find vulnerabilities that only appear at runtime

What is DAST?

Dynamic Application Security Testing tests a running application by sending crafted HTTP requests and analyzing responses for security vulnerabilities. It's "black-box" testing — the scanner doesn't see source code. It interacts with the application the same way an attacker would: through the web interface and API endpoints.

DAST finds issues that SAST cannot: server misconfigurations, authentication flaws, session management problems, CORS issues, and vulnerabilities that only manifest when multiple components interact at runtime.

How GitLab DAST works

• GitLab DAST uses a browser-based crawler (based on Chromium) that navigates the application like a real user. The legacy proxy-based DAST analyzer was removed in GitLab 17.0.
• It discovers pages, forms, API endpoints, and JavaScript-rendered content
• The scanner then fuzzes inputs — injecting payloads for XSS, SQL injection, CSRF, command injection, path traversal, etc.
• Results are correlated and deduplicated, then surfaced in the merge request and vulnerability dashboard

DAST modes

• Passive scan — crawls the application and analyzes responses without sending attack payloads. Fast, safe, low noise. Good for CI pipelines.
• Active scan (full) — sends attack payloads to discover exploitable vulnerabilities. Slower, may modify data, should target a dedicated test environment.
• API scan — tests API endpoints directly using an OpenAPI/Swagger spec, HAR file, or Postman collection. No crawling needed.

Note: The legacy proxy-based DAST analyzer was removed in GitLab 17.0. All DAST scanning now uses the browser-based engine (DAST version 5+), which provides better crawl coverage but may require more resources.

Configuration

include:
  - template: Security/DAST.gitlab-ci.yml

variables:
  DAST_WEBSITE: "https://staging.example.com"  # target URL

  # Authenticated scanning (critical for real coverage)
  DAST_AUTH_URL: "https://staging.example.com/login"
  DAST_USERNAME: "dast-scanner@example.com"
  DAST_PASSWORD_VARIABLE: "DAST_PASSWORD"  # CI variable
  DAST_USERNAME_FIELD: "css:#username"
  DAST_PASSWORD_FIELD: "css:#password"
  DAST_SUBMIT_FIELD: "css:button[type='submit']"

  # API scanning
  DAST_API_OPENAPI: "https://staging.example.com/api/v1/openapi.json"

dast:
  stage: dast
  # Run only on staging deploys, not every commit
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Practical considerations

• Environment: DAST needs a running target — typically a review environment or staging. Never point it at production.
• Authentication: Unauthenticated DAST only sees the login page. Configure authenticated scanning to test the actual application.
• Speed: Full active scans can take 30-90 minutes. Run passive scans in MR pipelines and full scans nightly or on main branch only.
• Data pollution: Active scans create records, submit forms, and may trigger emails. Use a disposable test environment with seed data.

Dependency Scanning

Detect known vulnerabilities in third-party libraries before they reach production

What is Dependency Scanning?

Dependency Scanning (also called Software Composition Analysis / SCA) analyzes your project's dependencies — the third-party libraries and packages declared in lock files — against databases of known vulnerabilities (CVEs). Most modern applications are 80-90% third-party code, making this one of the highest-value scanners.

How it works in GitLab

• The scanner parses lock files and manifests: package-lock.json, yarn.lock, Gemfile.lock, go.sum, pom.xml, requirements.txt, Pipfile.lock, Cargo.lock, etc.
• Each dependency (including transitive dependencies) is checked against the GitLab Advisory Database (aggregating NVD, GitHub Advisories, and other sources)
• Findings include CVE ID, severity (CVSS score), affected versions, and the fixed version if available
• Results appear in the MR widget with a clear "upgrade to version X.Y.Z to fix" recommendation

Configuration

include:
  - template: Security/Dependency-Scanning.gitlab-ci.yml

# Typically no configuration needed — it auto-detects
# the package manager from lock files

# Optional customization:
variables:
  DS_EXCLUDED_PATHS: "vendor,node_modules"
  DS_MAX_DEPTH: 2  # limit transitive dependency depth

Vulnerability lifecycle

1. Detected — scanner finds a CVE in a dependency
2. Confirmed — team verifies the vulnerability is relevant (not all CVEs are exploitable in your context)
3. Resolved — dependency is upgraded to a fixed version
4. Dismissed — false positive or accepted risk (document the reason)

Key practices

• Keep lock files committed — scanners need deterministic dependency trees. Without lock files, scans are unreliable.
• Automate updates — use Dependabot, Renovate Bot, or GitLab's own dependency update MRs to stay current
• Transitive dependencies matter — your app may not directly use a vulnerable library, but a dependency of a dependency might. The scanner catches these.
• Don't ignore severity — a Critical CVE in a library that handles user input (e.g., a JSON parser, XML library, or image processor) is a real risk

Container Scanning

Find vulnerabilities in Docker images — OS packages, language libraries, and base image issues

What is Container Scanning?

Container Scanning analyzes Docker container images for known vulnerabilities in OS-level packages (apt, yum, apk) and language-specific packages. It's the container equivalent of dependency scanning — but for the entire runtime environment, not just your application's declared dependencies.

How it works in GitLab

• GitLab uses Trivy (by Aqua Security) as the default container scanner
• The scanner pulls the Docker image built in your CI pipeline and analyzes every layer
• It checks installed packages against vulnerability databases (NVD, Alpine SecDB, Debian Security Tracker, Red Hat CVE database, etc.)
• Results include CVE ID, severity, affected package, installed version, and fixed version

Configuration

include:
  - template: Security/Container-Scanning.gitlab-ci.yml

variables:
  CS_IMAGE: "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"  # image to scan
  CS_SEVERITY_THRESHOLD: "HIGH"  # only report HIGH and CRITICAL

# The scanner runs after the build stage
# (it needs the image to exist in a registry)

Common findings and remediation

• Outdated base image — FROM ubuntu:20.04 with unpatched OpenSSL. Fix: update the base image tag or use :latest with pinned digests and regular rebuilds.
• Unnecessary packages — base images often include tools not needed at runtime (curl, wget, gcc). Fix: use minimal base images (alpine, distroless, scratch) or multi-stage builds.
• Language packages in image — pip/npm/gem packages installed during build may have CVEs. Fix: keep dependency scanning and container scanning aligned.

Best practices

• Use minimal base images — fewer packages = fewer vulnerabilities. Alpine or distroless images have a dramatically smaller attack surface.
• Rebuild regularly — even if your code hasn't changed, base images get security patches. Schedule weekly rebuilds.
• Multi-stage builds — compile in one stage, copy only the binary to a minimal runtime image. Build tools and headers don't ship to production.
• Pin image digests — FROM node:20@sha256:abc... ensures reproducible builds. Combine with automated digest updates.

Secret Detection

Catch accidentally committed credentials before they become a breach — API keys, passwords, tokens, and private keys

What is Secret Detection?

Secret Detection scans git commits for patterns that match known secret formats — AWS access keys, private RSA/ECDSA keys, database connection strings, API tokens, passwords in config files, and more. It uses a combination of regex pattern matching and entropy analysis (high-entropy strings that look like random tokens).

This is arguably the most immediately actionable scanner. A committed secret is a live vulnerability — it's in git history forever (even if deleted in a later commit) and can be exploited immediately.

Detection modes

• Pipeline (post-commit) — runs in CI after the commit is pushed. Scans the diff of each commit. JSON report artifacts available in all tiers; MR widget, vulnerability dashboard, and security policies require Ultimate.
• Pre-receive (push rules) — server-side hook that blocks the push before the secret enters the repository. This is the most effective mode — the secret never makes it into git history. Requires GitLab Ultimate.
• Client-side (pre-commit) — optional git hook that runs locally before the developer commits. Fastest feedback loop but requires developer setup.

What it detects

• AWS access key IDs and secret keys (AKIA...)
• GCP service account keys (JSON key files)
• Azure storage keys, connection strings
• GitHub, GitLab, Slack, Stripe, Twilio tokens
• Private keys (RSA, ECDSA, Ed25519, PGP)
• Database connection strings with embedded passwords
• Generic high-entropy strings (configurable sensitivity)
• Custom patterns via .gitlab/secret-detection-ruleset.toml

Configuration

include:
  - template: Security/Secret-Detection.gitlab-ci.yml

variables:
  SECRET_DETECTION_HISTORIC_SCAN: "true"  # scan full git history (first run)
  SECRET_DETECTION_EXCLUDED_PATHS: "test/"

# Custom rules — add organization-specific patterns
# .gitlab/secret-detection-ruleset.toml
# [[rules]]
#   id = "internal-api-key"
#   regex = '''MYCO-[A-Za-z0-9]{32}'''
#   description = "Internal API key"

Incident response for committed secrets

1. Rotate immediately — the secret is compromised the moment it's pushed, even to a private repo. Assume it's been read.
2. Revoke the old credential — disable the API key, rotate the password, regenerate the token
3. Don't just delete the file — the secret is in git history. Deleting it in a new commit doesn't remove it. Use git filter-repo to rewrite history if needed, but rotation is the priority.
4. Audit access logs — check if the secret was used by an unauthorized party during the exposure window

SBOM — Software Bill of Materials

A machine-readable inventory of every component in your software — increasingly required for compliance and supply chain security

What is an SBOM?

A Software Bill of Materials is a structured, machine-readable list of all components, libraries, and dependencies that make up a piece of software. Think of it as a nutritional label for software — it tells you exactly what's inside. SBOMs have become a critical compliance requirement following high-profile supply chain attacks (SolarWinds, Log4Shell) and government mandates (US Executive Order 14028, EU Cyber Resilience Act).

SBOM formats

• CycloneDX — OWASP standard. JSON or XML format. GitLab generates CycloneDX by default. Designed for security use cases: vulnerability tracking, license compliance, and component lifecycle.
• SPDX (Software Package Data Exchange) — Linux Foundation standard. ISO/IEC 5962:2021. Stronger focus on license compliance. Widely used in open-source projects and government procurement.

How GitLab generates SBOMs

• GitLab's Dependency Scanning and Container Scanning automatically generate CycloneDX SBOM reports as part of their scan output
• The SBOM is stored as a CI artifact and linked to the pipeline
• The Dependency List page (project-level) shows a browsable view of all components with versions, licenses, and known vulnerabilities
• SBOMs can be exported for sharing with customers, auditors, or regulatory bodies

What's in an SBOM

• Component name and version — e.g., lodash@4.17.21, openssl 3.0.8-1ubuntu1
• Package URL (purl) — standardized identifier: pkg:npm/lodash@4.17.21
• License — MIT, Apache-2.0, GPL-3.0, etc.
• Supplier — who produced the component
• Dependency relationship — direct vs. transitive
• Hashes — SHA-256 of the component for integrity verification

Why SBOMs matter

• Vulnerability response: When the next Log4Shell drops, an SBOM tells you in seconds whether you're affected — across all projects, all environments.
• License compliance: Automatically flag GPL dependencies in proprietary software, or track license obligations for open-source usage.
• Regulatory compliance: US federal agencies require SBOMs from software vendors. The EU Cyber Resilience Act mandates them for products sold in the EU.
• Customer trust: Enterprise customers increasingly request SBOMs as part of procurement due diligence.

SAML 2.0

Security Assertion Markup Language — the XML-based SSO standard that dominates enterprise identity federation

What is SAML?

SAML 2.0 (Security Assertion Markup Language) is an XML-based open standard for exchanging authentication and authorization data between an Identity Provider (IdP) and a Service Provider (SP). Published in 2005 by OASIS, it remains the dominant SSO protocol in enterprise environments.

In a GitLab context, GitLab acts as the SAML SP. An external IdP (Keycloak, ADFS, Okta, Microsoft Entra ID) authenticates users and sends SAML assertions to GitLab. GitLab trusts the assertion and creates/maps the user session.

How the SAML flow works with GitLab

1. User clicks "Sign in with SSO" on GitLab
2. GitLab generates an AuthnRequest and redirects the user to the IdP
3. IdP authenticates the user (login form, Kerberos, MFA)
4. IdP generates a signed SAML Response containing an Assertion with user identity and attributes
5. IdP POSTs the response to GitLab's ACS URL (/users/auth/saml/callback)
6. GitLab validates the signature, maps attributes (email, name, groups), and creates the session

GitLab SAML configuration

# /etc/gitlab/gitlab.rb
gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "Company SSO",
    args: {
      assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
      idp_cert_fingerprint: "XX:XX:XX:...",
      idp_sso_target_url: "https://idp.example.com/sso/saml",
      issuer: "https://gitlab.example.com",
      name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress",
      attribute_statements: {
        email: ["email"],
        first_name: ["firstName"],
        last_name: ["lastName"]
      }
    }
  }
]

Key concepts

• Assertion — signed XML payload containing who the user is and their attributes
• Entity ID — unique identifier for each party. Must match exactly between IdP and SP configurations
• ACS URL — the GitLab endpoint that receives the SAML response
• Name ID — the user identifier in the assertion (typically email)
• Metadata — XML document describing endpoints and certificates. Exchange between IdP and SP to automate setup
• Group sync — map SAML group attributes to GitLab groups (requires Premium+)

OAuth 2.0

The authorization framework that underpins modern API security and delegated access

What is OAuth 2.0?

OAuth 2.0 is an authorization framework (RFC 6749) that enables applications to obtain limited access to user resources without exposing credentials. A critical distinction: OAuth 2.0 is about authorization (what can you access?), not authentication (who are you?). OIDC was built on top of OAuth 2.0 to add authentication.

OAuth 2.0 in GitLab

GitLab uses OAuth 2.0 in two ways:

• As an OAuth provider — GitLab can act as an OAuth 2.0 authorization server. Third-party applications can request access to GitLab APIs on behalf of a user. This is how integrations like IDE plugins, CLI tools, and custom dashboards authenticate.
• As an OAuth consumer — GitLab can authenticate users via external OAuth/OIDC providers (Keycloak, Google, GitHub, Microsoft Entra ID) through OmniAuth.

Core roles

• Resource Owner — the GitLab user who owns repositories, issues, pipelines
• Client — the application requesting access (registered as an OAuth Application in GitLab)
• Authorization Server — GitLab itself (issues access tokens after user consent)
• Resource Server — GitLab's API (validates access tokens on each request)

Creating an OAuth application in GitLab

# Admin Area > Applications > New Application
Name:          My Integration
Redirect URI:  https://myapp.example.com/callback
Scopes:        api, read_user, read_repository
Confidential:  Yes (server-side apps) / No (SPAs, mobile)

# Result:
Application ID:  abc123...  (client_id)
Secret:          xyz789...  (client_secret)

Grant types supported by GitLab

• Authorization Code — standard flow for web apps. User is redirected to GitLab, approves access, GitLab returns a code, app exchanges it for tokens.
• Authorization Code + PKCE — for public clients (SPAs, CLIs). Adds a code verifier/challenge to prevent interception.
• Resource Owner Password Credentials — direct username/password exchange. Deprecated in OAuth 2.1, but GitLab still supports it for legacy integrations.

GitLab API scopes

• api — full read/write access to the API
• read_user — read the authenticated user's profile
• read_api — read-only API access
• read_repository — read repository contents (clone/fetch)
• write_repository — write to repositories (push)
• read_registry — read container registry images
• openid — OIDC authentication (ID token)

JSON Web Token (JWT)

The compact, self-contained token format that carries identity and authorization claims

What is a JWT?

A JSON Web Token (RFC 7519) is a compact, URL-safe way to represent claims between two parties. It consists of three Base64URL-encoded parts separated by dots: header.payload.signature. JWTs are used throughout GitLab — as OAuth access tokens, CI/CD job tokens, and OIDC ID tokens.

JWT structure

# Header
{ "alg": "RS256", "typ": "JWT", "kid": "key-id" }

# Payload (claims)
{
  "iss": "https://gitlab.example.com",
  "sub": "12345",
  "aud": "my-app",
  "exp": 1711234567,
  "iat": 1711230967,
  "namespace_id": "42",
  "namespace_path": "my-group",
  "project_id": "99",
  "project_path": "my-group/my-project",
  "user_login": "jsmith",
  "user_email": "jsmith@example.com",
  "ref": "main",
  "pipeline_id": "7890"
}

# Signature
RSASHA256(base64url(header) + "." + base64url(payload), privateKey)

JWTs in GitLab CI/CD

GitLab CI/CD can generate JWTs for pipelines, enabling keyless authentication to external services:

# .gitlab-ci.yml — OIDC authentication to cloud providers
deploy:
  id_tokens:
    VAULT_TOKEN:
      aud: https://vault.example.com
    AWS_TOKEN:
      aud: sts.amazonaws.com
  script:
    # Use the JWT to authenticate to Vault (no static secrets!)
    - export VAULT_TOKEN=$(vault write -field=token
        auth/jwt/login role=gitlab-deploy jwt=$VAULT_TOKEN)
    # Use the JWT to assume an AWS IAM role via OIDC federation
    - aws sts assume-role-with-web-identity
        --role-arn arn:aws:iam::123456:role/deploy
        --web-identity-token $AWS_TOKEN

Key claims in GitLab JWTs

• iss — the GitLab instance URL
• sub — project_path:ref_type:ref (e.g., my-group/my-project:ref_type:branch:ref:main)
• namespace_path / project_path — allows external services to authorize based on which project/group triggered the pipeline
• ref — the branch or tag that triggered the pipeline
• pipeline_id / pipeline_source — audit trail for which pipeline generated the token

Token validation

1. Fetch JWKS — GitLab publishes public keys at https://gitlab.example.com/-/jwks
2. Verify signature — match the kid header to a JWKS key, verify with the public key
3. Check expiration — reject if exp is past
4. Check issuer — iss must match your GitLab instance
5. Check audience — aud must match what the external service expects
6. Check claims — verify project_path, ref, etc. match your authorization policy

1K Reference Architecture

Single-node all-in-one — up to 1,000 users, 20 RPS

Overview

The simplest GitLab deployment: everything on one server. Puma, Sidekiq, Gitaly, PostgreSQL, Redis, Prometheus — all bundled via Omnibus on a single VM.

Node specifications

Total: 1 node

Supported modifications

• External PostgreSQL (Cloud SQL, RDS)
• External object storage (S3)
• Elasticsearch for Advanced Search (Premium/Ultimate)

Unsupported modifications

• HA configurations — not possible at this tier
• Cloud Native Hybrid — requires minimum 2K

2K Reference Architecture

Separated services, no HA — up to 2,000 users, 40 RPS

Overview

Services are split across dedicated nodes but without redundancy. A single failure takes down the affected component.

Node specifications

Total: 8 nodes

Supported modifications

• External PaaS PostgreSQL (Cloud SQL, RDS)
• External Redis (ElastiCache, Memorystore)
• Cloud Native Hybrid variant available

3K Reference Architecture

Smallest HA architecture — up to 3,000 users, 60 RPS, ~28 nodes

Overview

The most commonly deployed production architecture. Every critical service has redundancy. This is the tier to recommend for any customer who needs high availability.

Node specifications

Total: ~28 nodes

Supported modifications

• Scaled-down HA — reduce specs while maintaining node redundancy for fewer users
• Cloud Native Hybrid — Puma + Sidekiq in Kubernetes, stateful services on VMs
• External PostgreSQL/Redis via PaaS
• Sharded Gitaly instead of Praefect cluster

5K Reference Architecture

HA with larger specs — up to 5,000 users, 100 RPS, ~28 nodes

Overview

Same node count as 3K but with larger CPU and RAM per node. The architecture shape doesn't change — services just get more resources.

Node specifications

Total: ~28 nodes

Supported modifications

• Split Redis (separate Cache + Persistent = 6 Redis nodes)
• Sidekiq autoscaling via Auto Scaling Groups
• TLS encryption between Praefect and Gitaly
• Cloud Native Hybrid variant

10K Reference Architecture

Large-scale HA — up to 10,000 users, 200 RPS, ~35 nodes

Overview

At this tier, Redis is split into separate Cache and Persistent clusters (6 Redis nodes instead of 3), and Sidekiq scales to 4 nodes.

Node specifications

Total: ~35 nodes (~236 vCPU, ~535 GB RAM)

25K Reference Architecture

Enterprise-scale HA — up to 25,000 users, 500 RPS, ~42 nodes

Node specifications

Total: ~42 nodes

50K Reference Architecture

Maximum scale — up to 50,000 users, 1,000 RPS, ~45 nodes

Node specifications

Total: ~45 nodes

GitLab Environment Toolkit (GET)

Official IaC toolkit for deploying GitLab reference architectures using Terraform and Ansible

What is GET?

The GitLab Environment Toolkit is GitLab's official Infrastructure as Code solution for provisioning and configuring GitLab reference architectures. It combines Terraform modules (infrastructure provisioning) with Ansible playbooks (GitLab configuration) to deploy production-ready environments that match GitLab's published reference architectures exactly.

Supported architectures

• 1K — single node (Ansible only, no Terraform needed)
• 2K — separated services, no HA
• 3K — smallest HA architecture (~28 nodes)
• 5K — HA with larger per-node specs
• 10K — split Redis, 4 Sidekiq nodes
• 25K / 50K — enterprise scale

Cloud providers

• AWS — EC2, RDS (optional), ElastiCache (optional), S3, ELB/NLB
• GCP — Compute Engine, Cloud SQL (optional), Memorystore (optional), GCS, Load Balancer
• Azure — VMs, Azure Database for PostgreSQL (optional), Azure Cache for Redis (optional), Blob Storage, Load Balancer

Key capabilities

• Cloud Native Hybrid — deploy Puma and Sidekiq in Kubernetes (via Helm) while keeping stateful services on VMs
• Geo deployments — provision primary + secondary sites with full Geo replication configuration
• Custom configs — inject custom gitlab.rb settings via Ansible variables
• Day 2 operations — re-run Ansible playbooks for upgrades, scaling, and config changes
• Air-gapped support — deploy in environments without internet access

Terraform workflow

# 1. Configure environment variables
cp terraform/environments/3k/variables.tf.example my-env/variables.tf
# Edit: AWS region, VPC, SSH key, domain, instance types...

# 2. Provision infrastructure
cd terraform/environments/my-env
terraform init
terraform plan    # review what will be created
terraform apply   # provision ~28 VMs, LBs, security groups

# 3. Configure GitLab via Ansible
cd ansible
ansible-playbook -i environments/my-env/inventory playbooks/all.yml

GitLab Geo

Cross-region replication for disaster recovery, distributed reads, and data residency compliance

What is Geo?

GitLab Geo creates read-only replicas of a GitLab instance in different geographic regions. It replicates Git repositories, the PostgreSQL database, LFS objects, uploads, container registry images, and other data types to one or more secondary sites.

How replication works

• Database: PostgreSQL streaming replication (physical, not logical). The secondary has a read-only replica of the entire database.
• Git repositories: Geo-specific replication via Gitaly. Repositories are synced asynchronously after push events on the primary.
• Files & artifacts: Synced via internal HTTP API calls from secondary to primary. Object storage can use native cloud replication (S3 CRR) as an alternative.
• Container registry: Registry images are replicated if using filesystem storage. With object storage, use cloud-native replication.

Failover process

Geo failover is manual, not automatic. The process:

1. Planned: Enable maintenance mode on primary → wait for replication to complete → run gitlab-ctl geo promote on secondary → update DNS
2. Unplanned: Run gitlab-ctl geo promote on secondary immediately → update DNS → accept potential data loss (equal to replication lag)

Monitoring Geo health

# Check Geo status from the secondary
gitlab-rake geo:status

# Key metrics to monitor:
# - Repositories synced vs. failed
# - Database replication lag (seconds)
# - Last event ID gap between primary and secondary
# - Verification status (checksums match)

Common gotchas

• Primary and secondary must run the same GitLab version — upgrade primary first, then secondary
• Geo does not replicate external services (Elasticsearch, external Redis, external PostgreSQL beyond streaming replication)
• The secondary site needs its own separate object storage buckets — don't share buckets between sites
• After failover, the old primary cannot simply be "demoted" — it must be fully reconfigured as a new secondary

Direct Transfer

GitLab's native group and project migration mechanism — API-based transfer between any two GitLab instances

What is Direct Transfer?

Direct Transfer (formerly "Bulk Import" or "GitLab Migration") is GitLab's built-in mechanism for migrating groups and projects between instances. It works via HTTPS API calls — the destination instance pulls data directly from the source. No intermediate files or manual export/import steps.

Requirements

• Version: Both instances should be 16.8+ for best results (Direct Transfer reached GA in Q2 2025). Source can be at most 2 minor versions behind destination.
• Network: HTTPS connectivity between instances (destination must reach source API).
• Source token: Personal access token with api scope on the source instance.
• Destination access: Owner role on the destination top-level group. Admin token is not required for standard migrations.
• Feature flag: Must be enabled in Admin → Settings → General → Import/Export on the destination.

What it transfers

• Repositories (including LFS), wikis
• Issues, merge requests, comments, resource events
• Labels, milestones, boards, badges
• Epics, iterations (Premium+)
• Members and role mappings (users must already exist on destination)
• Releases, snippets, CI pipeline history
• Group/subgroup structure

What it does NOT transfer

• CI/CD variables — contains secrets, must be re-created manually or via Congregate
• Container registry images — must be pushed separately (Congregate handles this)
• Deploy tokens and webhooks — security-sensitive, excluded by design
• Runners — must be re-registered on the destination
• Job artifacts — ephemeral, not migrated
• Approval rules, feature flags — not yet supported
• Pages domains and remote mirrors

User mapping

Direct Transfer maps users by public email address. Users are never created on the destination — they must already exist (via SCIM, SAML, or manual creation). If a user's email doesn't match, their contributions are reassigned to the user performing the import. Pre-migration user mapping verification is critical.

Congregate

GitLab Professional Services' migration automation tool for large-scale platform migrations

What is Congregate?

Congregate is GitLab Professional Services' migration automation tool. It now uses Direct Transfer under the hood for core group/project migration, then supplements it with post-migration API calls to handle objects that Direct Transfer doesn't cover.

How it works

1. Direct Transfer phase: Congregate triggers Direct Transfer API to migrate groups, projects, repos, issues, MRs, and other core objects
2. Post-migration phase: API calls to migrate CI/CD variables, container registry images, webhooks, deploy tokens, and other excluded objects
3. Verification: Validates migration completeness and generates reports

Supported sources

• GitLab — self→self, self→SaaS, SaaS→SaaS
• GitHub — GitHub.com and GitHub Enterprise
• Bitbucket — Server and Cloud
• Azure DevOps — SaaS and Server
• SVN — with documented conversion guidance

Wave orchestration

Congregate breaks large migrations into waves — batches of groups/projects that migrate together. This manages API rate limits, allows staged cutover (e.g., migrate team-by-team over weeks), and enables progress tracking across hundreds of projects.

Technical details

Python-based with Celery task scheduling, MongoDB for state tracking, and a web UI for monitoring progress. Supports incremental syncs (run multiple times, final cutover with minimal delta) and air-gapped migrations via two Congregate nodes with file-based data transfer.

Migrating from GitHub

Built-in importer with comprehensive project migration support

What gets migrated

• Repositories (including wiki repos)
• Issues and issue comments
• Pull requests and PR review comments
• Labels, milestones, releases
• Collaborators (mapped to GitLab users by email)

How to import

GitLab provides a built-in GitHub importer: New Project → Import Project → GitHub. Authenticate via personal access token (needs repo scope). Supports GitHub.com and GitHub Enterprise Server.

What doesn't migrate

• GitHub Actions workflows — must be manually converted to .gitlab-ci.yml
• GitHub Packages — re-publish to GitLab Package/Container Registry
• Branch protection rules — recreate in GitLab
• GitHub Apps and webhook configurations

Migrating from Bitbucket

Built-in importer for Bitbucket Cloud and Server

Bitbucket Cloud

• Built-in importer: New Project → Import → Bitbucket Cloud
• Authenticate via OAuth or App Password
• Migrates: repositories, pull requests, issues (if enabled), wiki
• Does not migrate: Bitbucket Pipelines (convert to .gitlab-ci.yml), deployment environments, project/workspace settings

Bitbucket Server / Data Center

• Built-in importer available for repositories and pull requests
• Requires API access to the Bitbucket Server instance
• For large-scale migrations, use Congregate via GitLab PS

Planning considerations

• Bitbucket projects map to GitLab groups/subgroups — plan the hierarchy before importing
• Bitbucket branch permissions → GitLab protected branches (manual recreation)
• Bitbucket Pipelines → .gitlab-ci.yml (manual conversion)

Migrating from Jira

Issue migration using jira2gitlab (open source) or Jira2Lab (GitLab PS)

jira2gitlab (open source)

Community tool at github.com/swingbit/jira2gitlab (MIT license). Works with Jira Server 8.5.1+ only (not Jira Cloud).

What it migrates

• Issues with titles, descriptions (Jira markup → Markdown conversion)
• Comments (including tables, formatting)
• Attachments (optional)
• Labels, components, priority, status, resolution → GitLab labels
• Fix versions → GitLab milestones
• Worklogs → comments with /spend quick actions
• Sub-tasks → issues with blocking relationships
• Epics → issues with label-based coupling
• "Relates to", "Blocks", "Duplicates" relationships
• Custom fields (as comment tables)

Key features

• Incremental/resumable — can run multiple times, updates changed issues
• User mapping — explicit mapping file, unmapped users attributed to admin
• Requires: Jira admin credentials, GitLab admin token, pre-created GitLab groups

Jira2Lab (GitLab PS)

GitLab Professional Services' enterprise fork for large-scale Jira migrations. Handles thousands of issues with better performance and reporting.

Alternative: Keep Jira

If using Jira Cloud (jira2gitlab doesn't support it), consider keeping Jira and using GitLab's native Jira integration instead: link commits/MRs to Jira issues, view GitLab pipelines in Jira, create GitLab branches from Jira issues.

Migrating from Jenkins

Manual pipeline conversion — Jenkinsfile to .gitlab-ci.yml

Largely manual migration

There is no fully automated tool to convert Jenkins pipelines to GitLab CI. Community CLI converters exist for simple cases, and GitLab provides a JenkinsFile Wrapper (unsupported) that runs Jenkins jobs inside GitLab CI as a transitional bridge. However, complex pipelines must be rewritten as .gitlab-ci.yml. The concepts map closely:

Migration strategy

1. Inventory pipelines — list all Jenkins jobs, categorize by type (build, test, deploy)
2. Prioritize — start with the most-used pipelines, convert less-used ones later
3. Convert incrementally — run Jenkins and GitLab CI in parallel during transition
4. Decommission Jenkins — once all pipelines are verified in GitLab CI

Common patterns

# Jenkins: stage('Build') { steps { sh 'make build' } }
# GitLab CI equivalent:
build:
  stage: build
  script:
    - make build
  artifacts:
    paths:
      - build/

# Jenkins: when { branch 'main' }
# GitLab CI equivalent:
deploy:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Migrating from SVN

Convert Subversion repositories to Git while preserving history

Migration process

1. Create author mapping — map SVN usernames to Git author format
2. Clone with git svn — converts SVN history to Git commits
3. Clean up — convert SVN branches/tags to proper Git refs
4. Push to GitLab

# Create author mapping file (authors.txt)
# svnuser = Git Name <email@example.com>
svn log --quiet svn://svn.example.com/repo | \
  awk '/^r/ {print $3}' | sort -u > svn_authors.txt
# Edit to: username = Full Name <email@example.com>

# Clone SVN repo with full history
git svn clone svn://svn.example.com/repo \
  --stdlayout \
  --authors-file=authors.txt \
  --no-metadata \
  my-repo

# Convert SVN tags to Git tags
cd my-repo
for tag in $(git branch -r | grep 'tags/'); do
  git tag $(echo $tag | sed 's|tags/||') $tag
  git branch -r -d $tag
done

# Push to GitLab
git remote add origin https://gitlab.example.com/group/repo.git
git push origin --all
git push origin --tags

Considerations

• Large repos — SVN repos with 100K+ commits take hours to convert. Run on a fast machine with SSD.
• svn:externals — no direct Git equivalent. Convert to Git submodules or subtrees, or restructure.
• Partial checkout — SVN supports sparse checkout of subdirectories. Git doesn't (well). Monorepo vs multi-repo decision needed.
• Binary files — move large binaries to Git LFS during conversion.

Migrating from Mercurial

Convert Mercurial repositories to Git for import into GitLab

Migration tools

• hg-fast-export (recommended) — fast, handles most repositories well
• hg-git — Mercurial extension that enables pushing to Git remotes
• git-cinnabar — Mozilla's tool for bidirectional Hg/Git

Using hg-fast-export

# Install fast-export
git clone https://github.com/frej/fast-export.git

# Create a new Git repo
git init my-repo-git
cd my-repo-git

# Run the conversion
../fast-export/hg-fast-export.sh \
  -r /path/to/mercurial-repo \
  --force

# Clean up and push to GitLab
git checkout HEAD
git remote add origin https://gitlab.example.com/group/repo.git
git push origin --all
git push origin --tags

Considerations

• Named branches — Mercurial named branches map to Git branches, but semantics differ (Hg branches are permanent, Git branches are movable pointers)
• Bookmarks — Mercurial bookmarks are closer to Git branches. Plan the mapping.
• Anonymous heads — Mercurial allows multiple heads on one branch. These need manual resolution.
• Subrepos — convert to Git submodules or merge into a monorepo.