Correct Deploy-Site Script Inventory in Reusable-Workflows Doc

[ptr727]

Fixes #925.

The "Deploy-site" adoption section in docs/reusable-workflows.md assumed Blog's deploy carries three scripts (deploy/make-release.sh, deploy/prune-releases.sh, checks/check-live-urls.sh) folding 1:1 into the hub's three-mode deploy hook invocation (build/prune/verify). Blog's actual repo has no deploy/prune-releases.sh, retention is the tail of make-release.sh itself.

This works through the build/prune/verify split against Blog's real deploy/make-release.sh and checks/check-live-urls.sh, as the reference adoption the issue asked for:

• Corrects the script inventory (two scripts, not three).
• Clarifies where the hub-owned upload/flip sequence ends and the hook's own build mode begins, since make-release.sh's own swap-and-prune tail runs entirely against the ephemeral bundle-path scratch tree the hook is passed, never the live host.
• Explains why make-release.sh's internal hard-link-against-previous check is inert in CI (the scratch tree is empty every run, so it never has a previous release to compare against), and that the property that actually matters for the fleet's retention floor is the hub-owned remote --link-dest, which nothing currently asserts a floor on.
• Explains why prune mode is a no-op for Blog specifically: its deploy credential is a forced rsync command confined write-only, so it can't observe or delete the remote destination, and retention there is owned by a host-side timer instead (already recorded in Blog's own OPERATIONS.md), a pattern deploy-site-task.yml's own code comments already anticipate.
• Restores (corrected) the "why a hook, not a path convention" rationale the original prose made, since dropping the false three-script claim shouldn't drop that reasoning too.

Along the way this surfaced a real, separate gap: verify mode has no secret-forwarding path for a repo that gates a non-production environment behind a token, the way Blog's checks/check-live-urls.sh needs PANGOLIN_ACCESS_TOKEN_ID/PANGOLIN_ACCESS_TOKEN for its staging auth gate. deploy-site-task.yml declares no such secret today. That's tracked as a new open checklist item rather than solved here, since the shape (a named pair vs. a generic passthrough) is its own design decision.

No code changes, docs/reusable-workflows.md only. Verified locally: prose_lint.py --diff HEAD clean, repo_gate.py --check eol clean, markdownlint-cli2 clean.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Clarified deploy-site adoption guidance for build, prune, and verification workflows.
  • Documented environment-variable handling and responsibilities between the hub and site-specific hooks.
  • Added a rollout decision item regarding staging authentication secrets in deployment verification.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can commit Qodo's fix in one click with committable suggestions (GitHub & GitLab)

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

PR Summary by Qodo

Fix deploy-site adoption docs to match Blog’s real scripts and hook modes

📝 Documentation 🕐 20-40 Minutes

AI Description

• Correct deploy-site hook adoption docs to reflect Blog’s two-script layout.
• Clarify build/prune/verify boundaries between hub-owned deploy steps and repo hook behavior.
• Add a tracked note for missing verify-mode secret forwarding (Blog staging token pair).

Diagram

graph TD
  A["Site repo: deploy-site.yml"] --> B["Hub: deploy-site-task.yml"] --> C["Repo hook: deploy action"]
  C --> D["build: make-release.sh"] --> F[("Remote env root")]
  C --> E["verify: check-live-urls.sh"] --> F
  C --> G["prune: no-op (Blog)"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Implement verify-mode secret forwarding now

• ➕ Closes the documented gap immediately for Blog-like staging auth checks
• ➕ Reduces chance of adopters discovering missing secrets during first deploy
• ➖ Requires an API decision (named pair vs generic passthrough) and careful secret-scoping
• ➖ Expands PR scope beyond documentation, increasing review surface and risk

2. Define a generic secret passthrough interface for hooks

• ➕ Supports arbitrary per-site verify needs without hub changes per site
• ➕ Keeps deploy hook flexible as intended by the docs
• ➖ Higher risk of over-broad secret exposure if not tightly scoped
• ➖ Harder to document/validate consistently across repos

3. Keep docs-only fix (current PR) and track follow-up issue

• ➕ Corrects misleading guidance immediately with minimal risk
• ➕ Allows deliberate design work on secret-forwarding shape
• ➖ Adopters still blocked on verify-mode secrets until follow-up lands
• ➖ Requires readers to notice and follow the new checklist item

Recommendation: Keep this PR focused on correcting the documentation and explicitly tracking the verify-mode secret-forwarding gap. A follow-up change should decide between a minimal named secret pair interface versus a carefully-scoped generic passthrough, since that choice affects security and long-term hook flexibility.

Files changed (1) +10 / -1

Documentation (1) +10 / -1

reusable-workflows.mdCorrect deploy-site adoption guidance and add verify-secret gap checklist +10/-1

Correct deploy-site adoption guidance and add verify-secret gap checklist

• Updates the Deploy-site adoption section to match Blog’s actual two-script setup and explains how build/prune/verify map to hub-owned vs hook-owned responsibilities. Adds an explicit checklist item noting that verify mode currently lacks a secret-forwarding mechanism for staging token-gated checks (e.g., Blog’s Pangolin tokens).

docs/reusable-workflows.md

[Copilot]

🟢 Approval recommended

Documentation-only changes that are consistent with the current deploy-site-task.yml hook invocation contract and improve accuracy for the reference adoption case.

Pull request overview

Updates the reusable workflows documentation to align the Deploy-site adoption guidance with Blog's real deploy script layout, and to document the practical implications of the build/prune/verify hook split.

Changes:

• Correct Deploy-site reference inventory to two scripts (no deploy/prune-releases.sh) and walk through how Blog maps to build/prune/verify.
• Clarify the boundary between hub-owned upload/flip steps and repo-owned build mode behavior (bundle-path vs. live environment root).
• Add a tracked checklist item noting that verify mode currently has no secret-forwarding path for token-gated staging checks (e.g., Blog’s PANGOLIN token pair).

File summaries

File	Description
docs/reusable-workflows.md	Fixes Deploy-site adoption guidance to match Blog’s real script inventory and documents the current verify-mode secret-forwarding gap.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 154cf650-80df-4fde-a29c-8cae829e99dd

📥 Commits

Reviewing files that changed from the base of the PR and between ee719d4 and c71d9e9.

📒 Files selected for processing (1)

• docs/reusable-workflows.md

Included review availability: Your plan provides up to 10 included reviews per hour; 4 remain after this review.

---

📝 Walkthrough

Walkthrough

The deploy-site adoption documentation now describes Blog’s two-script hook workflow, mode-specific behavior, environment variables, hub-owned upload and activation steps, and the pending staging-auth secret handoff decision.

Changes

Deploy-site adoption guidance

Layer / File(s)	Summary
Deploy-site behavior and rollout contract docs/reusable-workflows.md	The guidance describes Blog’s required deploy hook, build, prune, and verify behavior. It documents environment-variable handling, the hub-owned upload and activation boundary, and the staging-auth secret handoff decision.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to c71d9

This documentation-only change corrects the Deploy-site script inventory and clarifies the documented workflow behavior. No actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the documentation change and matches the primary objective of correcting the Deploy-site script inventory.
Linked Issues check	✅ Passed	The documentation corrects Blog’s script inventory and explains the build, prune, and verify split, hub responsibilities, and credential constraints required by issue #925.
Out of Scope Changes check	✅ Passed	The PR changes only the targeted reusable-workflows documentation and adds details directly related to issue #925.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-925-deploy-site-docs

---

_{Comment @coderabbitai help to get the list of available commands.}