wordmove-ng 6.0.1 → 6.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f35d0da6f7b15e8f492351b76ea90e096fe73b5c94cf55d9e8f10a0e93eb3802
-  data.tar.gz: cebf5ecc1de41bf581c5b07cdf4446e87ead5b73c891393b60cfa7a6d702c14c
+  metadata.gz: 6b938b4ef6d1ed30ecf48f1cbe1d48ba2f1a2ef223247189a3da3a0c1b840238
+  data.tar.gz: a3ffcdb129f255a82a7257f7d50a9d7c8b56195fd7e8a169ff04cceed8216281
 SHA512:
-  metadata.gz: dcb6cddeb0d95335204a1a40b2f429573ec114d0cffc7375e16af0eec4d2201df92c9c8f2040e809c610933853a1e71cf116ff3b3525a22f25d6b4da26366ac5
-  data.tar.gz: 35b2e3a3b29fb0e2ca9d6c128781cc0ca2feaa758b8efa49eeb71402c0ff2e683cb3bfcbbb8bf5d54d0d172ffd524a09579c7794b6da5a3da8638dc725c0bd8e
+  metadata.gz: 7d8d9baa3cecea48ac16a2853c927695eb1ad865bc0df9efc01f5ba6d034e96afab4322eeae3da3b9a605584a5fe44ed4ff58c3995daea9d4b9f08de616720ac
+  data.tar.gz: 211ca5b52895d6fef092985a0bec08cd7bad97845c6579187699856e1d79339d510da596a60247bc3aa4296b1bdb7e85859cebbeda51a853b36335bdb86723b0

data/.github/workflows/release.yml

@@ -13,7 +13,10 @@
 #   - rubygems.org: pending trusted publisher for gem wordmove-ng, repository
 #     tekgnosis-net/wordmove-ng, workflow release.yml, environment release
 #   - GitHub: environment "release"; Actions setting "Allow GitHub Actions to
-#     create and approve pull requests" enabled (needed by release-please)
+#     create and approve pull requests" enabled; repository secret
+#     RELEASE_PLEASE_TOKEN holding a fine-grained PAT scoped to this repository
+#     with Contents and Pull requests read/write (so release PRs run the checks
+#     that branch protection requires)
 
 name: Release
 
@@ -37,9 +40,14 @@ jobs:
       release_created: ${{ steps.release.outputs.release_created }}
       tag_name: ${{ steps.release.outputs.tag_name }}
     steps:
+      # A fine-grained PAT (secret RELEASE_PLEASE_TOKEN, contents + pull-requests
+      # read/write) instead of the built-in token: PRs opened with the built-in
+      # token never trigger the Tests workflow, which the branch protection on
+      # master requires before a release PR can be merged.
       - uses: googleapis/release-please-action@v4
         id: release
         with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN || github.token }}
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json
 

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "6.0.1"
+  ".": "6.0.2"
 }

data/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to wordmove-ng are documented here. The project follows
 are listed at https://github.com/welaika/wordmove/releases; the kokiddp fork's changes
 between 5.2.2 and this project are summarised under 6.0.0.
 
+## [6.0.2](https://github.com/tekgnosis-net/wordmove-ng/compare/v6.0.1...v6.0.2) (2026-09-12)
+
+
+### Documentation
+
+* add cron automation guide and contrib/wordmove-sync.sh ([#4](https://github.com/tekgnosis-net/wordmove-ng/issues/4)) ([dbe3612](https://github.com/tekgnosis-net/wordmove-ng/commit/dbe36126976f9f5a0f0793208aed89bd5c7fc787))
+
 ## [6.0.1](https://github.com/tekgnosis-net/wordmove-ng/compare/v6.0.0...v6.0.1) (2026-09-09)
 
 

data/CLAUDE.md

@@ -103,7 +103,8 @@ Update the relevant page in the same commit as any user-facing behaviour change.
   `docs:`, `chore:`, `ci:`, `test:`, `refactor:`). release-please derives the version bump
   and CHANGELOG from them; never edit `lib/wordmove/version.rb` or `CHANGELOG.md` by hand.
   Releases are published to rubygems.org by `.github/workflows/release.yml` (trusted
-  publishing, no secrets).
+  publishing). `master` is protected for everyone including admins: branch, open a PR, let
+  the six `test` checks pass, merge. release-please needs the `RELEASE_PLEASE_TOKEN` secret.
 
 - Every shell fragment that includes user/config data goes through `Shellwords.escape`
   (or `Shellwords.split` for user-supplied option strings). Secrets must never appear in

