Sync automation-template.yml to consumer repos with pull requests

[akolson]

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 that opens a pull request in each consumer repo whose copy no longer
matches the template, in the same shape dependabot uses. The workflow proposes the change. A person
in that repo reviews and merges it.

Complexity: Medium
Target branch: main

Context

#88 gives every consumer one file to copy, .github/workflows/automation.yml, generated from
automation-registry.yml. Most registry changes reach consumers on their own, because that file only
says uses: learningequality/.github/.github/workflows/automation.yml@main. Toggling an automation,
changing a dispatch if:, or pointing one at a different leaf all propagate with no consumer action.

Four things leave a consumer's copy out of date:

1. A new event or activity type enters the on: union.
2. The permissions union widens.
3. The secret list changes.
4. The consumer's own tooling rewrites the copy.

The fourth is not theoretical. It happened twice during #88, before any migration. yamlfmt v0.16.0
stripped a blank line from the header, and the template lacked the inline
# zizmor: ignore[dangerous-triggers] that the callers it replaces carry. Both were fixed in #88.
Neither was visible from this repo, because this repo pins an older yamlfmt, excludes the generated
files from it, and runs no zizmor.

All four fail quietly. The consumer keeps running its old on: block, so a new automation simply
never fires there. There is no error and no log line.

All four also end in the same state: the consumer's file differs from automation-template.yml. One
mechanism resolves all of them, rather than engineering each cause away separately.

The Change

Add a workflow in this repo that compares each consumer's .github/workflows/automation.yml against
automation-template.yml on main, and opens a pull request replacing it wherever the two differ.

Follow the dependabot shape. The pull request is the whole artifact. There is no accompanying issue,
because the change is a byte copy of one file with nothing to author and nothing to decide, and a
second artifact per repo per change is noise.

The work must be done by the workflow itself, not delegated to an agent. The task is deterministic,
and routing it through an agent means the fix lands only if that agent picks it up, which reintroduces
the silent drift this workflow exists to end.

A core maintainer approves and merges every change. This is a constraint on how the workflow is
written:

• It opens pull requests on a branch, and never commits to a default branch.
• It never merges, never enables auto-merge, and never approves its own pull request.
• Each consumer repo's existing review rules gate the change, unchanged.
• A pull request left unmerged stays unmerged. The workflow updates it and never routes around it.

There is no bot pre-review. The copy either matches the template or it does not, and the workflow
writes those bytes by construction, so there is no content question a reviewer could answer
differently. What the core maintainer decides is whether to accept the file landing in their repo.

It must be idempotent. A repo already in sync gets nothing. A repo with a sync pull request already
open gets that pull request updated, not a second one.

Detection then falls out of remediation. No open pull request means no drift.

Verify the app installation scope first. The workflows authenticate as
learning-equality-bot[bot], the app behind LE_BOT_APP_ID. That is a different identity from
rtibblesbot, the user account that opened the migration pull requests for #88, so the migration is
no evidence of the app's scope. The app needs contents: write and pull-requests: write on all
eight consumers. If it lacks them on one repo, the workflow silently covers seven. Confirm before
writing code.

Note that contents: write is also enough to push directly to a default branch. Default-branch
protection on each consumer is what makes the human-in-the-loop constraint enforceable rather than
merely intended, so confirm that alongside the app scope.

Classify drift against the template's own history. Compare the time automation-template.yml
last changed here with the time the repo's last sync pull request closed. A template change after
that is ordinary drift. Without one, the difference came from the consumer, and which side acted
decides the outcome:

• A merged pull request means the consumer's own tooling rewrote the copy. Report it as a toolchain
  conflict, because the template is not stable under that toolchain, and reopening would loop
  forever. Report on the first occurrence rather than waiting for a second, which would only spend a
  maintainer's attention to confirm what is already known.
• A pull request closed unmerged means a maintainer declined it. Leave that repo alone until the
  template moves again, so the workflow stops asking without forgetting. This state does not fail
  the run, so a repo can sit drifted while the workflow stays green.

An unknown template date resolves to ordinary drift. A needless pull request costs one review, where
a wrong toolchain conflict stops syncing the repo entirely.

Let a consumer shape the pull request body. A repo with its own pull request template, or a check
on the description, needs more than generic text. kolibri-design-system fails check-description
unless the body carries a Changelog block. Give each consumer an optional body template with a
placeholder for the generated text, so the body follows that repo's own section order.

