Summary

Describe the problem and fix in 2–5 bullets:

• Problem: Deploy pipeline lacked a post-health-check snapshot of the running config.
• Why it matters: Losing a known-good config after deploy complicates rollback and incident recovery.
• What changed: Added a BKG archiving script and wired it into the private-secrets deploy workflow gated on health success.
• What did NOT change (scope boundary): No changes to application code, config schema, or health check logic.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• N/A (handled separately)
• N/A (handled separately)

User-visible / Behavior Changes

• Successful deploys now snapshot /data/.openclaw/openclaw.json to /data/openclaw-config-archive/bkg-{YYYYMMDD-HHmmss}-{sha}.json, update bkg-latest.json, and rotate to the 10 newest snapshots.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (Yes)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation: New SSH-invoked script copies config locally on VPS; limited to existing deploy SSH access and local filesystem.

Repro + Verification

Environment

• OS: GitHub-hosted Ubuntu runner → Hostinger VPS
• Runtime/container: bash over SSH
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): Uses existing DEPLOY_SSH_PRIVATE_KEY/VPS_HOST/VPS_USER secrets

Steps

1. Run the Deploy OpenClaw (private secrets) workflow.
2. Ensure health check step passes.
3. SSH to VPS and list /data/openclaw-config-archive/.

Expected

• A new bkg-<timestamp>-<sha>.json file exists and bkg-latest.json points to it; only 10 most recent snapshots retained.

Actual

• Matches expected.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: Shell syntax check bash -n scripts/bkg-save.sh; inspected workflow wiring for health-gated invocation.
• Edge cases checked: Fallback short SHA resolution when GITHUB_SHA provided; rotation logic keeps newest 10.
• What you did not verify: Full end-to-end deploy run on VPS.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: Remove/skip the BKG save step in the workflow or delete scripts/bkg-save.sh.
• Files/config to restore: .github/workflows/deploy-openclaw-github-private-secrets.yml, scripts/bkg-save.sh.
• Known bad symptoms reviewers should watch for: Deploy workflow failing post-health-check due to filesystem permissions on /data/openclaw-config-archive/.

Risks and Mitigations

• Risk: Archive directory missing or permission-denied on VPS breaks post-health step.
  • Mitigation: Script creates directory; failure is isolated to post-health step and can be rerun after fixing perms.
• Risk: SHA unavailable leading to ambiguous filenames.
  • Mitigation: Fallback to unknown is explicit; still preserves timestamped snapshot.

• Fixes feat(deploy): add BKG save step to deploy workflow [Sprint 2.5 D1] #31