Mirroring a GitLab Repository to GitHub

Prerequisites

• A GitLab repository (source)
• A GitHub repository (target), which can be empty or already contain the same content
• Admin/Maintainer access to the GitLab project
• A GitHub account with write access to the target repository

Step 1: Create a Fine-Grained Personal Access Token on GitHub

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens. You are asked to authenticate with your GitHub account.
2. Click Generate new token
3. Configure the token:
   • Token name: choose a descriptive name (e.g., Test_token)
   • Expiration: choose an appropriate duration
   • Resource owner: select the organization that owns the target repo (e.g., agroscope-ch), or your personal account
   • Repository access: select Only select repositories and pick the target repository
   • Permissions → Repository permissions → Contents: set to Read and Write
4. Click Generate token
5. Copy the token immediately (it starts with github_pat_...). You won't be able to see it again.
6. Your administrator must validate your token (you will see a label pending until it is activated)

Step 2: Ensure Both Repositories Are in Sync

Before setting up mirroring, you have to make sure

• that the GitHub repo is up to date with GitLab
• that your personnal access token is activated

Option A (preferred and the most natural one): GitHub repo is empty

No action needed — GitLab will push everything on the first mirror sync.

Option B: GitHub repo already has content

From your local GitLab clone, add GitHub as a temporary remote and mirror-push:

cd /path/to/your/gitlab/repo
git remote add github https://github.com/<org>/<repo>.git
git push github --mirror
git remote remove github

This force-pushes all branches, tags, and refs to GitHub.

Step 3: Configure Push Mirroring in GitLab

1. Go to your GitLab project's web interface
2. Navigate to Settings → Repository
3. Expand the Mirroring repositories section
4. Fill in the fields:
   • Git repository URL: https://github.com/<org>/<repo>.git. In our example, it is https://github.com/agroscope-ch/test.git
   • Mirror direction: Push (no choice)
   • Authentication method: Username and Password (no choice)
   • Username: your personal GitHub username (the account that owns the token, not the organization name)
   • Password: the full token including the github_pat_ prefix.
5. Click Mirror repository

This should look like this

Step 4: Verify

1. After saving, you should see the mirror listed with a status indicator
2. Click the Update now button (refresh icon) to trigger an immediate sync
3. Check the GitHub repository to confirm the content matches GitLab. It now looks like the Gitlab repository

How It Works

• Every time you git push to GitLab, it automatically pushes to GitHub
• GitLab also periodically syncs (typically every 5 minutes)
• The mirror uses force push, so GitHub always matches GitLab exactly

Important Notes

• Treat GitHub as read-only. Any commits pushed directly to GitHub will be overwritten by the next mirror sync.
• If the token expires, the mirror will stop working. You'll need to regenerate a token and update the password in GitLab's mirroring settings.
• Fine-grained tokens must be scoped to the specific repository with Contents: Read and Write permission.