ci(udg): build bot — add the build-dist label and CI runs just build #193

Merged

peterswimm merged 1 commit from ci/udg-build-bot into main 2026-10-07 23:02:44 +00:00

Conversation 0 Commits 1 Files changed 2 +156

peterswimm commented 2026-10-07 22:58:39 +00:00

Owner

Copy link

Scope

Adds the UDG build bot, so designers (Keff first) get dist/ rebuilt without a local
toolchain. Add the build-dist label to a same-repo PR, or dispatch the workflow with a branch,
and CI:

1. runs the justfile's build recipe in python:3.12-slim;
2. converts EPS plates, but only when the branch changes one (it installs ghostscript and
   poppler-utils itself);
3. refuses to push if anything outside the generated paths changed (dist/,
   Brand/source/derived/, docs/brand-guide.html, the WordPress theme and preview outputs);
4. commits the result back to the branch and removes the label.

It never runs for forks or main. A "Let CI build it" section in CONTRIBUTING.md explains it.

This is step 1 of the designer-tooling roadmap. Step 2 is just doctor and a designer quickstart.

Setup needed before it can run (repo admin)

• Create the label build-dist.
• Add the repo secret UDG_BUILD_BOT_TOKEN: a dedicated bot account's token with write
  access to this repository only (contents, plus issues for removing the label). Don't reuse
  CI_TOKEN. Forgejo's automatic token won't work, because its pushes don't re-trigger the drift
  gate.
• Note: for pull_request events, the workflow file from the PR head runs. Anyone who can push a
  branch here could therefore read this token, but they already have write access, so it grants
  nothing new. Keep the token scoped to this repository.

Testing

Rehearsed in python:3.12-slim (Docker) with the workflow's own run: blocks, extracted from the
YAML; only git push was stubbed:

