Publish manual: accept a fine-grained token as well as a deploy key

.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

documentation-site/README.md

@@ -67,14 +67,28 @@ python tools/export_docs.py --output <empty-directory>
 
 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).

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 <empty-directory>
 ```
 
-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.