eleven / ocho Public

docs: sync the planet-scale guide to elevenmessenger/website automatically (#886)

James wants the guide's source to stay next to the code it documents
(docs/planet-scale-guide/), while also being reachable on the main public
site, not just home.elevenmessenger.com. The website is a separate repo
(Eleventy, deploys via its own GitHub Actions workflow on push to main), so
a new workflow here copies the guide into that repo's src/infrastructure/
(Eleventy passthrough-copies it unmodified) whenever it changes on main,
and pushes — which triggers the website's existing deploy automatically.
No manual step, and no second copy of the guide to keep in sync by hand.

Needs a one-time setup: a fine-grained PAT scoped to ONLY
elevenmessenger/website (Contents: read/write, nothing else), stored as the
WEBSITE_REPO_TOKEN secret on this repo. Documented in
docs/planet-scale-guide/README.html. Until it's set, the workflow logs a
warning and does nothing else — never fails loudly, never partially syncs.

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

James Adam 3 months ago 69f06f8df356c8f44267fda978feda6cbc5fb628 parent 1f3d98d

2 files changed, +89 −0

.github/workflows/sync-guide-to-website.yml +69 −0
docs/planet-scale-guide/README.html +20 −0

diff --git a/.github/workflows/sync-guide-to-website.yml b/.github/workflows/sync-guide-to-website.yml

new file mode 100644

index 0000000..2069205

--- /dev/null

+++ b/.github/workflows/sync-guide-to-website.yml

@@ -0,0 +1,69 @@

+name: Sync planet-scale guide to the website

+# The guide's source lives here (docs/planet-scale-guide/ — see its own

+# README.html), since keeping it next to the code it documents is what keeps

+# it honest. This mirrors it into the public elevenmessenger/website repo

+# (src/infrastructure/, passthrough-copied by Eleventy — see .eleventy.js

+# there) so it's reachable at elevenmessenger.com/infrastructure/ too,

+# without ever duplicating the source by hand. A push to website's main

+# branch triggers its own existing deploy.yml automatically.

+on:

+ push:

+ branches: [main]

+ paths:

+ - 'docs/planet-scale-guide/**'

+ workflow_dispatch:

+concurrency:

+ group: sync-guide-to-website

+ cancel-in-progress: false

+jobs:

+ sync:

+ runs-on: ubuntu-latest

+ steps:

+ - name: Checkout the guide source

+ uses: actions/checkout@v4

+ with:

+ sparse-checkout: docs/planet-scale-guide

+ sparse-checkout-cone-mode: true

+ - name: Check for the website repo token

+ id: check-token

+ run: |

+ if [ -z "${{ secrets.WEBSITE_REPO_TOKEN }}" ]; then

+ echo "skip=true" >> "$GITHUB_OUTPUT"

+ echo "::warning::WEBSITE_REPO_TOKEN secret not set — skipping guide sync. See docs/planet-scale-guide/README.html § Publishing to elevenmessenger.com."

+ else

+ echo "skip=false" >> "$GITHUB_OUTPUT"

+ fi

+ - name: Checkout elevenmessenger/website

+ if: steps.check-token.outputs.skip != 'true'

+ uses: actions/checkout@v4

+ with:

+ repository: elevenmessenger/website

+ token: ${{ secrets.WEBSITE_REPO_TOKEN }}

+ path: website

+ - name: Copy the guide into website's passthrough directory

+ if: steps.check-token.outputs.skip != 'true'

+ run: |

+ rm -rf website/src/infrastructure

+ mkdir -p website/src/infrastructure

+ cp -r docs/planet-scale-guide/* website/src/infrastructure/

+ - name: Commit and push if the guide changed

+ if: steps.check-token.outputs.skip != 'true'

+ working-directory: website

+ run: |

+ git config user.name "github-actions[bot]"

+ git config user.email "github-actions[bot]@users.noreply.github.com"

+ git add src/infrastructure

+ if git diff --cached --quiet; then

+ echo "No changes to the guide — nothing to sync."

+ else

+ git commit -m "docs: sync planet-scale guide from elevenmessenger/messenger@${GITHUB_SHA::7}"

+ git push

+ fi

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

index f04e196..2b539d5 100644

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

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

@@ -60,6 +60,26 @@ 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.

+</div>

</div>

</main>

</div>