Skip to content

Dotfiles Maintenance Runbook

This runbook captures recovery and release maintenance operations for this repository.

Signed History Recovery (February 19, 2026)

Purpose: Recover from strict signature enforcement failures caused by legacy/non-compliant commit history.

When to use:

  • Pushes are blocked by signature policy on historical commits.
  • Merge ancestry contains commits that can't be validated by the current principal/key policy.

Procedure:

  1. Create a backup ref for current main.
  2. Build a rewritten signed baseline commit from the current tree.
  3. Push the rewritten branch to remote.
  4. Temporarily allow force-push on main protections/rulesets.
  5. Force-update main to the rewritten signed baseline.
  6. Disable force-push again immediately.
  7. Re-run CI and verify required checks are green.
  8. Repoint the release tag/target as needed.

Verification commands:

git verify-commit HEAD
gh run list --workflow ci.yml --branch main --limit 1
gh release view v0.2.501 --json tagName,targetCommitish,url

Release Closeout Checklist

For every release update:

  1. main branch is clean and synced.
  2. CI is green on the release commit.
  3. Annotated release tag points to the intended commit.
  4. GitHub release target is correct (main or explicit commit).
  5. Branch protections/rulesets are restored to strict state.
  6. Local apply has completed:
CHEZMOI_SOURCE_DIR="$HOME/.dotfiles" ./bin/dot apply

Security Scan Guardrails

We prevent gitleaks historical-scan regressions with:

  • Shallow checkout (fetch-depth: 1, fetch-tags: false) in gitleaks jobs.
  • A workflow-dispatch guard script: tools/ci/guard-gitleaks-checkout.sh.

Manual verification:

bash tools/ci/guard-gitleaks-checkout.sh