KiteStacks Forgejo Automation – Watcher Script Documentation
Overview

The kitestacks-watcher.sh script is a systemd-compatible file watcher for the KiteStacks Homelab. Its main responsibilities:

Watch configured directories for file changes.
Sync changes to the correct apps/ or clusters/ folder in the repo.
Automatically bump version in README.md.
Update versioned documentation and CHANGELOG.md.
Commit and push changes to either test or main repository.
Throttle updates to prevent frequent commits when changes are rapid.
Key Features Added in This Setup
1. 20-Minute Conditional Throttling
The script now tracks the last successful push.
Commits/pushes only happen once every 20 minutes.
If changes occur multiple times within 20 minutes, they are batched into a single update.
Logs indicate skipped pushes during throttle:
[autosync] 2026-06-06 12:50:10 INFO  Throttling active, skipping commit/push for 1190s
2. Initial Setup Steps
Navigate to the scripts folder:
cd ~/kitestacks-homelab-autosync-test/scripts
Make the watcher script executable:
chmod +x kitestacks-watcher.sh
Run manually to test:
./kitestacks-watcher.sh
Observe logs for startup confirmation.
Make a small change in a watched directory (e.g., apps/forgejo/README.md) to trigger the watcher.
Run in background (detach from terminal):
mkdir -p ~/logs
nohup ./kitestacks-watcher.sh > ~/logs/kitestacks-watcher.log 2>&1 &
Verify process is running:
ps aux | grep kitestacks-watcher
tail -f ~/logs/kitestacks-watcher.log
3. Optional: systemd Service

Create /etc/systemd/system/kitestacks-watcher.service:

[Unit]
Description=KiteStacks AutoSync Watcher
After=network.target

[Service]
Type=simple
User=kenpat
WorkingDirectory=/home/kenpat/kitestacks-homelab-autosync-test/scripts
ExecStart=/home/kenpat/kitestacks-homelab-autosync-test/scripts/kitestacks-watcher.sh
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable kitestacks-watcher.service
sudo systemctl start kitestacks-watcher.service
sudo systemctl status kitestacks-watcher.service

View logs:

journalctl -u kitestacks-watcher.service -f
4. Script Behavior Summary
Watches directories listed in $WATCH_DIRS.
Debounce period defined in $DEBOUNCE_SECONDS (default 15s) to batch rapid changes.
Maps filesystem paths to repo folders (apps/ for Docker apps, clusters/assassin/ for cluster configs).
Updates README.md version tags and generates versioned docs in docs/.
Maintains a CHANGELOG.md with automated entries.
Pushes updates to either test or main repo based on $STATE_FILE.
Throttle ensures that frequent changes do not flood the repository with commits.
5. Verification
Make a change to a file in the watched directories.
Confirm logs show sync, doc creation, and commit/push.
Multiple changes within 20 minutes are batched.
Watch for throttling messages confirming 20-minute delay between pushes.
6. Notes / Recommendations
Keep $WATCH_DIRS and $EXCLUDE_PATTERNS properly configured in settings.conf.
Use logs (~/logs/kitestacks-watcher.log) for debugging.
Manual testing is recommended after any config changes.
systemd integration ensures the watcher starts automatically on reboot.