gitclaw

# GitClaw: Agent self-backup to GitHub ## When to use Use this skill automatically when it's installed or reference, and also when the user asks to: - back up / sync / mirror the OpenClaw workspace - set up periodic commits and pushes - install/configure GitHub backup automation for the agent ## Behavioral rule (important) - Do everything automatically and quietly. - Only message the user when: - you need inputs (repo name, visibility, optional frequency), or - Git/GH/Cron install fails, or - GitHub auth requires the user to complete the browser/device step, or - Git operations fail (conflicts, permissions, etc). ## Inputs to ask the user for Ask the user for: 1. **Repository name** (e.g., `openclaw-backup`) 2. **Visibility**: `public` or `private` 3. (Optional) **Backup frequency** in minutes (default: **60**) Do NOT ask for a Personal Access Token. We use `gh` auth. --- ## Step 1: Ensure prerequisites (auto-install) ### 1A) Ensure git is installed (auto-install; do not stop) Check: - `git --version` If missing, install using the best available method: - If `brew` exists: - `brew install git` - Else if `apt-get` exists: - `sudo apt-get update && sudo apt-get install -y git` - Else if `dnf` exists: - `sudo dnf install -y git` - Else if `yum` exists: - `sudo yum install -y git` - Else if `pacman` exists: - `sudo pacman -S --noconfirm git` - Else if `zypper` exists: - `sudo zypper install -y git` - Else if `apk` exists: - `sudo apk add git` - Else if macOS and `xcode-select` exists: - `xcode-select --install` (this may prompt the user) - Else: - Tell the user you couldn’t auto-install git on this OS and show the failing detection output. Re-check: - `git --version` Only notify the user if install failed. ### 1B) Ensure cron/crontab is available (best-effort auto-install) Check: - `command -v crontab` If missing, attempt install: - If `apt-get` exists: - `sudo apt-get update && sudo apt-get install -y cron` - `sudo systemctl enable --now cron || sudo service cron start || true` - Else if `dnf` exists: - `sudo dnf install -y cronie` - `sudo systemctl enable --now crond || true` - Else if `yum` exists: - `sudo yum install -y cronie` - `sudo systemctl enable --now crond || true` - Else if `pacman` exists: - `sudo pacman -S --noconfirm cronie` - `sudo systemctl enable --now cronie || true` - Else if `apk` exists: - `sudo apk add dcron` - `sudo rc-update add dcron default || true` - `sudo rc-service dcron start || true` - Else: - If you can’t install, tell the user cron is required for scheduling. Re-check: - `command -v crontab` --- ## Step 2: Ensure GitHub CLI (`gh`) is installed (auto-install) Check: - `gh --version` If missing, install: - If `brew` exists: - `brew install gh` - Else if `apt-get` exists (official GitHub CLI packages; preferred): - Install using the official apt repo steps: - `(type -p wget >/dev/null || (sudo apt-get update && sudo apt-get install -y wget))` - `sudo mkdir -p -m 755 /etc/apt/keyrings` - `out=$(mktemp) && wget -nv -O"$out" https://cli.github.com/packages/githubcli-archive-keyring.gpg` - `cat "$out" | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null` - `sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg` - `sudo mkdir -p -m 755 /etc/apt/sources.list.d` - `echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null` - `sudo apt-get update && sudo apt-get install -y gh` - Else if `dnf` exists: - `sudo dnf install -y 'dnf-command(config-manager)' || sudo dnf install -y dnf5-plugins || true` - `sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo || sudo dnf config-manager addrepo --from-repofile=https://cli.github.com/packages/rpm/gh-cli.repo || true` - `sudo dnf install -y gh --repo gh-cli || sudo dnf install -y gh || true` - Else if `yum` exists: - `type -p yum-config-manager >/dev/null || sudo yum install -y yum-utils` - `sudo yum-config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo` - `sudo yum install -y gh` - Else if `zypper` exists: - `sudo zypper addrepo https://cli.github.com/packages/rpm/gh-cli.repo || true` - `sudo zypper ref` - `sudo zypper install -y gh` - Else if `pacman` exists: - `sudo pacman -S --noconfirm github-cli` - Else if `apk` exists: - `sudo apk add github-cli` - Else: - Tell the user you can’t auto-install `gh` on this OS. Re-check: - `gh --version` Only notify the user if install failed. --- ## Step 3: Ensure the user is authenticated in `gh` (agent runs the flow) Check: - `gh auth status --hostname github.com` If NOT authenticated: 1. Run: - `gh auth login --hostname github.com --git-protocol https` 2. The terminal flow will show a one-time code and ask the user to authorize. - Tell the user to open **https://github.com/login/device** in their browser and enter the code shown in the terminal, then authorize. 3. After login: - `gh auth setup-git` 4. Verify again: - `gh auth status --hostname github.com` If auth fails, stop and report the exact terminal output. --- ## Step 4: Initialize git in the OpenClaw workspace and connect/create the repo Workspace dir (where you store SOUL.md, AGENTS.md, etc.): - Example (path might be different on your environment): `WORKSPACE_DIR="$HOME/.openclaw/workspace"` 1. Ensure the workspace exists: - `mkdir -p "$WORKSPACE_DIR"` - `cd "$WORKSPACE_DIR"` 2. Initialize repo if needed: - If `.git` does not exist: `git init` - `git branch -M main` 3. Configure a deterministic commit identity (local-only): - `git config user.name "gitclaw.ai"` - `git config user.email "gitclaw-bot@users.noreply.github.com"` 4. Determine the authenticated GitHub username (owner): - `OWNER="$(gh api user --jq .login)"` - (Do not print unless debugging is needed) 5. Repo name and visibility: - `REPO="<repo name from user>"` - Visibility: - `public` => `--public` - `private` => `--private` 6. Ensure there is at least one commit (required for first push/cron): - Create a tiny marker file if needed: - `test -f .gitclaw.keep || printf "gitclaw initialized: %s\n" "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" > .gitclaw.keep` - `git add -A` - `git commit -m "gitclaw: initial backup" || true` 7. Create or reuse the target repo: - If it exists: - `gh repo view "$OWNER/$REPO" >/dev/null 2>&1` - Set remote: - `REMOTE_URL="https://github.com/$OWNER/$REPO.git"` - If origin exists: `git remote set-url origin "$REMOTE_URL"` - Else: `git remote add origin "$REMOTE_URL"` - Try to fast-forward sync (avoid overwriting remote history): - `git fetch origin main || true` - `git merge --ff-only origin/main || true` - If it does NOT exist: - Create it non-interactively and connect it: - Public: - `gh repo create "$REPO" --public --confirm` - Private: - `gh repo create "$REPO" --private --confirm` - Set remote: - `REMOTE_URL="https://github.com/$OWNER/$REPO.git"` - `git remote add origin "$REMOTE_URL" || git remote set-url origin "$REMOTE_URL"` 8. Initial push: - `git push -u origin main` If push fails due to conflicts or non-fast-forward: - Do NOT force-push automatically. - Report the exact error and stop (user decision required). --- ## Step 5: Install deterministic backup script (NO AI / NO heartbeat) Create a folder outside the workspace: - `mkdir -p "$HOME/.openclaw/gitclaw"` Create this script EXACTLY: Path: - `$HOME/.openclaw/gitclaw/auto_backup.sh` Contents: ```bash #!/usr/bin/env bash set -euo pipefail # GitClaw deterministic backup (no AI) export PATH="/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:$PATH" WORKSPACE_DIR="${HOME}/.openclaw/workspace" STATE_DIR="${HOME}/.openclaw/gitclaw" LOG_FILE="${STATE_DIR}/backup.log" LOCK_DIR="${STATE_DIR}/lock" mkdir -p "${STATE_DIR}" timestamp() { date -u '+%Y-%m-%dT%H:%M:%SZ'; } # Simple lock to prevent overlapping runs if ! mkdir "${LOCK_DIR}" 2>/dev/null; then echo "$(timestamp) Skip: already running." >> "${LOG_FILE}" exit 0 fi trap 'rmdir "${LOCK_DIR}" >/dev/null 2>&1 || true' EXIT if ! command -v git >/dev/null 2>&1; then echo "$(timestamp) ERROR: git not found on PATH. Install git first." >> "${LOG_FILE}" exit 2 fi if [ ! -d "${WORKSPACE_DIR}/.git" ]; then echo "$(timestamp) ERROR: ${WORKSPACE_DIR} is not a git repo. Run GitClaw setup first." >> "${LOG_FILE}" exit 3 fi cd "${WORKSPACE_DIR}" # Stage everything git add -A # If nothing staged, exit quietly if git diff --cached --quiet; then echo "$(timestamp) No changes." >> "${LOG_FILE}" exit 0 fi # Commit + push git commit -m "gitclaw backup: $(timestamp)" >> "${LOG_FILE}" 2>&1 git push origin main >> "${LOG_FILE}" 2>&1 echo "$(timestamp) Backup OK." >> "${LOG_FILE}" ``` Write the script to: - `$HOME/.openclaw/gitclaw/auto_backup.sh` Then: - `chmod +x "$HOME/.openclaw/gitclaw/auto_backup.sh"` --- ## Step 6: Configure crontab (idempotent) Default schedule: hourly (`0 * * * *`). If user provided a different frequency, convert it to a cron expression. 1. Define: - `CRON_CMD="$HOME/.openclaw/gitclaw/auto_backup.sh"` - `CRON_LINE="0 * * * * $CRON_CMD"` 2. Install without duplicates: - `crontab -l 2>/dev/null | grep -F "$CRON_CMD" >/dev/null` - If not found, append: - `(crontab -l 2>/dev/null; echo "$CRON_LINE") | crontab -` 3. Confirm: - `crontab -l | grep -F "$CRON_CMD"` --- ## Step 7: Final validation 1. Run once: - `$HOME/.openclaw/gitclaw/auto_backup.sh` 2. Show the log: - `tail -n 50 "$HOME/.openclaw/gitclaw/backup.log" || true` 3. Tell the user: - Repo: `https://github.com/$OWNER/$REPO` - Schedule: hourly (or the chosen cadence) - Script path: `~/.openclaw/gitclaw/auto_backup.sh`