Create a branch that is missing in the fork

[pytooling-claude]

Rebased onto dev after #1 was merged; the base was retargeted automatically.

New Features

• A branch listed in an <organisation>.repos file that the fork doesn't have is created, from the upstream
  repository's branch head, and the next run synchronizes it like any other branch.

  gh repo sync updates a branch; it can't create one. So a branch added upstream after the fork was made — or every
  branch but one, when the fork was made with Copy the default branch only — could never be synchronized: the entry
  in the configuration file simply failed on every run, for ever.

    📂 OSVVM/AXI4 ⇒ PLC2/OSVVM-AXI4
      🌱 dev — created from OSVVM/AXI4@a1b2c3d
  

• create-missing-branches enables it. It is false by default (second commit, on your call): the branch head
  is read from <upstream>, so a stale or copy-pasted upstream would create the branch from the wrong repository, and
  each repository should enable it once its configuration file has been checked. While disabled, a missing branch is a
  counted error naming the parameter — which is already an improvement, because it says why the branch can't be
  synchronized. created is a new output parameter and a new line in the summary.

Changes

• The mechanism is one API call, not fetch/push. You suggested fetch/pull/push; I checked whether the shorter path
  works first, and it does — GitHub keeps a fork and its upstream in one object network, so the upstream's commit
  is addressable through the fork and POST /repos/<fork>/git/refs accepts it directly.

  Verified read-only against real repositories before writing the code: ghdl/ghdl's rust branch is
  fa173d3bed630ee51f8c62426a12dd4748142a59, Paebbels/ghdl has no rust ref (GET .../git/ref/heads/rust →
  404), and yet GET /repos/Paebbels/ghdl/commits/fa173d3… returns that commit. The object is already there; only the
  ref is missing.

  That avoids cloning a repository per fork on the runner. A shallow fetch wouldn't help either — GitHub rejects a
  push from a shallow clone ("shallow update not allowed"), so the fetch/push route would pull GHDL's full history
  onto the runner to upload objects GitHub already has. If you'd rather have the git route regardless, it's a
  self-contained replacement of one function.

• <upstream> becomes functional. Until now it was reported; it is now the repository the new branch's head is
  read from.

  This is why the parameter defaults to false. PLC2/Synchronize and VHDL/Synchronize name OSVVM/osvvm as the
  upstream on every line of their OSVVM.repos — 14 and 13 forks. GitHub resolves repository names
  case-insensitively, so OSVVM/osvvm is a real repository, and a missing branch in any of those 27 forks would
  otherwise be created from the wrong one. Enable the parameter per repository, after its file has been corrected.

• The fork's branch is checked before synchronizing, one gh api read per branch, rather than after a failed sync.
  It costs ~50 reads per day for a namespace the size of Paebbels, and in exchange the missing-branch case doesn't
  depend on parsing gh's error text, and a doomed gh repo sync isn't run at all. Dry-run mode is unchanged and
  still reads nothing.

Bug Fixes

• The case above is the bug: a configured branch missing from the fork was a permanent, self-repeating error, with no
  path to a green run other than editing the configuration file or clicking through the GitHub UI.

Documentation

• README.md gains a Missing Branches section — what gh repo sync can't do, what the action does instead, why
  <upstream> matters now, and the escape hatch. The parameter tables, the sample log and the summary block are
  updated.

Unit Tests

• check-outputs verifies created too, and both verification jobs assert it.
• The workflow can't reach this path: dry-run deliberately touches no repository, and a real run would need a fork
  and a token. Four cases in the local harness cover it instead, against a stub gh that answers git/ref/heads
  with 404 for a configured set of refs:
  • a branch missing in the fork → created, created=1, the POST carries ref=refs/heads/dev and the upstream SHA,
    and gh repo sync is not called for it,
  • missing in the fork and upstream → one counted error, no POST,
  • the default, create-missing-branches: false → counted error naming the parameter, and the upstream isn't even
    read,
  • a POST that fails → the message is quoted, annotated with %0A escaping, and the fork appears in
    Not synchronized:.
• All 14 cases in the harness pass (10 from Add the 'SynchronizeForks' composite action #1, 4 new).

---

Related Issues and Pull-Requests

• Follows Add the 'SynchronizeForks' composite action #1 (merged).
• Sibling: Synchronize tags #3 synchronizes tags. Both touch the per-repository loop in action.yml; whichever merges second rebases.

🤖 Generated with Claude Code