HA Search Architecture in GitHub Enterprise Server

GitHub Enterprise Server now employs Elasticsearch Cross‑Cluster Replication (CCR) to provide a resilient high‑availability search layer. This redesign separates search clusters per node, eliminates previous lock‑state failures, and ensures index consistency while supporting seamless upgrades and failover for enterprise deployments.

Deep Technical Analysis

The new architecture replaces the legacy multi‑node Elasticsearch cluster with independent single‑node clusters on each primary and replica server. CCR continuously copies persisted Lucene segments from the leader to followers, guaranteeing durability. Administrators activate the mode via the ghe-config app.elasticsearch.ccr true flag, after which the system migrates existing indexes and establishes auto‑follow policies for future indices.

Elasticsearch Integration History

Initially, GitHub leveraged a shared Elasticsearch cluster across HA nodes, forcing a primary/follower pattern that Elasticsearch could not natively support. This caused index lock conditions when shards moved between nodes during maintenance, leading to service interruptions.

Challenges with Clustered Mode

When a primary shard was relocated to a replica that was subsequently taken offline, the system entered a deadlock: the replica awaited a healthy cluster, while the cluster waited for the replica to rejoin. Custom health checks and mirroring attempts mitigated but did not resolve the root cause.

Locking Scenarios

Lock states manifested as stalled upgrade processes and read‑only index errors, requiring manual repair or full reindexing-operations that risked data loss and increased administrator overhead.

Cross‑Cluster Replication (CCR) Implementation

CCR, detailed in the Cross‑Cluster Replication (CCR) documentation, provides native leader/follower support. Each GHE node runs a dedicated Elasticsearch instance the primary node acts as the leader, while replicas follow via CCR, copying only fully committed segments.

Bootstrap Workflow

A bootstrap script enumerates existing indexes, filters managed GHE indexes, and creates follower relationships where missing. It then configures an auto‑follow policy to automatically replicate future indexes, ensuring continuous synchronization without manual intervention.

Operational Benefits

By isolating search clusters, upgrades become linear, failover is instantaneous, and index health monitoring is simplified. The architecture also reduces resource contention, as search queries are served locally on each node.

Deployment Steps for Administrators

1. Request a CCR license via support@github.com. 2. Set the configuration flag: ghe-config app.elasticsearch.ccr true. 3. Run config-apply or perform an upgrade to version 3.19.1 or later. 4. Verify index replication status through the GHE admin console. 5. Monitor for any lingering lock conditions and confirm auto‑follow policies are active.

Future Outlook

The CCR mode will become the default HA search configuration within two years, providing a stable foundation for upcoming GHE features that rely on real‑time search performance and reliability.