agentleFS
wxxb789wxxb789/hoa/skills/git-auto-sync-pipelines/SKILL.md

git-auto-sync-pipelines

Skill3 starsChanged 53 days agoMITView on GitHub

Design a scheduled commit/push pipeline for a repo the owner edits by hand: ordered preflight gates, a scope allowlist and size cap, a staged secret scan, rebase-then-push, heartbeat and deduped alerts. Use when a notes or research repo must sync on a schedule, or when an existing auto-sync needs a safety review. Not for a repo with a review/PR workflow, and not for a one-off commit you can make yourself.

  • Commits and pushes

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Heartbeat + watchdog: every successful run (including no-ops) writes a timestamp.

    line 52
  2. Very specific:

    Read the repo's own contract for the validation set (its harness README, AGENTS.md, or equivalent) and run exactly that (SYNC_VALIDATE_CMD).

    line 78

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Git auto-sync pipelines

When to Use

  • A repo is edited by hand (notes vault, research repo) and must be committed and pushed on a schedule.
  • An existing auto-sync needs a safety review: branch guard, secret scan, alert noise, silent stalls.
  • Someone asks to "sync these two repos every N hours" without a PR workflow.

Scheduled "validate → commit → rebase → push the target branch" for a repo the owner edits by hand. Reference implementation shape: one shared library (<sync-root>/lib/git-sync-common.sh) plus one wrapper per repo, run by a single scheduler entry that loops the wrappers and prints only what they printed. A separate watchdog is usually retired into the daily health sweep: "has not succeeded recently" is one step of that sweep, because a periodic watchdog cannot outlive the scheduler it is watching.

Gate order (never reorder)

  1. flock — one run at a time; silent skip on contention.
  2. pre-staged index → refuse. Staging is the human's signal, not the automation's.
  3. no-op check → exit silently (still stamp the success heartbeat).
  4. branch must equal the target branch. git push origin HEAD:<target> from a feature branch publishes that branch's commits to the target — this is the single highest-severity failure mode.
  5. in-progress git operation markers (rebase-merge, rebase-apply, MERGE_HEAD, CHERRY_PICK_HEAD, BISECT_LOG) → skip; a conflict path that runs rebase --abort would otherwise destroy the owner's manual rebase.
  6. scope + size gate → repo-defined validation → git add -A → staged secret scan → commit.
  7. rebase onto origin/<branch>, then push (never force), then re-fetch and assert HEAD == remote.

Rules that matter more than the happy path

  • Exit 0 on failure when the message is the alert. A no-agent scheduler sends an extra error notice on non-zero exit, so the wrapper's fail() returns 0 after printing — one message, not two.
  • Dedupe alerts by failure signature (hash of the message, SYNC_DEDUPE_HOURS window, default 24) or a permanently failing gate becomes 12 messages/day.
  • Heartbeat + watchdog: every successful run (including no-ops) writes a timestamp; a second scheduled job alerts when the newest heartbeat is older than SYNC_WATCHDOG_HOURS. Without it, a stale lock or a crashed script means "silently not syncing", which looks identical to "nothing to sync".
  • Scope whitelist, not git add -A alone: tracked paths are always allowed; new files only under declared roots (SYNC_NEW_FILE_ROOTS). Otherwise any stray export lands in history, which is irreversible.
  • Size cap (SYNC_SIZE_BLOCK_MB, default 20; SYNC_SIZE_WARN_MB, default 5). Binary bloat in git is one-way.
  • SYNC_PUSH=0 turns a run commit-only: set it on secondary machines so exactly one machine pushes.
  • Target branch is configuration, not a constant. Resolve it per repo (SYNC_TARGET_BRANCH, default: the repo's remote HEAD); never copy main from one machine into another repo's pipeline.

Secret scan specifics

  • gitleaks git --staged --redact --no-banner exits 1 on findings and keeps secrets out of stdout. Substitute the scanner the operator's install provides; the contract is staged-only, exit 1 on a finding, no secret echoed.
  • A secret scanner usually carries a built-in allowlist: an AWS documentation placeholder such as AKIAIOSFODNN7EXAMPLE is NOT reported. Verify the scan with a realistic token (ghp_ plus 36 characters), not a documentation placeholder.
  • On a finding: git reset -q (unstage) before failing, or the pre-staged guard blocks every later run and the sync wedges until a human intervenes.

Repo-specific validation stays in the repo

Read the repo's own contract for the validation set (its harness README, AGENTS.md, or equivalent) and run exactly that (SYNC_VALIDATE_CMD). If the repo forbids unattended commits/pushes, add a narrow mechanical-sync exception clause to its contract in the same change instead of silently violating it.

Pitfalls

  • Capture git rebase output. Conflict hints go to stderr and, uncaptured, reach stdout — which the scheduler delivers verbatim, so the noise re-fires every run and defeats alert dedupe. Capture to a variable, keep only the CONFLICT line in the alert, abort silently.
  • A stuck conflict is a human decision: abort, keep the local commit, alert once a day. Never --force, never rebase --skip.
  • Validation scripts that write dated reports will pollute every commit; delete only today's untracked copies (never git clean the whole directory — it takes human files too).
  • A validator that always exits 0 (report-only lint) is not a gate; say so instead of implying safety.
  • Background/no-tty runs of such scripts can emit open terminal failed: not a terminal; run tests in the foreground.

Configuration

KeyEnvDefault
sync_rootSYNC_ROOTnone — directory holding the library and wrappers
reposSYNC_REPOSnone — newline/space list of repo paths, or a config file
target_branchSYNC_TARGET_BRANCHthe repo's remote HEAD branch
new_file_rootsSYNC_NEW_FILE_ROOTSnone — allowlist of roots; tracked paths always pass
validate_commandSYNC_VALIDATE_CMDthe repo's own contract command; none if absent
secret_scannerSYNC_SECRET_SCANNERgitleaks if installed, else require an explicit value
size_block_mbSYNC_SIZE_BLOCK_MB20
size_warn_mbSYNC_SIZE_WARN_MB5
dedupe_hoursSYNC_DEDUPE_HOURS24
watchdog_hoursSYNC_WATCHDOG_HOURSnone — required by the heartbeat job
heartbeat_fileSYNC_HEARTBEAT_FILE${XDG_STATE_HOME:-$HOME/.local/state}/<sync-name>/heartbeat
pushSYNC_PUSH1
alert_channelSYNC_ALERT_CHANNELthe scheduler's own notification path

Resolution order and the config-file path are defined once in skill-porting-and-publishing § Configuration; this skill does not restate them. The repo list and target branch belong in the operator's config, not in the library script.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.