data/README.md

@@ -246,12 +246,17 @@ production:
 File sync mirrors the source: files missing on the source are deleted on the destination.
 Put anything you need to keep in `exclude`, which is always relative to `wordpress_path`.
 
+Scheduled syncs from cron or CI work out of the box; `contrib/wordmove-sync.sh` handles the
+environment cron lacks (Ruby version manager, `PATH`, no agent, no TTY, overlap lock, logs).
+See [Automation and cron](https://tekgnosis-net.github.io/wordmove-ng/automation/).
+
 The documentation site has the full reference:
 [Configuration](https://tekgnosis-net.github.io/wordmove-ng/configuration/),
 [Usage and flags](https://tekgnosis-net.github.io/wordmove-ng/usage/),
 [Database sync](https://tekgnosis-net.github.io/wordmove-ng/database-sync/),
 [Hooks](https://tekgnosis-net.github.io/wordmove-ng/hooks/),
 [Multiple environments](https://tekgnosis-net.github.io/wordmove-ng/environments/),
+[Automation and cron](https://tekgnosis-net.github.io/wordmove-ng/automation/),
 [Troubleshooting](https://tekgnosis-net.github.io/wordmove-ng/troubleshooting/).
 
 ## Logging
@@ -333,6 +338,11 @@ One-time setup for a new maintainer or a fork:
 - In the GitHub repository settings create an environment named `release`, and under
   *Actions → General* enable "Allow GitHub Actions to create and approve pull requests"
   so release-please can open its PR.
+- Create a fine-grained personal access token scoped to this repository with *Contents* and
+  *Pull requests* set to read and write, and store it as the repository secret
+  `RELEASE_PLEASE_TOKEN`. Pull requests opened with the built-in Actions token never trigger
+  other workflows, so without it the release PR cannot satisfy the required `test` checks on
+  the protected `master` branch.
 
 ## Credits and licence
 

data/contrib/wordmove-sync.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+#
+# Run a wordmove-ng sync from cron (or any non interactive context).
+#
+# Copy this file somewhere in your PATH, adjust the settings block or override
+# the variables from the environment, then add a crontab entry such as
+#
+#   MAILTO=you@example.com
+#   30 2 * * * /usr/local/bin/wordmove-sync.sh
+#
+# Cron provides almost no environment: no rvm/rbenv shims, no ssh-agent, no TTY.
+# This script makes ruby and the peer tools findable, relies on a key that
+# needs no passphrase (see the docs page "Automation"), refuses to overlap
+# with a still-running sync, and writes a plain-text log per run.
+#
+# Test it the way cron will run it before trusting the schedule:
+#   env -i HOME=$HOME SHELL=/bin/bash PATH=/usr/bin:/bin /usr/local/bin/wordmove-sync.sh
+set -euo pipefail
+
+# ---- settings (override with environment variables) --------------------------
+SITE_DIR="${SITE_DIR:-/path/to/wordpress}"        # directory holding movefile.yml
+ENVIRONMENT="${ENVIRONMENT:-production}"          # remote environment (-e)
+ACTION="${ACTION:-pull}"                          # pull or push
+COMPONENTS="${COMPONENTS:---all --no-db}"         # component flags
+LOG_DIR="${LOG_DIR:-$HOME/log/wordmove}"
+KEEP_LOGS="${KEEP_LOGS:-30}"                      # how many run logs to keep
+RUBY_VERSION="${RUBY_VERSION:-}"                  # e.g. ruby-3.4.9 for rvm; empty = whatever is on PATH
+# -----------------------------------------------------------------------------
+
+case "$ACTION" in
+  pull|push) ;;
+  *) echo "ACTION must be pull or push, got '$ACTION'" >&2; exit 2 ;;
+esac
+
+# Ruby version managers are not loaded by cron.
+if [ -n "$RUBY_VERSION" ] && [ -s "$HOME/.rvm/scripts/rvm" ]; then
+  # shellcheck disable=SC1091
+  source "$HOME/.rvm/scripts/rvm"
+  rvm use "$RUBY_VERSION" >/dev/null
+elif [ -d "$HOME/.rbenv/shims" ]; then
+  export PATH="$HOME/.rbenv/shims:$PATH"
+fi
+
+# Peer tools wordmove-ng shells out to (ssh, rsync, mysqldump, wp, ...).
+export PATH="$HOME/bin:$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin:$PATH"
+export LC_ALL="${LC_ALL:-C.UTF-8}"
+
+command -v wordmove-ng >/dev/null || { echo "wordmove-ng not found in PATH" >&2; exit 2; }
+
+mkdir -p "$LOG_DIR"
+LOG="$LOG_DIR/${ENVIRONMENT}-$(date +%Y%m%d-%H%M%S).log"
+LOCK_FILE="${LOCK_FILE:-${TMPDIR:-/tmp}/wordmove-${ENVIRONMENT}.lock}"
+
+cd "$SITE_DIR"
+
+# Refuse to start while a previous run is still active.
+exec 9>"$LOCK_FILE"
+if ! flock -n 9; then
+  echo "$(date '+%F %T') previous run still active, skipping" >>"$LOG"
+  exit 0
+fi
+
+# The output is coloured regardless of TTY; strip the escape codes for the log.
+# shellcheck disable=SC2086  # COMPONENTS is a list of flags on purpose
+{
+  echo "== $(date '+%F %T') wordmove-ng $ACTION -e $ENVIRONMENT $COMPONENTS"
+  wordmove-ng "$ACTION" -e "$ENVIRONMENT" $COMPONENTS
+  echo "== $(date '+%F %T') finished, exit 0"
+} 2>&1 | sed 's/\x1b\[[0-9;]*m//g' >>"$LOG"
+
+# Rotate logs: keep the newest KEEP_LOGS files for this environment.
+find "$LOG_DIR" -maxdepth 1 -name "${ENVIRONMENT}-*.log" -printf '%T@ %p\n' \
+  | sort -rn | tail -n +"$((KEEP_LOGS + 1))" | cut -d' ' -f2- | xargs -r rm -f

data/docs/automation.md

@@ -0,0 +1,166 @@
+---
+title: Automation and cron
+nav_order: 10
+---
+
+# Automation and cron
+{: .no_toc }
+
+wordmove-ng never prompts, so it runs unattended: from cron, systemd timers, CI runners or deploy scripts. What differs from an interactive shell is the environment, and this page covers exactly that.
+
+1. TOC
+{:toc}
+
+## What cron does not give you
+
+- **No version manager.** rvm and rbenv shims are loaded by your shell profile, which cron does not read. `ruby`, `gem` executables and the gemset must be made visible explicitly.
+- **No ssh-agent.** There is no agent socket, so the SSH key must be usable without one: a key without a passphrase, or a key held by a system agent you start yourself.
+- **A minimal `PATH`.** `rsync`, `mysqldump`, `wp` and friends installed under `~/bin`, `/usr/local/bin` or a MAMP/Local directory are not found unless you add them.
+- **No TTY.** Output is still coloured; strip the escape codes when logging to a file.
+
+`wordmove-ng` itself is already safe here: SSH runs with `BatchMode=yes`, a failing key authentication is an error rather than a hanging prompt, prerequisites are checked before any side effect, and every failure exits non-zero.
+
+## Prepare once
+
+### A key cron can use
+{: .no_toc }
+
+Create a dedicated key without a passphrase and restrict what it can do on the server:
+
+```bash
+ssh-keygen -t ed25519 -N '' -f ~/.ssh/wordmove_cron_ed25519 -C wordmove-cron
+```
+
+In the remote `~/.ssh/authorized_keys`, prefix the public key with restrictions:
+
+```
+from="203.0.113.10",no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-ed25519 AAAA… wordmove-cron
+```
+
+Then point the movefile at a `~/.ssh/config` entry that names the key, so the movefile stays free of machine-specific paths:
+
+```
+Host prod-wordmove
+  Hostname example.com
+  User deploy
+  IdentityFile ~/.ssh/wordmove_cron_ed25519
+  IdentitiesOnly yes
+```
+
+```yaml
+production:
+  ssh:
+    host: prod-wordmove
+```
+
+### Secrets in `.env`
+{: .no_toc }
+
+Keep database passwords in a `.env` file next to `movefile.yml` with mode `600`, referenced as `<%= ENV['PROD_DB_PASS'] %>`. Never put them in the crontab, which is readable by other means and shows up in logs.
+
+### Guard rails in the movefile
+{: .no_toc }
+
+A scheduled job should not be able to do more than it was written for, even if the script is edited later. Use `forbid`:
+
+```yaml
+production:
+  forbid:
+    push:
+      db: true          # a file-sync job must never push the database
+      uploads: true
+```
+
+and `exclude` for anything that lives on one side only, because syncs **mirror** the source: a scheduled `pull --all` overwrites local changes, a scheduled `push --all` overwrites uploads added through the WordPress admin since the last run.
+
+## The script
+
+The repository ships [`contrib/wordmove-sync.sh`](https://github.com/tekgnosis-net/wordmove-ng/blob/master/contrib/wordmove-sync.sh). Copy it to `/usr/local/bin/`, adjust the settings block at the top or override the variables from the environment. It
+
+- loads rvm (`RUBY_VERSION=ruby-3.4.9`) or rbenv, and extends `PATH` for the peer tools;
+- refuses to start while a previous run holds the lock, so overlapping runs cannot happen;
+- writes one plain-text log per run to `~/log/wordmove/` with colour codes stripped, and keeps the last 30;
+- exits non-zero when the sync fails, so cron mails you when `MAILTO` is set.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+SITE_DIR="${SITE_DIR:-/path/to/wordpress}"        # directory holding movefile.yml
+ENVIRONMENT="${ENVIRONMENT:-production}"
+ACTION="${ACTION:-pull}"                          # pull or push
+COMPONENTS="${COMPONENTS:---all --no-db}"
+LOG_DIR="${LOG_DIR:-$HOME/log/wordmove}"
+RUBY_VERSION="${RUBY_VERSION:-}"                  # e.g. ruby-3.4.9 for rvm
+
+if [ -n "$RUBY_VERSION" ] && [ -s "$HOME/.rvm/scripts/rvm" ]; then
+  source "$HOME/.rvm/scripts/rvm"; rvm use "$RUBY_VERSION" >/dev/null
+elif [ -d "$HOME/.rbenv/shims" ]; then
+  export PATH="$HOME/.rbenv/shims:$PATH"
+fi
+export PATH="$HOME/bin:$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin:$PATH"
+
+mkdir -p "$LOG_DIR"
+LOG="$LOG_DIR/${ENVIRONMENT}-$(date +%Y%m%d-%H%M%S).log"
+cd "$SITE_DIR"
+
+exec 9>"/tmp/wordmove-${ENVIRONMENT}.lock"
+flock -n 9 || { echo "$(date '+%F %T') previous run still active" >>"$LOG"; exit 0; }
+
+{
+  echo "== $(date '+%F %T') wordmove-ng $ACTION -e $ENVIRONMENT $COMPONENTS"
+  wordmove-ng "$ACTION" -e "$ENVIRONMENT" $COMPONENTS
+  echo "== $(date '+%F %T') finished"
+} 2>&1 | sed 's/\x1b\[[0-9;]*m//g' >>"$LOG"
+```
+
+(abridged; the shipped file adds validation and log rotation)
+
+## Crontab
+
+Nightly at 02:30 local time, with failures mailed to you:
+
+```
+MAILTO=you@example.com
+30 2 * * * SITE_DIR=/home/me/sites/example RUBY_VERSION=ruby-3.4.9 /usr/local/bin/wordmove-sync.sh
+```
+
+Several sites or environments are just several lines with different variables. Stagger them so their windows do not overlap on the same remote.
+
+## Test it the way cron runs it
+
+A missing `PATH` entry or an unreadable key only shows up under cron's empty environment, so reproduce that before trusting the schedule:
+
+```bash
+env -i HOME=$HOME SHELL=/bin/bash PATH=/usr/bin:/bin \
+  SITE_DIR=/home/me/sites/example RUBY_VERSION=ruby-3.4.9 /usr/local/bin/wordmove-sync.sh
+echo "exit $?"
+tail -n 40 ~/log/wordmove/production-*.log
+```
+
+Running `wordmove-ng doctor` under the same `env -i` prefix is the quickest check that the key and every tool resolve without an agent.
+
+## Database jobs
+
+For a scheduled database push enable `global.maintenance_mode` so the seconds between import and `wp search-replace` show visitors the maintenance page instead of the wrong URLs. Scheduled database pulls are the common case (a nightly copy of production for development) and need nothing special; each run leaves a `local-backup-<timestamp>.sql.gz` in `wp-content/`, so prune those occasionally.
+
+## systemd timer instead of cron
+
+The same script works as a `oneshot` service:
+
+```ini
+# ~/.config/systemd/user/wordmove-sync.service
+[Service]
+Type=oneshot
+Environment=SITE_DIR=/home/me/sites/example RUBY_VERSION=ruby-3.4.9
+ExecStart=/usr/local/bin/wordmove-sync.sh
+
+# ~/.config/systemd/user/wordmove-sync.timer
+[Timer]
+OnCalendar=*-*-* 02:30:00
+Persistent=true
+[Install]
+WantedBy=timers.target
+```
+
+`systemctl --user enable --now wordmove-sync.timer`, and `journalctl --user -u wordmove-sync` for the output. Enable lingering (`loginctl enable-linger $USER`) so user timers run without a login session.

data/docs/contributing.md

@@ -1,6 +1,6 @@
 ---
 title: Contributing and releasing
-nav_order: 11
+nav_order: 12
 ---
 
 # Contributing and releasing
@@ -42,6 +42,8 @@ Releases are automated by [release-please](https://github.com/googleapis/release
 
 Pushing a `v*` tag by hand at the head of `master` triggers the same publish job.
 
+`master` is protected: changes land through pull requests whose `test` checks pass, and the rules apply to administrators too. release-please opens its PR with a fine-grained personal access token (secret `RELEASE_PLEASE_TOKEN`) because PRs opened with the built-in Actions token never trigger the checks.
+
 ## This documentation
 
 The site is built from the `docs/` folder on `master` with Jekyll and the just-the-docs theme by `.github/workflows/pages.yml`. Preview locally with

data/docs/index.md

@@ -51,6 +51,7 @@ It is the maintained, independent successor of [Wordmove](https://github.com/wel
 | know what each flag does | [Usage and flags]({{ site.baseurl }}/usage/) |
 | know exactly what happens to my database | [Database sync]({{ site.baseurl }}/database-sync/) |
 | run commands before or after a deploy | [Hooks]({{ site.baseurl }}/hooks/) |
+| schedule syncs from cron or CI | [Automation and cron]({{ site.baseurl }}/automation/) |
 | fix a problem | [Troubleshooting]({{ site.baseurl }}/troubleshooting/) |
 
 ## Credits

data/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 ---
 title: Troubleshooting
-nav_order: 10
+nav_order: 11
 ---
 
 # Troubleshooting and FAQ

data/docs/usage.md

@@ -109,6 +109,10 @@ exclude:
 
 The same works for themes and any other folder.
 
+## Running unattended
+
+wordmove-ng never prompts, so it can run from cron, systemd timers or CI. The environment those give you is the only difference; see [Automation and cron]({{ site.baseurl }}/automation/) for a ready-made script and the SSH key setup.
+
 ## Rsync options in a continuous delivery context
 
 The default rsync flags are `-rlpt`. On a CI runner every file is freshly checked out, so `--times` triggers a full transfer every time and `--perms` may not be what you want:

data/lib/wordmove/version.rb

@@ -1,3 +1,3 @@
 module Wordmove
-  VERSION = "6.0.1".freeze
+  VERSION = "6.0.2".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wordmove-ng
 version: !ruby/object:Gem::Version
-  version: 6.0.1
+  version: 6.0.2
 platform: ruby
 authors:
 - Kumar
@@ -251,11 +251,13 @@ files:
 - bin/setup
 - bin/thor
 - bin/wordmove-ng
+- contrib/wordmove-sync.sh
 - deploy/deploy.sh
 - docs/Gemfile
 - docs/README.md
 - docs/_config.yml
 - docs/assets/images/wordmove-ng.png
+- docs/automation.md
 - docs/configuration.md
 - docs/contributing.md
 - docs/database-sync.md