From b52f8800660122e19734766650e08712e736fdea Mon Sep 17 00:00:00 2001
From: omen <14905147+adamzend@users.noreply.github.com>
Date: Mon, 19 Oct 2026 14:31:35 +0200
Subject: [PATCH] Document weekly root cron deployment and quiet-mode
 verification

---
 CHANGELOG.md           | 46 ++++++++++++++++++++++++++++++++++++++++++
 README.md              | 38 +++++++++++++++++++++++++++++++++-
 README.txt             | 29 ++++++++++++++++++++++++++
 gitea-github-sync.cron |  5 +++++
 4 files changed, 117 insertions(+), 1 deletion(-)
 create mode 100644 CHANGELOG.md
 create mode 100644 gitea-github-sync.cron

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..90222ad
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,46 @@
+# Changelog
+
+## v1.0.2 - 2026-10-19
+
+### Changes
+
+- Added `gitea-github-sync.cron`, a system cron example for Monday at 03:00,
+  running as root with `--apply-quiet`.
+- Documented installing the script at a stable absolute path, installing the
+  cron file with the required ownership/permissions, and checking service/logs.
+- Clarified that quiet mode detaches the worker and records its final exit
+  status in the log; the launcher's exit status does not confirm sync success.
+- Included the existing GPL-3.0-only license in the release bundle.
+
+### Why
+
+The original server still had an older script without `--apply-quiet`, and the
+expected weekly cron entry had not been installed. Deploying the already
+published script and adding the system cron entry resolved those deployment
+gaps. The reusable cron example and verification instructions make these steps
+explicit for other installations.
+
+`--apply-quiet` was already included in v1.0.0 and v1.0.1. The synchronization
+script in v1.0.2 is byte-for-byte identical to v1.0.1; this release documents and
+packages the scheduling setup rather than claiming a new quiet-mode code change.
+
+### Verification
+
+- Confirmed that the deployed script matches the published v1.0.1 script.
+- Confirmed the installed weekly root cron entry, active/enabled cron service,
+  required commands, script syntax and successful read-only API access.
+- The scheduled synchronization itself was not manually triggered during these
+  checks; successful completion must be confirmed in the log after execution.
+
+## v1.0.1 - 2026-10-04
+
+- Required an explicit `GITEA_URL` and removed the deployment-specific fallback.
+- Added base-URL validation and documented custom hosts and web path prefixes.
+- Made the example configuration independent of a specific Gitea account.
+
+## v1.0.0 - 2026-10-04
+
+- First public release: automatic discovery of GitHub mirrors and enrichment
+  with metadata, topics, issues and comments.
+- Included dry-run, foreground apply and quiet background apply modes,
+  rate-limit handling, locking and English/YunoHost documentation.
diff --git a/README.md b/README.md
index 9379f37..2e5633c 100644
--- a/README.md
+++ b/README.md
@@ -82,6 +82,42 @@ check the log's final `exit_status` to determine the actual result.
 sudo tail -f /var/log/gitea-github-sync.log
 ```
 
+## Weekly cron job
+
+The release includes [`gitea-github-sync.cron`](gitea-github-sync.cron), which runs
+the script **as root every Monday at 03:00 in the server's timezone**.
+First configure `/etc/gitea-github-sync.conf` with your instance URL and tokens.
+From the extracted release directory, install the script and cron entry:
+
+```bash
+sudo install -o root -g root -m 755 ./gitea-github-sync.sh /usr/local/bin/gitea-github-sync.sh
+sudo install -o root -g root -m 644 ./gitea-github-sync.cron /etc/cron.d/gitea-github-sync
+```
+
+This does not overwrite your configuration or trigger an immediate sync. Check
+for an existing equivalent job before installing, so it is not scheduled twice.
+This file is for `/etc/cron.d`, where the `root` column is required; do not paste
+it unchanged into a per-user `crontab -e`.
+
+```bash
+sudo cat /etc/cron.d/gitea-github-sync
+systemctl is-active cron
+systemctl is-enabled cron
+timedatectl show -p Timezone
+sudo tail -n 100 /var/log/gitea-github-sync.log
+```
+
+Cron must be installed and running. On a system with an existing active cron
+service, a new `/etc/cron.d` file is read automatically without a restart.
+The log path can be overridden by `QUIET_LOG_FILE`. Look for
+`Background worker finished: PID=..., exit_status=0` to confirm successful
+completion. Starting the quiet worker alone does not confirm completion.
+If using a scheduler that must track the final process exit code, use foreground
+`--apply` instead. No additional shell output redirection is needed for quiet mode.
+
+See the [changelog](CHANGELOG.md) for what changed and why. Quiet mode already
+existed in v1.0.1; v1.0.2 adds the reusable scheduling setup and documentation.
+
 **Depending on the number of repositories/mirrors and their issues/comments,
 execution can take a very long time, potentially hours.** Quiet mode does not
 speed up synchronization. GitHub limits may require a later run.
@@ -112,7 +148,7 @@ mock API tests, including multiple mirrors, idempotency, throttling and quiet mo
 
 Download the script or the complete bundle from
 [GitHub Releases](https://github.com/adamzend/gitea-github-sync/releases).
-The latest release is **v1.0.1**, which requires an explicitly configured Gitea URL.
+The latest release is **v1.0.2**, with weekly root cron setup and deployment notes.
 
 ## License
 
diff --git a/README.txt b/README.txt
index b09add0..bd55eb0 100644
--- a/README.txt
+++ b/README.txt
@@ -57,6 +57,35 @@ requests while still enriching repositories. Non-root runs need LOCK_FILE in
 a writable, trusted directory. All runs must use the same lock file.
 No schedule is installed; the script can be invoked by cron or systemd.
 
+Weekly root cron setup (v1.0.2)
+------------------------------
+Quiet mode was already supported in v1.0.1. This release keeps the script
+unchanged and adds a reusable system cron file plus deployment instructions.
+An older installed copy must be replaced before scheduling --apply-quiet.
+
+After configuring /etc/gitea-github-sync.conf, run from the release directory:
+  sudo install -o root -g root -m 755 ./gitea-github-sync.sh /usr/local/bin/gitea-github-sync.sh
+  sudo install -o root -g root -m 644 ./gitea-github-sync.cron /etc/cron.d/gitea-github-sync
+
+The supplied entry runs as root every Monday at 03:00 in the server's timezone.
+It uses absolute script/configuration paths and an explicit command search PATH.
+The cron file does not run the task immediately. Check for equivalent existing
+jobs to avoid duplicate scheduling. This is an /etc/cron.d file with a username
+column; it cannot be pasted unchanged into a per-user crontab.
+
+Verify the setup:
+  sudo cat /etc/cron.d/gitea-github-sync
+  systemctl is-active cron
+  systemctl is-enabled cron
+  timedatectl show -p Timezone
+  sudo tail -n 100 /var/log/gitea-github-sync.log
+
+The cron service must be installed and active. No restart is needed for an
+already-running cron daemon to read the new entry. Look for the background
+worker's final exit_status=0 in the log after execution. A valid schedule or
+successful background launch does not itself prove a completed synchronization.
+For a customized QUIET_LOG_FILE, inspect that file instead.
+
 Complete command-line reference
 -------------------------------
 --dry-run
diff --git a/gitea-github-sync.cron b/gitea-github-sync.cron
new file mode 100644
index 0000000..d1a7651
--- /dev/null
+++ b/gitea-github-sync.cron
@@ -0,0 +1,5 @@
+# Install as /etc/cron.d/gitea-github-sync (root:root, mode 644).
+# Runs every Monday at 03:00 in the server's timezone.
+SHELL=/bin/sh
+PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+0 3 * * 1 root /bin/bash /usr/local/bin/gitea-github-sync.sh --config /etc/gitea-github-sync.conf --apply-quiet