GitAcross

Mirror releases between git hosts. When a new release appears on one host, GitAcross copies it to another — one clean commit per release, with the option to remove or rewrite files along the way.

local repo  ──>  GitHub       (publish local tags as releases)
Gitea       ──>  GitHub       (mirror dev to public)
GitHub      ──>  local repo   (backup)
...any combo                  (gitea, github, local)

Highlights:

• Clean history — every release lands as one commit on top of the last, so the target branch stays linear and readable
• Safe to re-run — already-synced releases are skipped, so it works on a schedule or in CI
• File transforms — exclude files or rewrite their contents before publishing
• Flexible endpoints — Gitea, GitHub, and local repositories, in any combination
• Config guardrails — lint and auto-fix your config before it runs

Contents

• Quick start
  • Install
  • Config
  • Run
• How it works
• Reference
  • Project anatomy
  • Endpoints — source & target
  • Source mode: release, tag, or commit
  • Excluding files
  • Transforming files
  • Retries
• How to use
  • CLI
  • Python API

Quick start

Install

pip install gitacross

For development, install the local checkout:

pip install -e .

Config

GitAcross reads a YAML file listing the mirrors you want. Each entry in the projects list is a project: it has a source (where releases come from) and a target (where they go).

Start from the fully commented config.yml.example — it covers remote-to-remote mirrors, prebuilt asset sync, local repos, backups, and commit-mode branch syncing:

cp config.yml.example config.yml

Then edit config.yml to fill in your own repos and tokens. Tokens like ${GITEA_TOKEN} are read from environment variables — keep secrets out of the file. See Project anatomy for everything else a project can have.

Run

# Preview what would change (no commits, no pushes)
gitacross --config config.yml --dry-run

# Check the config for errors and redundant settings
gitacross --config config.yml --lint

# Do the sync
gitacross --config config.yml

Run it again later — releases that were already synced are skipped, so nothing is duplicated. Use --project my-project to sync a single project. See CLI for all flags, or the Python API to drive GitAcross from code.

How it works

For each project, GitAcross watches the source and mirrors new releases to the target:

1. Fetch the list of releases from the source
2. Skip releases that were already synced (remembered in a local state file)
3. For each new release, oldest first:
   • Check out the release's file tree
   • Remove excluded files, then apply any file transforms
   • Commit the result on the target's branch — one commit per release
   • Tag the commit and publish the release on the target
4. Save the sync state

On remote targets the commit is pushed; on local targets the working tree is updated instead. Re-running the same command later only syncs new releases — already-synced ones are skipped.

Reference

Project anatomy

A config file starts with a projects list — each entry is one mirror and needs a name, a source, and a target; everything else is optional.

Endpoints — source & target

source and target each describe one git host:

Tokens use ${VAR} syntax — resolved from environment variables.

enabled

Set to false to pause a project without removing it from the config. Default true.

preserve_description

Copy the source release notes/body to the target release. Default true (alias: preserve_release_description). Set at the project or endpoint level; false leaves the target release description empty.

release_description

Format the target release notes from a template (aliases: release_notes_template, description_template). Placeholders: {body}, {description}, {tag}, {commit_sha}, {short_sha}, {project_name}, {name}, {source_date}.

commit_message

Custom commit message for the target commits (alias: commit_template). Default: "Release {tag}" or "Sync commit {short_sha}". Placeholders: {tag}, {commit_sha}, {short_sha}, {project_name}, {name}, {source_date}, {body}, {description}.

sync_assets

Mirror prebuilt release packages from the source to the target release — so you only need CI on the source platform (aliases: preserve_assets, include_assets). Project-level field:

projects:
  - name: my-project
    sync_assets:            # build on Gitea, upload prebuilts to GitHub
      - "*.tar.gz"
      - "*.zip"
      - "*.deb"
      - "*-checksums.txt"
    stream_assets: true     # stream uploads from disk — avoids buffering in RAM
    source:
      type: gitea
      ...
    target:
      type: github
      ...

stream_assets

Stream each asset upload directly from the temporary download directory on disk (cleaned up after syncing) instead of buffering the whole file in memory. Default false; set to true when syncing large prebuilt binaries (hundreds of MB) to avoid out-of-memory errors.

Source mode: release, tag, or commit

Remote sources sync from the host's API releases by default. Two alternatives are available: git tags, or the latest commit of a branch. A sync_from key on the source sets the starting point — only releases from that tag onward are synced.

Synced state is keyed by tag name, so switching a repo between release and tag modes is safe: already-synced tags are skipped regardless of the current mode (older state files keyed by API release id are migrated automatically).

release — API releases (default)

Remote sources sync from the host's API releases by default: prerelease/draft filtering applies, and sync_from must be an API release.

In release mode, a sync_from tag that exists only in git (no release object) — or is filtered out as prerelease/draft — produces a warning and syncs nothing. That points you at the right option, mode: tag or include_prereleases/include_drafts, instead of silently treating tags as releases.

tag — git tags

