Skip to content

WP07: docs/updating.md and docs/ghtokenworkflow.md, the update workflow and its write token - #4

Merged
Arthurvdv merged 4 commits into
mainfrom
wp07/updating-docs
Oct 7, 2026
Merged

WP07: docs/updating.md and docs/ghtokenworkflow.md, the update workflow and its write token#4
Arthurvdv merged 4 commits into
mainfrom
wp07/updating-docs

Conversation

@Arthurvdv

@Arthurvdv Arthurvdv commented Oct 7, 2026

Copy link
Copy Markdown
Member

The user side of WP07 (Update system files). The engine side is ALCops/rulebook-engine#66.

Summary

  • New docs/updating.md, the Update Rulebook System Files workflow, with observed vs code-derived marked:
    • what an update changes, in user terms: replaced, kept, regenerated, never touched, the site files (planned) with the reasons a site file is skipped;
    • running it: the dispatch inputs, the first run, pinning a version (planned with WP13);
    • how Validate reports an update (the four annotations), when the check is skipped, why there is no lasting switch yet (Settings key to turn the Validate template update check off rulebook-engine#67);
    • the pull request: title, branch, labels, the body sections, open update pull requests and when a second one appears;
    • removing a shipped level, stage or file with unusedRulebookFiles (paths with /);
    • update.schedule, direct commit and its fallback to a pull request;
    • troubleshooting with the messages as observed in the live run or taken from the code.
  • New docs/ghtokenworkflow.md, the GHTOKENWORKFLOW secret:
    • why GITHUB_TOKEN is not enough;
    • a GitHub App step by step (the steps of the live run) and the one-liner for the compressed JSON;
    • fine-grained and classic personal access tokens;
    • repository and organization secrets, reuse with AL-Go, ghTokenWorkflowSecretName and its name rule;
    • a private template;
    • the failure messages.
  • docs/README.md: both pages listed as written; the planned al-go.md and troubleshooting.md rows point at ghtokenworkflow.md for the secret and token failures.
  • README.md: section 1's update workflow row links both pages.

Review

Three Sonnet code-review rounds at effort high, 29 findings, all fixed. Two of them led to engine changes on ALCops/rulebook-engine#66: the GITHUB_ prefix rule for ghTokenWorkflowSecretName (schema, workflow step, no silent fallback), and the "Branch <name> was pushed." sentence that a failed pull request step now always carries.

Merge order

Depends on ALCops/rulebook-engine#66: the linked engine pages (update-mechanics.md, D44) exist on the engine's main after it merges. Merge the engine PR first, then this one.

Part of ALCops/rulebook-engine#9

🤖 Generated with Claude Code

Arthurvdv and others added 4 commits October 7, 2026 17:43
@Arthurvdv @claude
WP07: docs/updating.md and docs/ghtokenworkflow.md, the update workfl…
0caec1e 
…ow and its write token

docs/updating.md: what an update replaces, keeps, regenerates or never
touches, the site files, running it and pinning a version, the check in
Validate and its annotations, the pull request (title, branch, labels, body
sections, the one-open-update guard and its limitation after a merge into the
branch), unusedRulebookFiles as paths, update.schedule, direct commit and its
fallback, and the messages of a failed run as observed in the live test.

docs/ghtokenworkflow.md: why GITHUB_TOKEN is not enough, a GitHub App step by
step with the one-liner for the compressed JSON, a fine-grained or classic
personal access token, repository and organization secrets and
ghTokenWorkflowSecretName, a private template, and the failure messages.

docs/README.md and README.md link both pages.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@Arthurvdv @claude
docs: review fixes for updating.md and ghtokenworkflow.md
87e9d73 
- Commits are authored by the account that started the run; only the pull
  request shows the App or the token owner.
- A classic token needs both repo and workflow.
- Secret names follow GitHub's rules, including the GITHUB_ prefix; an invalid
  name fails Validate (C5), the settings step and the update, never a fallback.
- The token request failure is described from the code, without a status.
- Open update pull requests: a moved branch or a moved template opens a second
  one.
- The update check: when it is skipped, what was verified live, when Validate
  runs it.
- The Change rule lists, the release notes, the issue form and the site files
  are marked planned; the settings edit inserts missing keys and makes LF.
- A failed pull request step names a pushed branch only when there is one.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@Arthurvdv @claude
docs: second review round for updating.md and ghtokenworkflow.md
072348a 
- A failed pull request step: "Branch <name> was pushed." with the link, or
  nothing was pushed.
- No lasting switch for the update check yet (engine #67); the workflow edit
  is reverted by the next update. The fork clause is dropped; other skip
  reasons carry their own text.
- The settings edit: templateUrl required, templateSha inserted, $schema only
  when the template has one.
- "not recorded" also after a template commit that changes no managed file.
- Site files: the skip mode, deleted files coming back, site/data never touched.
- The schedule: what the live run verified, default branch only.
- The installation lookup message also covers a wrong client id or key; a
  fine-grained token must include a private template repository.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@Arthurvdv @claude
docs: final review round for updating.md and ghtokenworkflow.md
9558fb8 
The right message for a missing templateUrl per trigger, the wrong client id
or key in the "could not be used" row, code-derived marks on the 401, the
scheduled-run author and the token-owner author, the "Error was:" part of a
failed pull request step, read access for a personal access token on a private
template, the generated-files exception to "never touched", the reasons of
the skipped site files, the one-owner limit of a fine-grained token, and the
index rows of al-go.md and troubleshooting.md point at ghtokenworkflow.md.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@Arthurvdv Arthurvdv added the documentation Improvements or additions to documentation label Oct 7, 2026
This was referenced Oct 7, 2026
Merged
Closed
Arthurvdv added a commit to ALCops/rulebook-engine that referenced this pull request Oct 7, 2026
@Arthurvdv
Update Rulebook System Files: CheckForUpdates action, update workflow…
f878ed8 
…, GHTOKENWORKFLOW (D44), unusedRulebookFiles as paths (#66)

Organizations can now pull new template versions into their rulebook repository as a reviewable pull request, in the shape of AL-Go's "Update AL-Go System Files" (R5).

- actions/CheckForUpdates (new): check mode and update mode; outputs updatesAvailable, pullRequestUrl, templateSha, failure (token, template, validation, push, pull-request, error). Check mode never fails.
- modules/Rulebook.Update (new): file classes with the include-list rule (overwrite, settings, generated, customizable, org-owned), candidate tree, regeneration of skeletons/ and rulesets/, Test-Rulebook as the gate before any push, sha-only detection, D35 three-way decision for site/**, in-place settings edit, workflow rewrite ({TEMPLATEURL}, D30 choice lists, schedule: from update.schedule) with a yaml line editor, release-notes delta, PR body with the effective diff, Publish-RulebookUpdate (duplicate title guard, clone, commit, push, labelled PR, direct commit with fallback).
- modules/Rulebook.GitHub (new): REST wrapper, GHTOKENWORKFLOW exchange (PAT as is, GitHub App JSON in AL-Go format exchanged for an installation token), zipball, pull request helpers, clone and push with the token only in the git process environment.
- template/.github/workflows/UpdateRulebookSystemFiles.yaml (new): dispatch inputs, read-only GITHUB_TOKEN, settings step resolving ghTokenWorkflowSecretName, secrets[steps.settings.outputs.secretName].
- Validate: checkForUpdates wired; notice or warning plus a "Template update check" summary, never counted.
- Schema and C9 (#49): unusedRulebookFiles entries are repository-relative paths with "/"; new update.schedule; ghTokenWorkflowSecretName rejects the GITHUB_ prefix.
- Fixtures tests/fixtures/templates/{v1,v2} and tests/fixtures/repos/update-org; suites Rulebook.GitHub, Rulebook.Update, CheckForUpdates.Action; 1202 tests green on Windows and Linux.
- CI: job update-action (required check).
- Docs: docs/reference/update-mechanics.md with the live-run record; ADR D44 (#28); ARCHITECTURE, naming, template-content, dashboard, al-go-template-mechanics, CONTRIBUTING, template README.

Interview decisions (2026-10-07): classes generic now, consumers later; live E2E on scratch repos under Arthurvdv with a GitHub App; #28 and #49 folded in; secret lookup via a settings step; update.schedule in v1; validate the candidate before any push; local template folders and a bare git repo as engine proof; #58 stays at WP12; check mode never fails Validate; skeletons generated from the settings.

Review: three Sonnet code-review rounds at effort high, 31 findings, 29 fixed, 1 accepted (duplicate guard embeds the base head sha, AL-Go behaviour), 2 deferred to #58; two more engine fixes came from the docs review of ALCops/rulebook#4.

Live run: AC1 to AC10 observed on Arthurvdv/rulebook-e2e-template and Arthurvdv/rulebook-e2e-update; one fix from the run (endpoint order in the effective-diff tables).

Spin-off: #67 settings key to turn the Validate update check off.

Closes #9, #28, #49

🤖 Generated with [Claude Code](https://claude.com/claude-code)
@Arthurvdv
Arthurvdv merged commit 495b668 into main Oct 7, 2026
@Arthurvdv
Arthurvdv deleted the wp07/updating-docs branch October 7, 2026 17:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Arthurvdv