Consumer repos, from the org-wide search run for #88:

• kolibri, studio, ricecooker, kolibri-design-system, le-utils
• kolibri-data-portal, morango, kolibri-installer-debian

Out of Scope

• Generating the on: block with every activity type for the events in use. It would stop new
  activity types from changing the template, but consumers would then run the workflow on more events
  with every job skipping. pull_request_target: synchronize alone fires on every push to every pull
  request. Sync pull requests make this unnecessary, and the on: block stays minimal.
• Replacing the computed permissions union with a fixed ceiling, for the same reason.
• Auto-merging the sync pull requests.
• Bumping this repo's yamlfmt pin from v0.14.0 to v0.16.0. It would catch the formatting class of
  problem locally and match le-utils, but it also reformats .github/dependabot.yml and
  automation-registry.yml.

Acceptance Criteria

Prerequisites

• learning-equality-bot[bot] is confirmed to hold contents: write and pull-requests: write
  on all eight consumer repos, and the confirmation is recorded on this issue.
• Default-branch protection is confirmed on all eight, so a direct push cannot bypass review.

Human in the loop

• The workflow opens pull requests on a branch and never commits to a default branch.
• It never merges a pull request, never enables auto-merge, and never approves one.
• Each consumer's existing review rules gate the change, unchanged.
• The pull request body says what changed and that the file is generated, not hand-edited.

Behaviour

• The workflow runs on a schedule, on workflow_dispatch, and when automation-template.yml
  changes on main.
• It opens a pull request in each consumer repo whose .github/workflows/automation.yml differs
  from the template, replacing that file and nothing else.
• No accompanying issue is opened.
• A repo already in sync gets no pull request.
• A repo with an open sync pull request gets it updated, never duplicated.
• Archived repos are left out of the consumer list, with the reason recorded next to it.
  kolibri-app, kolibri-installer-android and kolibri-image-pi hold inert copies, because
  Actions do not run on archived repos.
• A repo with no automation.yml is reported as not migrated, and gets no pull request.
• Drift after a merged sync pull request, with no template change since, is reported as a
  toolchain conflict on the first occurrence, and no pull request is opened.
• Drift after a sync pull request closed unmerged is reported as declined, and no pull request
  is opened until the template changes again.
• An unreadable template history resolves to ordinary drift rather than stopping a repo.
• A repo the workflow cannot write to is reported, not skipped silently.
• A consumer can supply a pull request body template with a placeholder for the generated text,
  and kolibri-design-system uses one so its check-description job passes.
• Two overlapping runs cannot both open the same pull request.
• The state classification and the write payloads are covered by tests with an injected client,
  including that the write targets the sync branch and never a default branch.
• docs/automation.md says the sync workflow exists, what it opens, who merges it, and what
  each state that needs a core maintainer means.

Testing

1. Run the workflow manually while every consumer is in sync. Confirm that it opens nothing.
2. Change automation-registry.yml so the template changes, merge it, and confirm that the workflow
   opens one pull request per consumer, and merges none of them.
3. Run it again before merging those. Confirm that the existing pull requests are updated and no
   duplicates appear.
4. Leave a sync pull request unmerged across two runs. Confirm that the consumer's file is unchanged
   on its default branch.
5. Merge one consumer's pull request by hand, run again, and confirm that repo is reported in sync.
6. Revert a merged sync pull request's change in a consumer repo, then run once. Confirm that the
   run reports a toolchain conflict and opens nothing.
7. Close a sync pull request without merging it, then run again. Confirm that the repo is reported
   as declined and no pull request reopens.
8. Point the workflow at a repo the app cannot write to. Confirm that it reports the failure rather
   than passing.

References

• Consolidate shared workflows into a single generated automation.yml entry point #88 introduces the template, the registry and the generator.
• Consolidate shared workflows into a single generated automation.yml entry point #86 is the consolidation tracking issue, including the decision against secrets: inherit.
• docs/automation.md describes the entry point and the cases that need a re-copy.
• The two toolchain rewrites found during Consolidate shared workflows into a single generated automation.yml entry point #88: yamlfmt stripping the header blank line, and the
  missing inline zizmor ignore.

AI usage

I used Claude Code while reviewing #88, where the two toolchain rewrites and this propagation gap
surfaced, and to draft this issue from that work. I verified the failure modes against the consumer
repos, chose the dependabot shape over detection alone and over routing the work through an agent,
set the human-in-the-loop constraint, and edited the wording.