Set mode: tag to treat git tags as releases instead — useful when tags were pushed without creating release objects. sync_from: v2.0.0 starts at that tag, skipping older ones:

source:
  type: gitea
  repo: owner/repo
  api: https://gitea.example.com/api/v1
  token: ${GITEA_TOKEN}
  mode: tag
  sync_from: v2.0.0

commit — sync latest HEAD

Set mode: commit to sync the current HEAD of the source branch each time the script runs, rather than iterating over releases or tags. No tag or release is created on the target — only a plain commit is pushed.

source:
  type: gitea
  repo: owner/repo
  api: https://gitea.example.com/api/v1
  token: ${GITEA_TOKEN}
  mode: commit
  branch: main   # optional — which branch to read HEAD from (auto-detected if omitted)

Excluding files

Some files shouldn't be mirrored at all. The project's renderer block accepts an ignore list of glob patterns — matched paths are removed from every release before anything else runs:

renderer:
  ignore:
    - node_modules                 # any node_modules/ dir, at any depth
    - "*.secret"                   # only in root (single *, no /)
    - "build/**/*.o"               # any .o file under any build/ dir
    - ToDo.md                      # any file named ToDo.md, at any depth
    - some_folder/node_modules     # node_modules only when inside some_folder/
    - "./some_folder/node_modules"  # root-only variant (anchored to ./)

Two shortcuts worth knowing:

• .git/* matches only direct children like .git/config and misses deeper files such as .git/refs/heads/main — use .git/** to delete everything inside.
• Naming a directory directly (node_modules) removes the whole tree in one shot, which is slightly faster than listing node_modules/**.

Transforming files

The project's renderer block also accepts an operations list of file transformations. They run top-to-bottom in the order listed, both across blocks and within them — a later step can rely on an earlier one (e.g. rename a file, then replace text inside it).

remove

- remove:
    - path: .gitea                        # literal path
    - path: "*.secret"
      pattern: glob                       # glob pattern
    - path: "build\\d+"                   # regex matches path
      pattern: regex

rename

- rename:
    - from: .gitea
      to: .github
      pattern: literal

replace

Only UTF-8 text files are scanned. Binary files are skipped.

case_sensitive: false makes the search case-insensitive — search: gitea also matches Gitea and GITEA (combines with pattern: regex too).

match_case: true (handy with case_sensitive: false) adjusts each replacement to the casing of the matched text instead of writing it verbatim. With search: gitea, replace: github:

In regex mode, backreferences (e.g. \1) are expanded before the casing adaptation is applied.

- replace:
    - search: https://gitea\.example\.com
      replace: https://github.com
      pattern: regex
      glob: "*.md"
    - search: http://old-url.com
      replace: https://new-url.com
      pattern: literal
    - search: gitea
      replace: github
      case_sensitive: false
      match_case: true

add

- add:
    - path: .github/FUNDING.yml
      content: |
        github: myuser
    - path: RELEASE_NOTES.md
      content: |
        # Release Notes
        ...

validate

Aborts the entire release if any assertion fails.

- validate:
    - assert: file_exists
      path: README.md
    - assert: string_absent
      path: LICENSE
      pattern: "Gitea"
    - assert: string_exists
      path: README.md
      pattern: "mit"
      case_sensitive: false

Retries

Retry settings for API calls, configured in the project's retry block.

How to use

GitAcross can be driven from the command line or called directly from Python.

CLI

gitacross --config PATH [--project NAME] [--workdir PATH] [--dry-run] [--reset] [--lint] [--fix] [-v]

Python API

Prefer code over the CLI? GitAcross is importable from Python — handy for CI scripts and webhooks. Expand the use case that fits your situation:

import gitacross

results = gitacross.run("config.yml")

for r in results:
    print(f"{r['project']}: synced={r['synced']} releases={r['releases_synced']}")
    if r["error"]:
        print(f"  error: {r['error']}")

# Preview only — nothing is committed or pushed
results = gitacross.run(
    "config.yml",
    project="my-project",
    dry_run=True,
    work_dir="/data/custom_dir",
)

# Clears saved state and cache, so every release is treated as new
results = gitacross.run("config.yml", reset=True)

config = gitacross.Config.from_path("config.yml")

for project in config.projects:
    if project.enabled:
        gitacross.sync_project(project, ".gitsync", dry_run=False)

# ${VAR} tokens still resolve from the environment
project = gitacross.ProjectConfig({
    "name": "my-project",
    "source": {
        "type": "gitea",
        "repo": "owner/repo",
        "api": "https://gitea.example.com/api/v1",
        "token": "${GITEA_TOKEN}",
    },
    "target": {
        "type": "github",
        "repo": "owner/repo",
        "api": "https://api.github.com",
        "token": "${GITHUB_TOKEN}",
    },
})
gitacross.sync_project(project, ".gitsync")

report = gitacross.lint_config("config.yml", print_output=False)
if not report.is_valid:
    print([e.message for e in report.errors])
    gitacross.fix_config("config.yml", write_back=True)