Carlos Florêncio
99 lines
4.3 KiB
Markdown
99 lines
4.3 KiB
Markdown
---
|
|
spec: docs/specs/ui/requirements/published-docs-preview-reliability.md
|
|
created: 2026-07-31
|
|
status: implemented
|
|
---
|
|
|
|
# Implementation Plan: Published Docs Preview Reliability
|
|
|
|
## Overview
|
|
|
|
The cited preview failed because `.github/workflows/notify-docs.yml` launches
|
|
landing without `GITHUB_TOKEN`; the renderer therefore consumes the hosted
|
|
runner IP's 60-request unauthenticated quota and rejects any generated fallback
|
|
community data. The repair first adds a static regression test for the workflow
|
|
permission boundary, then authenticates the build with a read-only job token
|
|
and moves preview-comment publication to a separate write-capable job.
|
|
|
|
## Root Cause
|
|
|
|
- The preview build step exports `KANDEV_DOCS_SOURCE_PATH` but not
|
|
`GITHUB_TOKEN`, confirmed by the failing log's
|
|
`[github-auth] configured=false` diagnostic.
|
|
- Landing fetches repository metrics and contribution activity during static
|
|
generation. A non-success response produces fallback markup that
|
|
`build-pages.mjs` rejects.
|
|
- GitHub's unauthenticated REST quota is IP-scoped and limited to 60 requests
|
|
per hour, so runner starting quota and concurrent consumption make the result
|
|
intermittent.
|
|
- The existing preview job also owns issue and pull-request write permissions
|
|
for its final comment step. Passing that job token directly to the build
|
|
would make the preview reliable but violate least privilege.
|
|
|
|
## Workflow
|
|
|
|
### Static permission contract
|
|
|
|
- Add `scripts/notify-docs-workflow.test.mjs` to inspect the checked-in
|
|
workflow and prove the preview build has an explicit token, the preview job
|
|
is read-only, and preview-link publication is isolated in a write-capable job
|
|
that does not build pull request content.
|
|
- Add the new test to the workflow's pull-request path filter and validator
|
|
test command so future workflow changes keep exercising the contract.
|
|
|
|
### Authenticated preview build
|
|
|
|
- Restrict `jobs.preview.permissions` in
|
|
`.github/workflows/notify-docs.yml` to `contents: read`.
|
|
- Export `GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}` only from the
|
|
`Build preview from pull request docs` step. Landing already recognizes this
|
|
environment variable through its existing `githubApiHeaders()` contract.
|
|
- Export the Cloudflare-enabled flag, deployment URL, and alias URL as preview
|
|
job outputs.
|
|
|
|
### Isolated preview comment
|
|
|
|
- Move `Publish docs preview link` into a `publish-preview-link` job that needs
|
|
`preview`, runs only when preview deployment is enabled, and owns
|
|
`issues: write` plus `pull-requests: write`.
|
|
- Pass deployment outputs through `needs.preview.outputs` and retain the
|
|
existing idempotent marker-based create-or-update script.
|
|
|
|
## Tests
|
|
|
|
- **What:** the landing build receives an explicit authenticated token while
|
|
its job cannot write issues or pull requests.
|
|
**File:** `scripts/notify-docs-workflow.test.mjs`.
|
|
**How:** extract the checked-in preview job and named build step from the YAML
|
|
text, then assert the token mapping and permission exclusions.
|
|
- **What:** preview comment publication retains write permissions without
|
|
executing the landing build.
|
|
**File:** `scripts/notify-docs-workflow.test.mjs`.
|
|
**How:** extract the publication job and assert its dependency, output inputs,
|
|
permissions, and absence of checkout/build steps.
|
|
- **What:** public-doc validation and the workflow contract remain green under
|
|
the exact command used by CI.
|
|
**File:** `.github/workflows/notify-docs.yml`.
|
|
**How:** run both Node test files together, then run the public-doc validator.
|
|
|
|
## Implementation Waves And Parallel Candidates
|
|
|
|
Execution is sequential because the regression test and workflow repair share
|
|
the same permission and job-output contract.
|
|
|
|
- [x] [Task 01: Authenticate and isolate docs preview publication](task-01-authenticate-and-isolate-preview.md) — done
|
|
|
|
## Documentation Impact
|
|
|
|
The concise repair spec records CI behavior and permissions. No public CLI,
|
|
configuration, API, deployment, or UI documentation changes are required.
|
|
|
|
## Risks
|
|
|
|
- Job outputs must preserve the exact Cloudflare action output values across
|
|
the new job boundary.
|
|
- The publication job must remain skipped when Cloudflare is unconfigured or
|
|
preview fails.
|
|
- Exposing the token at workflow or job scope would unnecessarily widen its
|
|
availability; the implementation must keep it scoped to the build step.
|