Mirror repositories and CDN — the read-only fallback

A read-only mirror is the deployment-side counterpart to the multi-remote failover pattern. Where Part XCVIII-02 covered how an engineer pushes during a forge outage, this lesson covers how CI, GitOps controllers, and deployment tooling read during the same outage. The mirror is a bare clone of the canonical remote that the deployment tooling fetches from; the CDN in front of the mirror gives low-latency clones from every region.

git clone --mirror https://github.com/acme/infra.git /srv/git/infra.git

git clone --mirror creates a bare repository with every ref, including remote-tracking branches, refs/remotes, and notes. The --mirror flag is what distinguishes this from git clone --bare, which creates a bare repository with the local branches only. The mirror’s refs are the same refs the canonical remote served at the moment of the clone.

flowchart LR
    A["canonical remote"] --> B["push-mirror sync"]
    B --> C["bare mirror /srv/git/infra.git"]
    C --> D["CDN edge"]
    D --> E["CI runner clone"]
    D --> F["GitOps controller fetch"]
    D --> G["engineer clone during outage"]

Why —mirror and not —bare

The two flags produce superficially similar results - a bare repository with no working tree - but the ref handling differs. git clone --bare sets up a bare repository with the local branches only; it does not configure any remote. A mirror created with --mirror includes every ref the remote advertised (branches, tags, notes, remote-tracking branches) and configures the fetch refspec and the canonical URL as the remote.

The practical difference: a --mirror clone is updated with a plain git fetch; a --bare clone has no remote configured and the fetch has to specify the URL and the refspec each time. --mirror is the production primitive; --bare is the academic primitive.

Fronting the mirror with a CDN

The mirror is read by CI runners, GitOps controllers, and deployment tooling in many regions. A single mirror in one region has a per-region latency penalty: a runner in ap-southeast-2 cloning a mirror in us-east-1 pays the trans-Pacific round-trip on every clone. A CDN fronts the mirror with edge caches that absorb the clone traffic and serve it from the closest edge.

The setup is a CDN (Cloudflare, Fastly, CloudFront) with origin pull pointing at the mirror’s hostname. The production discipline is to configure the CDN to not cache the authentication handshake: the smart-HTTP protocol sends an unauthenticated GET for the refs first and an authenticated POST for the negotiation, and only the GET is cacheable. The CDN URL is what the multi-remote failover from Part XCVIII-02 points at when the canonical is down.

Push-mirror sync

The mirror is kept current by one of two patterns: a push-mirror sync that the canonical remote pushes to, or a scheduled fetch that the mirror pulls from.

GitLab supports push-mirroring natively: the canonical remote is configured to push every commit to a second repository (GitLab calls this “push mirrors”). GitHub supports mirror repositories via the API and external services; Bitbucket supports mirror repositories at the repository level.

# Verify the push-mirror is current
cd /srv/git/infra.git
git fetch
git log --oneline -1

A scheduled fetch is the fallback when the canonical does not support push mirroring:

# Cron entry on the mirror host
*/5 * * * * cd /srv/git/infra.git && git fetch origin && date -u +%FT%TZ > /srv/git/infra.git/last-sync

The schedule period determines the RPO. A mirror synced every five minutes has an RPO of up to five minutes; a mirror synced every hour has an RPO of up to one hour. The RPO is the gap between the last successful sync and the disaster time.

The mirror vs the failover clone

The mirror and the failover clone serve different purposes and have different shapes:

• Mirror. Read-only, served by a CDN, updated by push-mirror or scheduled fetch. The mirror is what CI and GitOps controllers fetch from. The mirror does not accept engineer pushes.
• Failover clone. Writable, owned by the engineer, served by the multi-remote pattern from Part XCVIII-02. The failover clone is what the engineer pushes to when the canonical is down. The failover clone is not a CDN; it is a single clone on the engineer’s laptop or on a CI runner.

A team that conflates the two ends up with a mirror that engineers push to (which corrupts the read path) or a failover clone that CI fetches from (which fails every clone because the clone is single-tenant). The two patterns are complementary, not interchangeable.

# Mirror on the mirror host (read-only)
git clone --mirror https://github.com/acme/infra.git /srv/git/infra.git

# Failover clone on the engineer's laptop (writable)
git clone https://github.com/acme/infra.git ~/infra
git remote add backup https://backup.internal/acme/infra.git

Production discipline

1. Use git clone --mirror, not git clone --bare, for the read-only fallback. The --mirror flag configures the fetch refspec and the remote; the --bare flag does not.
2. Front the mirror with a CDN. A single mirror in one region has per-region latency; a CDN absorbs the clone traffic and serves from the closest edge.
3. Match the sync period to the RPO design constraint. A sync period longer than the RPO is a sync that cannot meet the design constraint.
4. Push-mirror when the canonical supports it, scheduled fetch when it does not. Push-mirror has a smaller RPO; scheduled fetch is the universal fallback.
5. Verify the mirror is current before the failover flip. A mirror that has not been synced in a week is a mirror that fails the failover.

Cross-course references

• Git, CI/CD & GitOps — Part XX-05 (Multiple Remotes) covers the multi-remote configuration this lesson’s CDN URL is plugged into.
• Git, CI/CD & GitOps — Part XCVIII-02 (Multi-Remote Failover) is the engineer-side counterpart this lesson’s mirror is paired with.
• GitOps with Argo CD — Part III (RepoAuth) covers the Argo CD repository URL configuration, which is exactly the CDN-fronted mirror URL this lesson produces.

Quiz