Updating the documentation¶
I keep the procedures with the code they describe. This repository brings those pages together at gamb2le.pages.dev. For the dashboard and app cleanup, start with the documentation update plan: it links the current runbooks, source changes and release evidence.
Make a change¶
Edit the page in its owning repository, check its links and build the docs, then merge it with the related code. Use a dated record for deployments, checks and remaining problems. Keep the reusable procedure separate, so an old service status does not become tomorrow's instruction.
The portal currently includes eight repositories:
aurora_sopsaurora_cloud_dashboardaurora-cloud-infrachillybatholoimgass-compute-documentationlogger-documentationsupplementary
Their navigation is included from mkdocs.yml; the build clones them under
repos/. The native app guides are linked from the dashboard and app plan and
stay in their own repositories.
Publish and check¶
The documentation workflow
runs after a portal change reaches main, a docs-updated repository event, a
manual rebuild, or the daily 06:00 UTC schedule. It reads the latest portal
main and each included repository's default branch, builds with
mkdocs build --strict, and publishes site/ to the existing Cloudflare Pages
project gamb2le. A MkDocs warning or build error stops publication.
Only one production build runs at a time. The current build finishes; pending
requests are combined into the newest waiting run. That run checks out the
current main when it starts, including reruns of this workflow revision. This
keeps overlapping repository updates from publishing an old portal page last.
I check the Actions result,
then open the changed page on the public site and follow one relevant runbook
link. A successful source merge or local build does not establish publication.
For a failed build, start with its first error in Actions. Fix and merge that
source, then use Run workflow on main if another build has not started.
Use a new run for older failures: rerunning a historical run retains its old
workflow definition, including any missing publication safeguards.
Add another repository¶
- Give it a working
mkdocs.ymland adocs/entry page. The template repository is a starting point; check its paths against the actual repository. - Add its clone to the portal workflow and its include to the portal navigation.
- Check that the existing GitHub App installation can read that repository.
If it should trigger immediate rebuilds, use the established
.github/workflows/trigger-docs.ymlpattern to dispatchdocs-updatedto this portal. Otherwise the daily or manual rebuild still picks it up. - Run a complete strict portal build with all included repositories present. After merging, check the public page and navigation.
The navigation entry looks like this:
Existing publishing credentials¶
The build uses the existing GitHub App: APP_ID and APP_PRIVATE_KEY let
actions/create-github-app-token obtain a short-lived installation token for
the included repositories. This is an App token, not a personal access token.
The source repository's dispatch workflow needs its established credential
access too; check that workflow and its secret names before configuring a new
repository. Keep private keys in the approved Actions secret configuration.
Cloudflare publication uses CLOUDFLARE_API_TOKEN and
CLOUDFLARE_ACCOUNT_ID. The portal build's ordinary GITHUB_TOKEN only needs
read access. The separate Aurora log workflow commits its generated page and
has its own credentials and permissions.
Preview locally¶
Use a separate checkout of the portal and put the eight included repositories
under repos/, with their current documentation. Existing authorised Git
credentials are enough to clone private repositories; do not put tokens into
commands or documentation.
From that portal checkout:
uv run --with-requirements requirements.txt mkdocs build --strict
uv run --with-requirements requirements.txt mkdocs serve
The first command checks the complete site. The second gives a local preview; it does not publish anything. To undo a documentation change, revert the source commit and publish again through the same workflow. Dashboard service rollback and observation recovery remain separate procedures.