/github-gitlab-mirror

name: github-gitlab-mirror
description: >-
  Audits or synchronizes the authoritative GitHub main branch to the internal
  GitLab mirror without importing GitLab-only history back into GitHub. Use
  when checking GitHub/GitLab consistency, updating the internal mirror, or
  resolving a divergence between the two remotes.

GitHub to GitLab Mirror

GitHub `main` is the single source of truth. GitLab exists to build and deploy the same commit internally.

Safety Rules

• Discover both remotes from their URLs; do not assume they are named `origin`

and `gitlab`.

• Never merge, cherry-pick, or push GitLab-only commits into GitHub.
• A fast-forward update to GitLab may proceed after verification.
• Rewriting a divergent GitLab branch requires explicit user authorization and

an exact `--force-with-lease` expectation.

• Do not change the local branch or working tree to mirror remote refs.

Status

1. Fetch both authoritative refs:

   git remote -v
   git fetch <github-remote> main
   git fetch <gitlab-remote> main

2. Record both SHAs and show commits unique to either side:

   git rev-parse <github-remote>/main
   git rev-parse <gitlab-remote>/main
   git log --oneline <gitlab-remote>/main..<github-remote>/main
   git log --oneline <github-remote>/main..<gitlab-remote>/main

3. Classify the relationship:

• Equal: already mirrored.
• GitLab is an ancestor of GitHub: safe fast-forward.
• GitHub is an ancestor of GitLab: GitLab contains mirror-only commits.
• Neither is an ancestor: the remotes diverged.

Synchronize

For a verified fast-forward:

git push <gitlab-remote> <github-remote>/main:refs/heads/main

For a GitLab-ahead or divergent branch, stop and display the GitLab-only commits. An explicit request to restore GitLab as the GitHub mirror authorizes discarding those mirror-only commits. Use the previously fetched GitLab SHA as the lease:

git push \
  --force-with-lease=refs/heads/main:<expected-gitlab-sha> \
  <gitlab-remote> \
  <github-remote>/main:refs/heads/main

If the lease fails, fetch and reassess instead of weakening the protection.

Verify

Fetch both remotes again and require exact SHA equality from fresh refs:

git fetch <github-remote> main
git fetch <gitlab-remote> main
test "$(git rev-parse <github-remote>/main)" = \
  "$(git rev-parse <gitlab-remote>/main)"

If GitHub advanced during the synchronization, return to the Status phase and mirror the new SHA. Do not claim success until one fresh fetch of both remotes observes equality.

Report both final SHAs and whether the GitLab build/deploy pipeline was triggered. Do not describe the mirror as synchronized until the SHAs match. The scheduled mirror job in `.gitlab-ci.yml` is the automation reference.