From 3738627a89b976e43322c5f44f011f3dccd83579 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 18:38:24 +0000 Subject: [PATCH] Publish manual: accept a fine-grained token as well as a deploy key The Docs repository checkout takes secrets.DOCS_PUBLISH_TOKEN (falling back to the default token, which cannot push) next to the deploy key, so the one-time setup can be done entirely on the GitHub website. The README and the release page describe both routes. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01QcYr11a5B65kS64MagbgF1 --- .github/workflows/docs-publish.yml | 7 ++++-- documentation-site/README.md | 22 +++++++++++++++---- .../docs/contributing/release.md | 6 ++--- 3 files changed, 26 insertions(+), 9 deletions(-) diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml index 21aada0..f5596ea 100644 --- a/.github/workflows/docs-publish.yml +++ b/.github/workflows/docs-publish.yml @@ -1,7 +1,7 @@ # Publishes the manual in documentation-site/ to 76cb/OpenTag-Station-Docs, whose own workflow # builds and deploys GitHub Pages. Runs on every merge to main that changes the manual, pre-release -# versions included. One-time setup (deploy key and the DOCS_DEPLOY_KEY secret) is described in -# documentation-site/README.md under "Publish". +# versions included. One-time setup, either a fine-grained token (secret DOCS_PUBLISH_TOKEN) or a +# deploy key (secret DOCS_DEPLOY_KEY), is described in documentation-site/README.md under "Publish". name: Publish manual on: @@ -44,6 +44,9 @@ jobs: ref: main path: docs-repo fetch-depth: 0 + # A deploy key wins when both secrets exist; without either, the default token can + # read the public repository but the push below is refused. + token: ${{ secrets.DOCS_PUBLISH_TOKEN || github.token }} ssh-key: ${{ secrets.DOCS_DEPLOY_KEY }} persist-credentials: true # --delete removes manual files that no longer exist; the Docs repository keeps its own diff --git a/documentation-site/README.md b/documentation-site/README.md index 39705a3..0d27152 100644 --- a/documentation-site/README.md +++ b/documentation-site/README.md @@ -67,14 +67,28 @@ python tools/export_docs.py --output The export stamps the firmware commit and version into `firmware.json`. -One-time setup, needed before the first run: +One-time setup, needed before the first run. Either credential works; a deploy key is used when +both exist. + +Fine-grained token (needs only the GitHub website): + +1. On github.com, open your profile → Settings → Developer settings → Personal access tokens → + Fine-grained tokens → **Generate new token**. Resource owner `76cb`, repository access + **Only select repositories** → `OpenTag-Station-Docs`, repository permission **Contents: + Read and write**. Choose the expiration you want; the workflow fails with `403` once it + expires, and a new token goes into the same secret. +2. On `76cb/OpenTag-Station`, add the token as the repository secret `DOCS_PUBLISH_TOKEN` + (Settings → Secrets and variables → Actions → New repository secret). + +Deploy key (needs a computer with `ssh-keygen`): 1. Generate a key pair: `ssh-keygen -t ed25519 -N "" -f docs-deploy-key`. 2. On `76cb/OpenTag-Station-Docs`, add `docs-deploy-key.pub` as a deploy key with write access (Settings → Deploy keys → Add deploy key, tick **Allow write access**). 3. On `76cb/OpenTag-Station`, add the private key `docs-deploy-key` as the repository secret - `DOCS_DEPLOY_KEY` (Settings → Secrets and variables → Actions → New repository secret). -4. Run the workflow once by hand: Actions → **Publish manual** → **Run workflow**. This first run - brings the Docs repository up to date. + `DOCS_DEPLOY_KEY`. + +Then run the workflow once by hand: Actions → **Publish manual** → **Run workflow**. This first +run brings the Docs repository up to date. The manual is under the firmware's [PolyForm Noncommercial license](LICENSE.md). diff --git a/documentation-site/docs/contributing/release.md b/documentation-site/docs/contributing/release.md index 16ce295..b7c78eb 100644 --- a/documentation-site/docs/contributing/release.md +++ b/documentation-site/docs/contributing/release.md @@ -69,7 +69,7 @@ and points links to repository files at that commit. To look at it without publi python tools/export_docs.py --output ``` -The workflow needs a deploy key once; the setup is in the +The workflow needs a credential for the Docs repository once, a fine-grained token in the secret +`DOCS_PUBLISH_TOKEN` or a deploy key in the secret `DOCS_DEPLOY_KEY`; the setup is in the [documentation-site README](https://github.com/76cb/OpenTag-Station/blob/main/documentation-site/README.md#publish). -Until the secret `DOCS_DEPLOY_KEY` exists, the workflow fails at the Docs repository checkout and -nothing is published. +Until one of them exists, the workflow fails at its push step with `403` and nothing is published.