Document lessons from the first live auto-deploy - #49
Merged
Conversation
Four updates to docs/deployment.md based on what actually tripped during the v0.7.0 rollout: 1. Fix the smoke-test section's v0.0.0 example: v0.0.0 passes the regex (zeros are digits), so it is not a negative-path test. Use v1.0 as the canonical bad-shape example and list other valid rejection cases. 2. Add a "Tailscale prerequisites (admin console)" subsection before the on-server setup, covering the three things that live only in the admin console and are silently required: MagicDNS enablement, a non-empty tagOwners entry for tag:ci, and an ACL grant letting tag:ci reach the server on port 22. 3. Add a bootstrap prerequisite note to the on-server setup: step 3 installs the entry stub *from* /opt/ephemera/scripts/deploy/, so that path must already exist before step 3 can run. Deployments predating the auto-deploy infra need one manual checkout first. 4. Rename the "Failure & rollback" subsection to "When a CI run fails" and expand it with a diagnostic recipe: journalctl -t ephemera-deploy + systemctl status on the server, gh run view/rerun on the laptop, and the specific retry-after-manual- checkout pattern for the bootstrap chicken-and-egg. Split the actual rollback instructions into their own "Rollback" subsection for discoverability. No code changes; no behavior changes. All additions are about making the existing pipeline easier to stand up and recover without the manual steps that were needed today. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Four updates to
docs/deployment.mdbased on what actually tripped during the first live auto-deploy (v0.7.0):v0.0.0smoke-test claim.v0.0.0actually passes the regex^v[0-9]+\.[0-9]+\.[0-9]+$(zeros are digits), so the docs' "expect rejection" guidance was wrong. Switched tov1.0as the canonical negative-shape example and listed other valid rejection inputs.tagOwnersentry fortag:ci, and an ACL grant lettingtag:cireach the server's port 22 (only needed on locked-down tailnets; default allow-all already covers it)./opt/ephemera/scripts/deploy/ephemera-deploy-entry, so that path must already exist on disk before step 3. If the current deploy predates the auto-deploy infrastructure, one manual checkout is required first. Added a one-paragraph preface at the top of "One-time server setup".journalctl -t ephemera-deployon the server,gh run view --log-failedon the laptop,gh run rerunfor transient issues), with a callout for the specific bootstrap-chicken-and-egg retry pattern. Rollback split into its own subsection for discoverability.Out of scope
DEPLOYMENT.mdupdates for the same lessons (the runbook at repo root, .gitignored) — applied directly, not in this PR.deploy.sh, the entry stub, or the workflow — the one code fix from this rollout already shipped in PR Fix deploy.sh cwd + correct sudoers subject in docs #48.Test plan
ssh deploy@<host> v1.0returns the "does not match" line + exit 2.