Skip to content
Docs
Getting started

Getting started

This guide runs forgemirror locally or in a container and mirrors a first repository. For production, see Deployment.

Prerequisites

  • Forgejo: a Forgejo instance where you are an administrator (for a system webhook) or a repository owner (for a repository webhook).
  • Target tokens: a token with push access for each target forge, for example a GitHub fine-grained token with Contents: read and write on the destination repositories.
  • Source token: a Forgejo token with read access, if private repositories should be mirrored.
  • Existing target repositories: forgemirror pushes to repositories that already exist. It does not create them.

Install

Multi-arch images (linux/amd64, linux/arm64) are published with every release. The image runs as a non-root user and already contains git.

docker pull git.bitfoo.de/dvonessen/forgemirror:<version>

Write a configuration

Create forgemirror.yaml. This minimal setup mirrors every repository to the GitHub organization acme, under the same repository name:

webhook:
  secret: a-long-random-string  # openssl rand -hex 32
targets:
  - name: github
    url: "https://github.com/acme/{{ .Name }}.git"
    token: github_pat_...

Check it:

forgemirror --config forgemirror.yaml validate
# configuration is valid (1 targets)

All options, including filters and secrets read from files, are covered in Configuration.

Start the service 

docker run --rm -p 8080:8080 \
  -v "$PWD/forgemirror.yaml:/etc/forgemirror/forgemirror.yaml:ro" \
  git.bitfoo.de/dvonessen/forgemirror:<version> \
  --config /etc/forgemirror/forgemirror.yaml

curl localhost:8080/readyz answers ready.

Point Forgejo at it

In Forgejo, add a webhook of type Forgejo:

  • Target URL: http://<forgemirror-host>:8080/webhook
  • Content type: application/json
  • Secret: the value of webhook.secret
  • Trigger: push events

Forgejo webhook explains system webhooks and Forgejo’s ALLOWED_HOST_LIST, which blocks private addresses by default.

Push

Push to any repository. The log shows:

level=INFO msg="mirror started" repository=acme/app ref=refs/heads/main …
level=INFO msg="target mirrored" target=github outcome=success duration=1.2s …
level=INFO msg="mirror finished" repository=acme/app duration=1.9s …

If nothing happens, look at the webhook’s Recent deliveries in Forgejo and the troubleshooting table.

Last updated on
Configuration