ci(port): open port PRs with a GitHub App so their checks actually count

Branch protection on main requires six status checks, and only pull_request-event
runs satisfy them. GitHub does not trigger workflows from events created with the
native GITHUB_TOKEN (recursion guard), so a PR opened with it gets no
pull_request checks and can never become mergeable — the automated port PR would
sit permanently stuck.

The previous workaround dispatched ci.yaml at the PR branch. That does not work,
and I measured it rather than assuming: on PR #24 the commit carried 14
check-runs while the PR's rollup showed 7. A workflow_dispatch run of the same
workflow, on the same commit, succeeding, was entirely invisible to branch
protection.

(I also had to correct myself here. I first claimed dispatch runs never attach,
citing runs on LukasParke/e2e-CI — but that PR was already merged and closed when
they ran, so nothing would have shown regardless. Retested on an open PR: 7 checks
before the dispatch, 7 after. Same conclusion, real evidence.)

Also verified that dropping the PR requirement does not help. On a throwaway
protected branch with required checks and no PR requirement, a direct push is
rejected outright:

  remote: error: GH006: Protected branch update failed
  remote: - Required status check "types" is expected.

Required checks gate pushes too, so there is no configuration of branch
protection that lets GITHUB_TOKEN-created work through while keeping the gates.

An App installation token is not recursion-guarded, so the PR it opens gets real
checks. Preferred over a PAT: scoped to this repo, not tied to a personal account,
revocable on its own.

- New "Mint App token" step (actions/create-github-app-token@v1), gated on
  vars.PORT_BOT_APP_ID being set.
- create-pull-request uses the App token when present, GITHUB_TOKEN otherwise.
- The dispatch step is now a FALLBACK, running only when no App token was minted,
  and it emits a ::warning:: stating plainly that the PR will get no checks and
  cannot merge as-is. An unconfigured bot should degrade loudly rather than look
  healthy while producing permanently stuck PRs.

Setup is documented in PORTING.md: App with Contents + Pull requests read/write
(nothing else), installed on this repo, then PORT_BOT_APP_ID (variable) and
PORT_BOT_PRIVATE_KEY (secret). Neither exists yet, so the fallback path is what
runs until they are added.

Verification: all three workflows parse · mint step gated correctly · PR token
falls back as intended · verify.sh PASS (0 failures) · 114 passed.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: LukasParke

.github/workflows/upstreamer-port.yaml

@@ -142,12 +142,40 @@ jobs:
             echo "passed=true" >> "$GITHUB_OUTPUT"
           fi
 
+      # Mint a GitHub App installation token so the PR is created by the App
+      # rather than by the native GITHUB_TOKEN.
+      #
+      # Why this exists: GitHub does not trigger workflows from events created
+      # with GITHUB_TOKEN (recursion guard), so a PR opened with it gets no
+      # pull_request-event checks — and `main`'s required status checks are
+      # satisfied ONLY by pull_request-event runs. Measured on PR #24: the commit
+      # had 14 check-runs, the PR's rollup showed 7; the workflow_dispatch half was
+      # invisible to branch protection. So the previous "dispatch ci.yaml
+      # explicitly" workaround produced green runs that could never satisfy the
+      # required checks, leaving an automated port PR permanently unmergeable.
+      #
+      # An App installation token is not recursion-guarded, so the PR gets real
+      # pull_request checks. Preferred over a PAT: scoped to this repo, not tied to
+      # a person's account, and independently revocable.
+      #
+      # Optional by design — see the fallback below.
+      - name: Mint App token
+        id: app-token
+        if: steps.diff.outputs.changed == 'true' && vars.PORT_BOT_APP_ID != ''
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ vars.PORT_BOT_APP_ID }}
+          private-key: ${{ secrets.PORT_BOT_PRIVATE_KEY }}
+
       - name: Open PR
         id: open-pr
         if: steps.diff.outputs.changed == 'true'
         uses: peter-evans/create-pull-request@v6
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+          # App token when configured; GITHUB_TOKEN otherwise. With the fallback
+          # the PR still opens, but its checks will not attach — the guard step
+          # below says so loudly rather than leaving a silently stuck PR.
+          token: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
           branch: upstreamer/sync
           delete-branch: true
           title: >-
@@ -172,16 +200,23 @@ jobs:
             `.upstreamer/state.yaml` did not advance, the eval did not pass and this
             PR must not be merged as-is.
 
