Mirroring GitHub to Codeberg

A GitHub Actions workflow that mirrors branches and tags to Codeberg with plain git push over SSH, without a third-party action.

I wanted a second home for my repository in case GitHub ever went away, or went weird, and Codeberg was the obvious pick. What I didn't want was another marketplace action in the middle of that path. A plain git push over SSH turns out to be enough.

The goal

  • Mirror from GitHub to Codeberg on every push to main.
  • No third-party dependency in the workflow.
  • Only branches and tags: a clean repository without origin/* refs leaking over.

A dedicated SSH key

The mirror should not reuse any existing key. I generated a fresh ed25519 pair locally, for this one purpose:

ssh-keygen -t ed25519 -C "github-actions-codeberg-mirror" -f ~/.ssh/codeberg_mirror -N ""

Keys in the right places

The two halves of the pair go to opposite sides, and mixing them up is the most common way this fails.

  • Codeberg deploy key (Repository → Settings → Deploy keys): paste the content of ~/.ssh/codeberg_mirror.pub. Enable Allow write access; without it the mirror can't push.
  • GitHub secret (Settings → Secrets and variables → Actions): create CODEBERG_SSH with the content of ~/.ssh/codeberg_mirror, the private key.

If a key form says Key is invalid. You must supply a key in OpenSSH public key format, the private key landed where the public one belongs. Swap them.

The workflow

File: .github/workflows/sync-mirror.yml:

name: Mirror to Codeberg
on:
  push:
    branches: [main]
  workflow_dispatch:
  schedule:
    - cron: '30 0 * * 0'

jobs:
  codeberg:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Configure SSH
        run: |
          mkdir -p ~/.ssh
          printf '%s\n' "${{ secrets.CODEBERG_SSH }}" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          ssh-keyscan -H codeberg.org >> ~/.ssh/known_hosts
          cat <<'EOF' > ~/.ssh/config
          Host codeberg.org
            HostName codeberg.org
            User git
            IdentityFile ~/.ssh/id_ed25519
            IdentitiesOnly yes
          EOF

      - name: Verify SSH access
        run: |
          ssh -T git@codeberg.org || true
          git ls-remote git@codeberg.org:adrian-altner/website.git > /dev/null

      - name: Mirror to Codeberg
        run: |
          git remote add mirror git@codeberg.org:adrian-altner/website.git

          # Remove previously mirrored remote-tracking refs (for example refs/remotes/origin/*).
          while IFS= read -r ref; do
            git push mirror ":${ref}"
          done < <(git ls-remote --refs mirror 'refs/remotes/*' | awk '{print $2}')

          # Mirror only real branches and tags.
          git push --prune mirror \
            +refs/heads/*:refs/heads/* \
            +refs/tags/*:refs/tags/*

Three triggers: every push to main, a manual workflow_dispatch button and a weekly cron on Sunday at 00:30 UTC. The cron is the safety net in case a Codeberg outage ever swallows a push without anyone noticing.

The mirror step does two things in order. First it clears any refs/remotes/* that slipped in during earlier runs: I had a few refs/remotes/origin/* on Codeberg from an older setup, and they kept coming back. Then it pushes refs/heads/* and refs/tags/* explicitly, with --prune, so deletions on GitHub carry over instead of piling up. --mirror would have carried over every remote-tracking ref as well.

Expected output during testing

On a successful SSH handshake, Forgejo (which Codeberg runs) prints:

... successfully authenticated ... but Forgejo does not provide shell access.

That's no error. The server refuses a shell but still handles fetch and push. If you see it, authentication worked.

Takeaways

  • One key, one purpose: revoking the mirror key never affects anything else.
  • Push explicit refspecs instead of --mirror to keep the destination clean.

More on this

Topic
  • Self-Hosting Running services on a server you control instead of using a provider's hosted version, with the upkeep that comes with it.
See also
  • GitHub Deploy Key on a VPS A read-only SSH deploy key so a VPS can pull from GitHub without a personal access token or a password.
Tags

Show in the graph view →