gitmeout

gitmeout

Container Images:

Mirror GitHub repositories to Forgejo/Codeberg instances

A fast, reliable CLI tool for mirroring repositories from GitHub to Forgejo/Codeberg. Supports both push and pull mirror modes, with flexible filtering and container-ready deployment.

Topics: github forgejo codeberg mirror backup git golang cli kubernetes docker

Features

• GitHub as source - Mirror personal and organization repositories
• Forgejo/Codeberg as targets - Create mirror repos on any Forgejo instance
• Flexible filtering - Filter by personal repos, orgs, or explicit repo list
• Wildcard support - Use owner/* to mirror all repos from an owner
• Dual mirror types - Push mirrors (clone + push) or pull mirrors (Forgejo MigrateRepo API)
• Token-only auth - Secure authentication via Personal Access Tokens
• Container-ready - Docker image and Kubernetes manifests included
• Multiarch support - Linux amd64/arm64 binaries and Docker images

⚠️ Disclaimer

Use this tool responsibly and only for repositories you own or have permission to mirror.

• Personal Use: This tool is designed for mirroring your own repositories or repositories you have explicit permission to mirror.
• GitHub ToS: Ensure your usage complies with GitHub's Terms of Service, including API rate limits and acceptable use policies.
• Rate Limits: GitHub's API has rate limits (5,000 authenticated requests/hour). Be mindful when mirroring large numbers of repositories.
• Data Portability: GitHub's ToS supports user data portability for your own content.
• No Warranty: This software is provided "as is" without warranty of any kind. The authors are not responsible for any issues arising from its use.

By using this tool, you agree to:

• Only mirror repositories you own or have permission to mirror
• Comply with GitHub's API Terms of Service
• Respect rate limits and not abuse the API
• Use it for legitimate data portability purposes

Quick Start

1. Create a config file

source:
  type: github
  token: ${GITHUB_TOKEN}
  filters:
    personal: true
    orgs:
      - my-org
    repos:
      - owner/repo1
      - owner/*

targets:
  - name: codeberg
    type: forgejo
    url: https://codeberg.org
    token: ${CODEBERG_TOKEN}

2. Set environment variables

export GITHUB_TOKEN="ghp_xxx"
export CODEBERG_TOKEN="xxx"

3. Run

# Using Just
just run

# Or directly
go run ./cmd/gitmeout

# Or with Docker
docker run --rm \
  -e GITHUB_TOKEN \
  -e CODEBERG_TOKEN \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  ghcr.io/guilycst/gitmeout:latest

Configuration

Source Configuration

Target Configuration

Mirror Types

Push Mirrors (mirror_type: push):

• Clones the repository from GitHub, then pushes --mirror to the target
• Syncs every run - changes on source are pushed to target
• Use for: Codeberg (pull mirrors disabled by admin)

Pull Mirrors (mirror_type: pull):

• Uses Forgejo's MigrateRepo API to create a pull mirror
• Forgejo periodically fetches changes from the source automatically
• Use for: Self-hosted Forgejo instances where pull mirrors are enabled
• Skips if a mirror already exists

Environment Variable Interpolation

Use ${VAR_NAME} syntax in config values to reference environment variables:

source:
  token: ${GITHUB_TOKEN}  # Reads from $GITHUB_TOKEN env var

Behavior

Repository Resolution

1. Personal repos: If personal: true, fetches all repos owned by the authenticated user
2. Organization repos: For each org in orgs, fetches all repos the user can access
3. Explicit repos: Resolves each entry in repos:
   • owner/repo-name: Specific repo
   • owner/*: All repos from that owner

Mirror Creation

• Existing mirrors: If a mirror repo already exists on the target, it is skipped
• New mirrors: Creates a new mirror repo pointing to the source

Required Token Permissions

GitHub:

• repo (for private repos)
• read:org (if filtering by orgs)

Forgejo/Codeberg:

• read:user - required to get authenticated user info
• write:repository - required to create mirror repositories

Deployment

Docker

docker build -t gitmeout:latest .
docker run --rm \
  -e GITHUB_TOKEN \
  -e CODEBERG_TOKEN \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  gitmeout:latest

Kubernetes

Create a secret for your config:

kubectl create secret generic gitmeout-config --from-file=config.yaml=config.yaml

Apply the CronJob:

kubectl apply -f deploy/k8s/cronjob.yaml

See deploy/k8s/ for Job and CronJob examples.

Kubernetes Custom Resource

For GitOps workflows, see deploy/k8s/job.yaml for a Job CR that can be used with tools like ArgoCD or Flux.

Development

# Install dependencies
go mod download

# Build
just build

# Run tests
just test

# Lint
just lint

# Format
just fmt

# Run all checks
just validate

License

MIT License - see LICENSE for details.