Title: Sync automation-template.yml to consumer repos with pull requests · Issue #95 · learningequality/.github · GitHub
Open Graph Title: Sync automation-template.yml to consumer repos with pull requests · Issue #95 · learningequality/.github
X Title: Sync automation-template.yml to consumer repos with pull requests · Issue #95 · learningequality/.github
Description: Overview Consumer repos hold a copied automation-template.yml. When the generated template changes, every consumer must copy it again, and nothing today detects that or does it. A stale copy fails silently. Add a workflow in this repo th...
Open Graph Description: Overview Consumer repos hold a copied automation-template.yml. When the generated template changes, every consumer must copy it again, and nothing today detects that or does it. A stale copy fails ...
X Description: Overview Consumer repos hold a copied automation-template.yml. When the generated template changes, every consumer must copy it again, and nothing today detects that or does it. A stale copy fails ...
Opengraph URL: https://github.com/learningequality/.github/issues/95
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Sync automation-template.yml to consumer repos with pull requests","articleBody":"## Overview\n\nConsumer repos hold a copied `automation-template.yml`. When the generated template changes, every\nconsumer must copy it again, and nothing today detects that or does it. A stale copy fails silently.\n\nAdd a workflow in this repo that opens a pull request in each consumer repo whose copy no longer\nmatches the template, in the same shape dependabot uses. The workflow proposes the change. A person\nin that repo reviews and merges it.\n\n**Complexity:** Medium\n**Target branch:** main\n\n### Context\n\n#88 gives every consumer one file to copy, `.github/workflows/automation.yml`, generated from\n`automation-registry.yml`. Most registry changes reach consumers on their own, because that file only\nsays `uses: learningequality/.github/.github/workflows/automation.yml@main`. Toggling an automation,\nchanging a dispatch `if:`, or pointing one at a different leaf all propagate with no consumer action.\n\nFour things leave a consumer's copy out of date:\n\n1. A new event or activity type enters the `on:` union.\n2. The permissions union widens.\n3. The secret list changes.\n4. The consumer's own tooling rewrites the copy.\n\nThe fourth is not theoretical. It happened twice during #88, before any migration. yamlfmt v0.16.0\nstripped a blank line from the header, and the template lacked the inline\n`# zizmor: ignore[dangerous-triggers]` that the callers it replaces carry. Both were fixed in #88.\nNeither was visible from this repo, because this repo pins an older yamlfmt, excludes the generated\nfiles from it, and runs no zizmor.\n\nAll four fail quietly. The consumer keeps running its old `on:` block, so a new automation simply\nnever fires there. There is no error and no log line.\n\nAll four also end in the same state: the consumer's file differs from `automation-template.yml`. One\nmechanism resolves all of them, rather than engineering each cause away separately.\n\n### The Change\n\nAdd a workflow in this repo that compares each consumer's `.github/workflows/automation.yml` against\n`automation-template.yml` on `main`, and opens a pull request replacing it wherever the two differ.\n\nFollow the dependabot shape. The pull request is the whole artifact. There is no accompanying issue,\nbecause the change is a byte copy of one file with nothing to author and nothing to decide, and a\nsecond artifact per repo per change is noise.\n\nThe work must be done by the workflow itself, not delegated to an agent. The task is deterministic,\nand routing it through an agent means the fix lands only if that agent picks it up, which reintroduces\nthe silent drift this workflow exists to end.\n\n**A core maintainer approves and merges every change.** This is a constraint on how the workflow is\nwritten:\n\n- It opens pull requests on a branch, and never commits to a default branch.\n- It never merges, never enables auto-merge, and never approves its own pull request.\n- Each consumer repo's existing review rules gate the change, unchanged.\n- A pull request left unmerged stays unmerged. The workflow updates it and never routes around it.\n\nThere is no bot pre-review. The copy either matches the template or it does not, and the workflow\nwrites those bytes by construction, so there is no content question a reviewer could answer\ndifferently. What the core maintainer decides is whether to accept the file landing in their repo.\n\nIt must be idempotent. A repo already in sync gets nothing. A repo with a sync pull request already\nopen gets that pull request updated, not a second one.\n\nDetection then falls out of remediation. No open pull request means no drift.\n\n**The app's scope.** The workflows authenticate as `learning-equality-bot[bot]`, the app behind\n`LE_BOT_APP_ID`. That is a different identity from `rtibblesbot`, the user account that opened the\nmigration pull requests for #88, so the migration was no evidence of the app's scope. The app needs\n`contents: write` and `pull-requests: write`, and holds both.\n\nInstallation is separate from permissions and is granted per repo. `morango` had the secrets and the\npermissions and still failed, because the app was not installed there. A repo the app is not\ninstalled on is invisible to discovery, so installation is what enrols it.\n\nNote that `contents: write` is also enough to push directly to a default branch. Default-branch\nprotection on each consumer is what makes the human-in-the-loop constraint enforceable rather than\nmerely intended, so confirm that alongside the app scope.\n\n**Classify drift against the template's own history.** Compare the time `automation-template.yml`\nlast changed here with the time the repo's last sync pull request closed. A template change after\nthat is ordinary drift. Without one, the difference came from the consumer, and which side acted\ndecides the outcome:\n\n- A merged pull request means the consumer's own tooling rewrote the copy. Report it as a toolchain\n conflict, because the template is not stable under that toolchain, and reopening would loop\n forever. Report on the first occurrence rather than waiting for a second, which would only spend a\n maintainer's attention to confirm what is already known.\n- A pull request closed unmerged means a maintainer declined it. Leave that repo alone until the\n template moves again, so the workflow stops asking without forgetting. This state does not fail\n the run, so a repo can sit drifted while the workflow stays green.\n\nAn unknown template date resolves to ordinary drift. A needless pull request costs one review, where\na wrong toolchain conflict stops syncing the repo entirely.\n\n**Build the pull request body from the consumer's own template.** A repo with its own pull request\ntemplate, or a check on the description, needs more than generic text. Read that repo's template and\nuse it, so its shape stays current without anything stored here. A repo with no template gets a short\nexplanation instead.\n\nAnswer the template's fields rather than copying them. A template ships each field with instructions\nfor a human author, and a body full of \"Choose from: yes / no\" reads as an unanswered form. Name the\nchange in `Description`, put `none` in `Products impact`, and leave a dash everywhere else. That also\nsatisfies a repo checking that the description is no longer its placeholder, which is what\n`kolibri-design-system` does with `check-description`.\n\n**Find the consumers rather than listing them.** Walk the org's repos, skip archived ones and forks,\nand keep every repo whose `.github/workflows/automation.yml` calls this repo's `automation.yml`.\nThis repo's own reusable workflow sits at the same path and does not call it, so that marker\nexcludes it without a special case.\n\nTarget each repo's default branch. That is not a free choice: GitHub evaluates workflow triggers\nonly from the default branch, so any other value is wrong.\n\nA list would need editing whenever a repo onboards, and would carry a base branch per repo that can\ndrift from reality. Discovery removes both. It also means a repo the app is not installed on never\nappears, so installation is what enrols a repo.\n\n### Out of Scope\n\n- Generating the `on:` block with every activity type for the events in use. It would stop new\n activity types from changing the template, but consumers would then run the workflow on more events\n with every job skipping. `pull_request_target: synchronize` alone fires on every push to every pull\n request. Sync pull requests make this unnecessary, and the `on:` block stays minimal.\n- Replacing the computed permissions union with a fixed ceiling, for the same reason.\n- Auto-merging the sync pull requests.\n- Bumping this repo's yamlfmt pin from v0.14.0 to v0.16.0. It would catch the formatting class of\n problem locally and match `le-utils`, but it also reformats `.github/dependabot.yml` and\n `automation-registry.yml`.\n\n### Acceptance Criteria\n\n#### Prerequisites\n\n- [x] `learning-equality-bot[bot]` is confirmed to hold `contents: write` and `pull-requests: write`\n on all eight consumer repos, and the confirmation is recorded on this issue. Confirmed by\n @akolson on 2026-09-23, see the comment below.\n- [ ] Default-branch protection is confirmed on all eight, so a direct push cannot bypass review.\n\n#### Human in the loop\n\n- [ ] The workflow opens pull requests on a branch and never commits to a default branch.\n- [ ] It never merges a pull request, never enables auto-merge, and never approves one.\n- [ ] Each consumer's existing review rules gate the change, unchanged.\n- [ ] The pull request body says what changed and that the file is generated, not hand-edited.\n\n#### Behaviour\n\n- [ ] The workflow runs on a schedule, on `workflow_dispatch`, and when `automation-template.yml`\n changes on `main`.\n- [ ] It opens a pull request in each consumer repo whose `.github/workflows/automation.yml` differs\n from the template, replacing that file and nothing else.\n- [ ] No accompanying issue is opened.\n- [ ] A repo already in sync gets no pull request.\n- [ ] A repo with an open sync pull request gets it updated, never duplicated.\n- [ ] The consumers are discovered from the org rather than listed, by the marker that a copy calls\n this repo's `automation.yml`.\n- [ ] Each pull request targets the repo's own default branch.\n- [ ] Archived repos and forks are skipped. `kolibri-app`, `kolibri-installer-android` and\n `kolibri-image-pi` hold inert copies, because Actions do not run on archived repos.\n- [ ] A repo with no `automation.yml` is not a consumer, and produces no result at all.\n- [ ] A failed repo listing stops the run loudly rather than syncing a partial set.\n- [ ] Drift after a merged sync pull request, with no template change since, is reported as a\n toolchain conflict on the first occurrence, and no pull request is opened.\n- [ ] Drift after a sync pull request closed unmerged is reported as declined, and no pull request\n is opened until the template changes again.\n- [ ] An unreadable template history resolves to ordinary drift rather than stopping a repo.\n- [ ] A repo the workflow cannot write to is reported, not skipped silently.\n- [ ] The pull request body comes from the consumer's own pull request template when it has one,\n with its fields answered, and from a short explanation when it does not.\n- [ ] `kolibri-design-system` receives a body its `check-description` job accepts, with nothing\n about that repo stored here.\n- [ ] Two overlapping runs cannot both open the same pull request.\n- [ ] The state classification and the write payloads are covered by tests with an injected client,\n including that the write targets the sync branch and never a default branch.\n- [ ] `docs/automation.md` says the sync workflow exists, what it opens, who merges it, and what\n each state that needs a core maintainer means.\n\n### Testing\n\n1. Run the workflow manually while every consumer is in sync. Confirm that it finds the expected\n repos and opens nothing.\n2. Change `automation-registry.yml` so the template changes, merge it, and confirm that the workflow\n opens one pull request per consumer, and merges none of them.\n3. Run it again before merging those. Confirm that the existing pull requests are updated and no\n duplicates appear.\n4. Leave a sync pull request unmerged across two runs. Confirm that the consumer's file is unchanged\n on its default branch.\n5. Merge one consumer's pull request by hand, run again, and confirm that repo is reported in sync.\n6. Revert a merged sync pull request's change in a consumer repo, then run once. Confirm that the\n run reports a toolchain conflict and opens nothing.\n7. Close a sync pull request without merging it, then run again. Confirm that the repo is reported\n as declined and no pull request reopens.\n8. Point the workflow at a repo the app cannot write to. Confirm that it reports the failure rather\n than passing.\n\n### References\n\n- #88 introduces the template, the registry and the generator.\n- #86 is the consolidation tracking issue, including the decision against `secrets: inherit`.\n- `docs/automation.md` describes the entry point and the cases that need a re-copy.\n- The two toolchain rewrites found during #88: yamlfmt stripping the header blank line, and the\n missing inline zizmor ignore.\n\n## AI usage\n\nI used Claude Code while reviewing #88, where the two toolchain rewrites and this propagation gap\nsurfaced, and to draft this issue from that work. I verified the failure modes against the consumer\nrepos, chose the dependabot shape over detection alone and over routing the work through an agent,\nset the human-in-the-loop constraint, and edited the wording.\n\n\n\n","author":{"url":"https://github.com/akolson","@type":"Person","name":"akolson"},"datePublished":"2026-09-17T11:34:36Z","url":"https://github.com/learningequality/.github/issues/95"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:0de8feb2-2382-d176-17a7-ae22e98432b3 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 89FA:5537E:FD9C8B:14B0BA8:6AFFF5E1 |
| html-safe-nonce | 79f32688dc8573c686ba37a09269dc75bb2ecd3fe832209de8cdf634c1d350f3 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI4OUZBOjU1MzdFOkZEOUM4QjoxNEIwQkE4OjZBRkZGNUUxIiwidmlzaXRvcl9pZCI6IjYzOTQ1NTM0NzkxMDAxMDIxMTMiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 38bc2a0897fc0265a4517e381c349a27ff93ba072a8ac2ef9a0c86d6ee72ba3e |
| hovercard-subject-tag | issue:5486788642 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/learningequality/.github/95/issue_layout |
| twitter:image | https://opengraph.githubassets.com/2c6687af2265c840f404732d4786d95b3a0c8043dc7282302dab7e2f8f60aadc/learningequality/.github/issues/95 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/2c6687af2265c840f404732d4786d95b3a0c8043dc7282302dab7e2f8f60aadc/learningequality/.github/issues/95 |
| og:image:alt | Overview Consumer repos hold a copied automation-template.yml. When the generated template changes, every consumer must copy it again, and nothing today detects that or does it. A stale copy fails ... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | akolson |
| hostname | github.com |
| expected-hostname | github.com |
| None | 0a0d8686a27478df474dd7415776a7a080cde8838b3cd92ea7601187572e5729 |
| turbo-cache-control | no-preview |
| go-import | github.com/learningequality/.github git https://github.com/learningequality/.github.git |
| octolytics-dimension-user_id | 3926525 |
| octolytics-dimension-user_login | learningequality |
| octolytics-dimension-repository_id | 647407699 |
| octolytics-dimension-repository_nwo | learningequality/.github |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 647407699 |
| octolytics-dimension-repository_network_root_nwo | learningequality/.github |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 16a11879678aaf97e2a42c33ee70830aa084fa37 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width