Files
hermes ae400c416e feat(fork-sync): discover forks dynamically via Gitea API
Removes the hardcoded FORK_PAIRS list. The workflow now calls
GET /api/v1/users/{user}/repos and walks every repo where
`fork=true`, using `parent.full_name` as the upstream.

Behaviour:
- FORK_PAIRS env still works as an explicit override (used by tests).
- New forks owned by hermes are picked up automatically without any
  config change.
- Repos whose parent is not accessible (private, deleted, ACL change)
  are skipped with a single ::note:: log line.
- All other behaviour unchanged: clones, FF, branch creation, push.

Tested locally against the live Gitea: discovered 5 forks
(brencher, ansible, reverseproxy, mcps, hermes-voice-gateway) and
synced them as expected.

Assisted-By: hermes-agent:minimax-m3
2026-09-14 20:12:48 +00:00

261 lines
8.9 KiB
Python
Executable File

#!/usr/bin/env python3
"""
fork-sync: silently keep `hermes/<name>` forks in sync with their upstream.
Walks a list of fork pairs, for each:
1. fetches upstream and origin
2. fast-forwards every local branch that has upstream counterpart and is behind
3. creates local tracking branches for upstream branches that we don't have yet
4. reports a single Telegram alert on divergence (behind-by-N or missing branch)
Stdout empty on quiet tick. Non-empty stdout = one Telegram alert.
Config (env):
GITEA_TOKEN required
FORK_PAIRS "hermes/<name>=admin/<name>,hermes/<name>=admin/<name>,..."
default covers all 5 forks owned by hermes
WORK_ROOT default /opt/data/fork-sync
SKIP_BRANCHES comma-separated branch names to skip (default: HEAD,main_corrupted)
"""
import json
import os
import subprocess
import sys
import urllib.error
import urllib.request
from pathlib import Path
TOKEN = os.environ.get("GITEA_TOKEN", "")
GITEA_API = os.environ.get("GITEA_API", "https://gitea.rudolf.keenetic.link/api/v1").rstrip("/")
GITEA_USER = os.environ.get("GITEA_USER", "hermes")
FORK_PAIRS = os.environ.get("FORK_PAIRS", "")
WORK_ROOT = Path(os.environ.get("WORK_ROOT", "/opt/data/fork-sync"))
SKIP_BRANCHES = set(
b.strip() for b in os.environ.get("SKIP_BRANCHES", "HEAD,main_corrupted").split(",") if b.strip()
)
AUTH_URL = f"https://x-access-token:{TOKEN}@gitea.rudolf.keenetic.link"
def http_get_json(url, timeout=30):
req = urllib.request.Request(url, headers={"Authorization": f"token {TOKEN}"})
try:
with urllib.request.urlopen(req, timeout=timeout) as r:
return r.status, json.loads(r.read().decode("utf-8", errors="replace"))
except urllib.error.HTTPError as e:
return e.code, {}
except Exception:
return 0, {}
def discover_forks():
"""Walk every repo owned by GITEA_USER, return [(fork_full, upstream_full)].
Strategy:
1. If FORK_PAIRS is set in env, honour it (escape hatch for explicit
overrides / tests).
2. Otherwise call GET /api/v1/users/{user}/repos and pick ones whose
`fork` flag is true; use `parent.full_name` as upstream. Repos that
have no parent or where parent is not accessible are skipped.
3. Filter out any repo already up to date to keep the run cheap.
"""
if FORK_PAIRS:
pairs = []
for p in FORK_PAIRS.split(","):
p = p.strip()
if not p:
continue
fork, upstream = p.split("=", 1)
pairs.append((fork.strip(), upstream.strip()))
return pairs
code, payload = http_get_json(
f"{GITEA_API}/users/{GITEA_USER}/repos?limit=100&type=all"
)
if code != 200:
raise RuntimeError(f"Gitea API error fetching user repos: HTTP {code}")
pairs = []
skipped = []
for repo in payload:
full = repo.get("full_name") or ""
if not full.startswith(f"{GITEA_USER}/"):
continue
if not repo.get("fork"):
continue
parent = repo.get("parent") or {}
upstream = parent.get("full_name")
if not upstream:
skipped.append(f"{full}: no parent")
continue
if not parent.get("permissions", {}).get("pull", False) \
and not parent.get("permissions", {}).get("push", False):
try:
code, _ = http_get_json(f"{GITEA_API}/repos/{upstream}")
if code != 200:
skipped.append(f"{full}: parent {upstream} not accessible")
continue
except Exception:
skipped.append(f"{full}: parent check failed")
continue
pairs.append((full, upstream))
if skipped:
print(f"::note:: skipped {len(skipped)} forks: {skipped}", file=sys.stderr)
return pairs
def run(cmd, cwd=None, check=True, capture=False, timeout=60):
res = subprocess.run(
cmd, cwd=cwd, shell=isinstance(cmd, str),
capture_output=capture, text=True, timeout=timeout,
)
if check and res.returncode != 0:
raise RuntimeError(f"cmd failed: {cmd}\n{res.stderr}")
return res
def ensure_clone(fork_full, upstream_full):
"""Clone the fork if not present, ensure upstream remote exists, fetch both."""
local = WORK_ROOT / fork_full.replace("/", "__")
if not (local / ".git").exists():
local.parent.mkdir(parents=True, exist_ok=True)
run(["git", "clone", "--quiet", f"{AUTH_URL}/{fork_full}.git", str(local)])
# `git remote remove` exits non-zero when the remote doesn't exist; ignore.
res = run(
["git", "remote", "remove", "upstream"], cwd=str(local), check=False,
capture=True,
)
run(
["git", "remote", "add", "upstream", f"{AUTH_URL}/{upstream_full}.git"],
cwd=str(local), check=res.returncode == 0,
)
run(["git", "fetch", "--prune", "--quiet", "upstream"], cwd=str(local), timeout=120)
run(["git", "fetch", "--prune", "--quiet", "origin"], cwd=str(local), timeout=120)
return local
def list_upstream_branches(local):
res = run(
["git", "for-each-ref", "--format=%(refname:short)", "refs/remotes/upstream/"],
cwd=str(local), capture=True,
)
out = []
for line in res.stdout.splitlines():
b = line.strip()
if b.startswith("upstream/") and b != "upstream/HEAD":
out.append(b[len("upstream/"):])
return out
def list_local_branches(local):
res = run(
["git", "for-each-ref", "--format=%(refname:short)", "refs/heads/"],
cwd=str(local), capture=True,
)
return [b.strip() for b in res.stdout.splitlines() if b.strip()]
def ff_one(local, branch):
"""Try to fast-forward local/<branch> to upstream/<branch> and push to origin."""
if not subprocess.run(
["git", "rev-parse", "--verify", "--quiet", f"refs/remotes/upstream/{branch}"],
cwd=str(local), capture_output=True,
).returncode == 0:
return True, 0
res = run(
["git", "rev-list", "--count", f"{branch}..upstream/{branch}"],
cwd=str(local), capture=True,
)
behind = int(res.stdout.strip() or "0")
if behind == 0:
return True, 0
try:
run(["git", "merge", "--ff-only", f"upstream/{branch}"], cwd=str(local), timeout=30)
except Exception as e:
return False, behind
try:
push_res = run(
["git", "push", "origin", branch],
cwd=str(local), capture=True, timeout=120,
)
return True, behind
except Exception as e:
return False, behind
def ff_all(local):
"""For every local branch with upstream/<name>, fast-forward. Return (ffed, divergences)."""
ffed = 0
divergences = []
for branch in list_local_branches(local):
if branch in SKIP_BRANCHES:
continue
ok, behind = ff_one(local, branch)
if ok and behind > 0:
ffed += 1
elif not ok and behind > 0:
divergences.append(f"{branch} (behind {behind})")
return ffed, divergences
def create_missing_branches(local):
"""Create local tracking branches for every upstream branch we don't have, push to origin."""
upstream_branches = list_upstream_branches(local)
local_branches = set(list_local_branches(local))
created = []
pushed = []
for b in upstream_branches:
if b in SKIP_BRANCHES:
continue
if b in local_branches:
continue
run(["git", "branch", b, f"upstream/{b}"], cwd=str(local), check=False)
created.append(b)
try:
run(["git", "push", "origin", b], cwd=str(local), capture=True, timeout=120)
pushed.append(b)
except Exception:
pass
return created, pushed
def main():
if not TOKEN:
print("ERROR: GITEA_TOKEN not set", file=sys.stderr)
sys.exit(2)
WORK_ROOT.mkdir(parents=True, exist_ok=True)
try:
pairs = discover_forks()
except Exception as e:
print(f"ERROR: failed to discover forks: {e!r}", file=sys.stderr)
sys.exit(2)
if not pairs:
return
alerts = []
for fork, upstream in pairs:
try:
local = ensure_clone(fork, upstream)
ffed, divs = ff_all(local)
created, pushed = create_missing_branches(local)
except Exception as e:
alerts.append(f"❌ {fork}: ERROR {e!r}")
continue
if ffed or divs or created or pushed:
line = f"📦 {fork} (← {upstream}):"
if ffed:
line += f" ff={ffed}"
if created:
line += f" created={created}"
if pushed:
line += f" pushed={pushed}"
if divs:
line += f" divergent={divs}"
alerts.append(line)
if not alerts:
return
print("\n".join(alerts))
sys.exit(2) # 2 = changes reported, distinct from 1 = real error
if __name__ == "__main__":
main()