Case	Expected	Result
main with stale artifact.html (the control, which should produce a commit)	bot commit	13 × artifact.html, identical to #192
#192 branch, already built	no commit	"dist/ already matches … nothing to commit"
branch that edits an EPS plate	plates converted	Brand/source/derived/plate.ui.rectangle.svg + dist/assets/* committed
stray non-generated file	guard fails	::error::build changed non-generated paths; nothing pushed: stray.txt

The extract, artifact, brand-guide, assets and docs checks all pass on both bot-made commits.
test_workflow_invariants.py: 62 passed. yamllint --strict .forgejo/workflows/: clean. Not yet
exercised live: the push and the label removal, which need the secret above.

Impact Statement

• Existing features: no expected impact. A new opt-in workflow; udg-dist-check is unchanged.
• Public APIs / contracts: none.
• Schemas: none.
• Data / artifacts: the bot writes only generated paths, guarded.
• Integrations: Forgejo Actions plus one new repo secret and one new label.
• Mappings: none.
• Backward compatibility: fully compatible. Running just build locally still works.

Docs

CONTRIBUTING.md → "Let CI build it". Merge #192 first so the drift gate is green.

## Scope Adds the **UDG build bot**, so designers (Keff first) get `dist/` rebuilt without a local toolchain. Add the `build-dist` label to a same-repo PR, or dispatch the workflow with a branch, and CI: 1. runs the justfile's `build` recipe in `python:3.12-slim`; 2. converts EPS plates, but only when the branch changes one (it installs ghostscript and poppler-utils itself); 3. **refuses to push** if anything outside the generated paths changed (`dist/`, `Brand/source/derived/`, `docs/brand-guide.html`, the WordPress theme and preview outputs); 4. commits the result back to the branch and removes the label. It never runs for forks or `main`. A "Let CI build it" section in `CONTRIBUTING.md` explains it. This is step 1 of the designer-tooling roadmap. Step 2 is `just doctor` and a designer quickstart. ### Setup needed before it can run (repo admin) - [ ] Create the label **`build-dist`**. - [ ] Add the repo secret **`UDG_BUILD_BOT_TOKEN`**: a dedicated bot account's token with write access to **this repository only** (contents, plus issues for removing the label). Don't reuse `CI_TOKEN`. Forgejo's automatic token won't work, because its pushes don't re-trigger the drift gate. - Note: for `pull_request` events, the workflow file from the PR head runs. Anyone who can push a branch here could therefore read this token, but they already have write access, so it grants nothing new. Keep the token scoped to this repository. ## Testing Rehearsed in `python:3.12-slim` (Docker) with the workflow's own `run:` blocks, extracted from the YAML; only `git push` was stubbed: | Case | Expected | Result | |---|---|---| | `main` with stale `artifact.html` (the control, which should produce a commit) | bot commit | 13 × `artifact.html`, identical to #192 | | #192 branch, already built | no commit | "dist/ already matches … nothing to commit" | | branch that edits an EPS plate | plates converted | `Brand/source/derived/plate.ui.rectangle.svg` + `dist/assets/*` committed | | stray non-generated file | guard fails | `::error::build changed non-generated paths; nothing pushed: stray.txt` | The extract, artifact, brand-guide, assets and docs checks all pass on both bot-made commits. `test_workflow_invariants.py`: 62 passed. `yamllint --strict .forgejo/workflows/`: clean. Not yet exercised live: the push and the label removal, which need the secret above. ## Impact Statement - Existing features: no expected impact. A new opt-in workflow; `udg-dist-check` is unchanged. - Public APIs / contracts: none. - Schemas: none. - Data / artifacts: the bot writes only generated paths, guarded. - Integrations: Forgejo Actions plus one new repo secret and one new label. - Mappings: none. - Backward compatibility: fully compatible. Running `just build` locally still works. ## Docs `CONTRIBUTING.md` → "Let CI build it". Merge #192 first so the drift gate is green.

peterswimm added 1 commit 2026-10-07 22:58:39 +00:00

ci(udg): build bot — add the build-dist label and CI runs just build ... 443d688b1a

udg-dist-check only verifies dist/, so every contributor had to run the
build locally (terminal, Python, just, plus ghostscript + poppler for
plates). #163 shows the cost: a generator change merged without its rebuild
and the drift gate stayed red on every PR after it.

New workflow udg-build-bot.yml: on the build-dist label (same-repo PRs
only) or workflow_dispatch with a branch (never main), it runs the `build`
recipe in python:3.12-slim, converts EPS plates only when the branch
touches one, refuses to push if anything outside the generated paths
changed, commits the generated output back to the branch with a
dedicated repo-scoped token (UDG_BUILD_BOT_TOKEN), and removes the label.

Rehearsed in python:3.12-slim with the workflow's own run: blocks:
  - origin/main (control): bot commit = the 13 stale artifact.html (#192)
  - #192 branch: "nothing to commit"
  - branch touching an EPS: plates converted, derived SVG + asset index committed
  - stray non-generated file: guard fails, nothing pushed
Drift checks pass on both bot commits. Workflow invariants: 62 passed;
yamllint --strict: clean.

peterswimm referenced this pull request from a commit 2026-10-07 23:00:59 +00:00

feat(tools): just doctor + designer quickstart

peterswimm referenced this pull request 2026-10-07 23:01:10 +00:00

feat(tools): just doctor + designer quickstart #194

peterswimm merged commit 56d93479e3 into main 2026-10-07 23:02:44 +00:00

peterswimm deleted branch ci/udg-build-bot 2026-10-07 23:02:45 +00:00

peterswimm referenced this pull request from a commit 2026-10-07 23:02:46 +00:00

Merge pull request 'ci(udg): build bot — add the build-dist label and CI runs `just build`' (#193) from ci/udg-build-bot into main

peterswimm referenced this pull request 2026-10-07 23:03:12 +00:00

WIP: test(ci): build bot live test — do not merge #195

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

build-dist

Ask the UDG build bot to run just build and commit generated files to this PR

  

priority

P1

Urgent — no working icon yet (custom art pending) or a shipping asset

  

priority

P2

High — has an accessible stand-in; bespoke art wanted

  

priority

P3

Medium — stage visual headers

  

priority

P4

Low — behavioral dimension family

  

bug

Something is not working

  

duplicate

This issue or pull request already exists

  

enhancement

New feature

  

help wanted

Need some help

  

invalid

Something is wrong

  

question

More information is needed

  

wontfix

This won't be fixed

No labels

build-dist

priority

P1

priority

P2

priority

P3

priority

P4

bug

duplicate

enhancement

help wanted

invalid

question

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Toilville/toilville-design!193

No description provided.