eleven / messenger Public

docs: guide publishes via local build now, not GitHub Actions (#1080)

The website (elevenmessenger.com) moved off GitHub Actions — it builds locally
and serves from a gh-pages branch — so the guide's own 'Publishing' section and
the sync script were describing a pipeline that no longer runs.

- planet-scale-guide/README.html § Publishing: rewrite as the two-step local
  flow (tools/sync-guide-to-website.sh -> the website repo's ./deploy.sh); drop
  the WEBSITE_REPO_TOKEN setup and the retired home.elevenmessenger.com mirror;
  a 'why local, not Actions' panel.
- tools/sync-guide-to-website.sh: it is the normal step-1 sync now (not an
  Actions fallback); final message points at ./deploy.sh instead of the disabled
  deploy workflow.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Paul Campbell 3 months ago 76315b97a33ec6edcb8a27227a3345515f8b0f58 parent 6758369

2 files changed, +20 −28

docs/planet-scale-guide/README.html +11 −19
tools/sync-guide-to-website.sh +9 −9

diff --git a/docs/planet-scale-guide/README.html b/docs/planet-scale-guide/README.html

index 7c6458f..5d2d13f 100644

--- a/docs/planet-scale-guide/README.html

+++ b/docs/planet-scale-guide/README.html

@@ -60,26 +60,18 @@ open docs/planet-scale-guide/index.html # macOS; or any static file s

<h2 id="authorship">Authorship marking</h2>

Per the repository’s authorship convention (<code>CLAUDE.md</code>), these pages were written by an LLM and carry the visible 🤖 marker in each page’s eyebrow. A human who substantially rewrites a page should remove the marker from that page (or add a person marker to certify it); an LLM editing further keeps it.

-<h2 id="publishing">Publishing to home.elevenmessenger.com and elevenmessenger.com</h2>

-The guide is reachable in two places, and this directory is the only source for both — nothing is ever hand-copied or edited in place at the destination:

-<ul>

- <li><code>home.elevenmessenger.com/infrastructure/</code> — served straight from disk by the home server (<code>home/main.go</code>’s <code>serveInfrastructure</code>). A deploy step <code>scp -r</code>s this directory onto the box and sets <code>LCHAT_HOME_INFRASTRUCTURE_DIR</code>; see <code>home/README.md</code> § Optional: serving the planet-scale guide.</li>

- <li><code>elevenmessenger.com/infrastructure/</code> — mirrored automatically into the public <code>elevenmessenger/website</code> repo (a separate, Eleventy-built static site) by <code>.github/workflows/sync-guide-to-website.yml</code>: any push to <code>main</code> that touches this directory copies it into that repo’s <code>src/infrastructure/</code> (Eleventy passthrough-copies it unmodified — see its <code>.eleventy.js</code>) and pushes, which triggers that repo’s own existing deploy workflow. No manual step, and no separate copy of the guide to keep in sync by hand.</li>

-</ul>

-<div class="warn">

- One-time setup: the website repo token

- The sync workflow needs write access to the public <code>elevenmessenger/website</code> repo, granted via a fine-grained GitHub personal access token stored as a secret in this repo (<code>messenger</code>), named <code>WEBSITE_REPO_TOKEN</code>. To create it:

- <ol class="procedure">

- <li>Mint the token.

- GitHub → profile photo → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token. Set Resource owner to the <code>elevenmessenger</code> organization, Repository access to Only select repositories → <code>elevenmessenger/website</code> (and no other repository), and under Permissions → Repository permissions set Contents to Read and write — leave every other permission at its default (No access). Give it an expiration and a name that says what it’s for (e.g. “messenger guide sync”).</li>

- <li>Add it as a secret on the <code>messenger</code> repo.

- On <code>github.com/elevenmessenger/messenger</code>: Settings → Secrets and variables → Actions → New repository secret. Name: <code>WEBSITE_REPO_TOKEN</code>. Value: the token from step 1.</li>

- <li>Run the sync once by hand.

- Actions tab → Sync planet-scale guide to the website → Run workflow (it also has a <code>workflow_dispatch</code> trigger for exactly this) — seeds <code>website</code>’s <code>src/infrastructure/</code> for the first time. Every subsequent guide change on <code>main</code> syncs automatically.</li>

- </ol>

- Until the secret is set, the workflow runs, logs a warning, and does nothing else — it never fails loudly and never risks a partial or broken sync.

+<h2 id="publishing">Publishing to elevenmessenger.com</h2>

+The guide is published to <code>elevenmessenger.com/infrastructure/</code>, and this directory is the only source — nothing is ever hand-edited at the destination. Publishing is a local build, no GitHub Actions involved, in two steps:

+<ol class="procedure">

+ <li>Mirror this directory into the website repo.

+ Run <code>tools/sync-guide-to-website.sh <path-to-a-local-checkout-of-elevenmessenger/website></code>. It copies this directory into that separate, public repo’s <code>src/infrastructure/</code> (Eleventy passthrough-copies it to <code>/infrastructure/</code> unmodified — see that repo’s <code>.eleventy.js</code>), commits, and pushes the website’s <code>main</code>. It uses your own git credentials — no token to set up.</li>

+ <li>Build and publish the website.

+ In that website checkout, run <code>./deploy.sh</code>: it builds the Eleventy site and force-pushes the output to the <code>gh-pages</code> branch, which GitHub Pages serves directly (deploy-from-a-branch). The custom domain and HTTPS ride along inside the build; live within about a minute. See the website repo’s <code>README.md</code> § Deploy.</li>

+</ol>

+<div class="why">

+ Why a local build, not a GitHub Action

+ This used to be automatic: a push to <code>main</code> touching this directory triggered <code>.github/workflows/sync-guide-to-website.yml</code>, which synced and deployed through the website’s own workflow. Both are now disabled — the project moved off GitHub Actions entirely (every binary already builds locally, and Actions was only ever publishing this site). The workflow files are kept in their trees, disabled, as the record of that approach; re-enabling them and flipping the website’s Pages source back to workflow-build is how you would restore auto-publish. (An earlier second copy served at <code>home.elevenmessenger.com/infrastructure/</code> is being retired.)

</div>

-<code>tools/sync-guide-to-website.sh <path-to-a-local-checkout-of-website></code> does the same copy-commit-push by hand, using your own git credentials instead of the token — useful when Actions can’t run (a billing/spending-limit block, say) or to try a guide change before merging it.

</div>

</main>

diff --git a/tools/sync-guide-to-website.sh b/tools/sync-guide-to-website.sh

index 0e1e4f6..87fa6b3 100755

--- a/tools/sync-guide-to-website.sh

+++ b/tools/sync-guide-to-website.sh

@@ -1,13 +1,13 @@

#!/usr/bin/env sh

-# Manual/local fallback for .github/workflows/sync-guide-to-website.yml —

-# mirrors docs/planet-scale-guide/ into elevenmessenger/website's

-# src/infrastructure/ (Eleventy passthrough-copies it to /infrastructure/

-# unmodified — see that repo's .eleventy.js), commits, and pushes.

+# Step 1 of publishing the guide to elevenmessenger.com — mirrors

+# docs/planet-scale-guide/ into elevenmessenger/website's src/infrastructure/

+# (Eleventy passthrough-copies it to /infrastructure/ unmodified — see that

+# repo's .eleventy.js), commits, and pushes the website's main.

-# The GitHub Actions workflow does this automatically on every push to main;

-# use this script when Actions can't run (e.g. a billing/spending-limit

-# block) or to test the sync before merging a guide change. Unlike the

-# workflow, this needs no WEBSITE_REPO_TOKEN — it uses your own local git

+# The old GitHub Actions auto-sync (.github/workflows/sync-guide-to-website.yml)

+# is DISABLED — the project builds the site locally now — so this is the normal

+# path, not a fallback. After it pushes, run ./deploy.sh in the website checkout

+# to build and publish (step 2). It needs no token: it uses your own local git

# credentials, exactly like pushing any other change by hand.

# ./tools/sync-guide-to-website.sh <path-to-a-local-checkout-of-website>

@@ -41,4 +41,4 @@ if git diff --cached --quiet; then

git commit -m "docs: sync planet-scale guide from elevenmessenger/messenger@$(git -C "$REPO_ROOT" rev-parse --short HEAD)"

git push

-echo "Pushed — elevenmessenger/website's own deploy workflow will publish it shortly."

+echo "Pushed website main. Now run ./deploy.sh in $WEBSITE_DIR to build + publish (no Actions)."