-      # Events created with the native GITHUB_TOKEN deliberately do not trigger
-      # other workflows (GitHub's recursion guard), so the PR opened above gets
-      # no CI checks on its own. workflow_dispatch is exempt from that guard:
-      # kick ci.yaml at the PR branch explicitly. This keeps the whole pipeline
-      # on the native token — no PAT anywhere in this repo.
-      - name: Trigger CI on the port PR
-        if: steps.diff.outputs.changed == 'true' && steps.open-pr.outputs.pull-request-operation != 'none'
+      # Fallback path only. With the App configured, the PR above already has real
+      # pull_request checks and nothing here runs.
+      #
+      # Without it, the PR exists but can never satisfy `main`'s required checks.
+      # Dispatching ci.yaml still gives a human something to read, but the run does
+      # NOT attach to the PR — so say that plainly instead of leaving a green-looking
+      # PR that will not merge and no explanation of why.
+      - name: Trigger CI on the port PR (no App token — checks will not attach)
+        if: >-
+          steps.diff.outputs.changed == 'true'
+          && steps.open-pr.outputs.pull-request-operation != 'none'
+          && steps.app-token.outputs.token == ''
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: gh workflow run ci.yaml --repo "$GITHUB_REPOSITORY" --ref upstreamer/sync
+        run: |
+          echo "::warning::PORT_BOT_APP_ID / PORT_BOT_PRIVATE_KEY are not configured, so this PR was opened with GITHUB_TOKEN and will receive NO pull_request-event checks. main's required status checks cannot be satisfied, so the PR cannot merge as-is. The dispatched run below is informational only. Configure the App (see PORTING.md) or close and reopen the PR by hand to generate real checks."
+          gh workflow run ci.yaml --repo "$GITHUB_REPOSITORY" --ref upstreamer/sync
 
       - name: Upload logs
         if: always()

PORTING.md

@@ -29,7 +29,8 @@ scripts/upstream
         │  6. .upstreamer/eval.md            (parity gate, fresh context)
         │  7. advance state.yaml — ONLY if both gates pass
         ▼
-    Pull request  (never a direct push to main)
+    Pull request, opened by the GitHub App so it gets real
+    pull_request-event CI checks  (never a direct push to main)
 ```
 
 ### Why HEAD and not the latest release
@@ -132,6 +133,42 @@ Two values, same names locally and in CI:
 | `OPENROUTER_API_KEY` | local: `.upstreamer/port.env` · CI: repo **secret** | `sk-or-…` key opencode uses for inference |
 | `OPENCODE_MODEL` | local: `.upstreamer/port.env` · CI: repo **variable** | e.g. `openrouter/~anthropic/claude-opus-latest` |
 
+Two more are needed in CI only, for the bot that opens port PRs:
+
+| Name | Kind | What |
+|------|------|------|
+| `PORT_BOT_APP_ID` | repo **variable** | The GitHub App's App ID |
+| `PORT_BOT_PRIVATE_KEY` | repo **secret** | The App's generated private key (full PEM, including the BEGIN/END lines) |
+
+### Why a GitHub App is required, not optional
+
+`main` requires six status checks, and **only `pull_request`-event runs satisfy
+them**. GitHub does not trigger workflows from events created with the native
+`GITHUB_TOKEN` (its recursion guard), so a PR opened with that token gets no
+`pull_request` checks and can never become mergeable.
+
+Measured on PR #24: the commit carried **14 check-runs, while the PR's rollup
+showed 7** — a `workflow_dispatch` run of the same workflow on the same commit was
+completely invisible to branch protection. That is why "just dispatch `ci.yaml`
+at the branch" does not work; it produces green runs that cannot satisfy anything.
+
+An App installation token is not recursion-guarded, so the PR it opens gets real
+checks. Preferred over a PAT: scoped to this repo, not tied to anyone's personal
+account, and revocable on its own.
+
+**Setup** — create a GitHub App (org Settings → Developer settings → GitHub Apps):
+
+- Repository permissions: **Contents: Read and write**, **Pull requests: Read and
+  write**. Nothing else.
+- Install it on `OpenRouterTeam/python-agent`.
+- Generate a private key, then add `PORT_BOT_APP_ID` (variable) and
+  `PORT_BOT_PRIVATE_KEY` (secret).
+
+Until those exist the pipeline still runs and still opens a PR, but emits a
+`::warning::` saying the PR will receive no checks and cannot merge as-is. That is
+deliberate — an unconfigured bot should degrade loudly, not look healthy while
+producing permanently stuck PRs.
+
 The wrapper writes the key into `~/.local/share/opencode/auth.json` so headless
 runs work without the interactive `opencode /connect` flow.