ci: keep release PRs rebased, stagger integration jobs, allow an App token

Merging one release PR left the other two CONFLICTING. All three edit the
shared .release-please-manifest.json, and by default Release Please
rewrites a release branch only when the generated release notes change —
so a straggler kept a stale base, and neither the post-merge run nor an
explicit workflow_dispatch repaired it. always-update is the supported
option for exactly this ("can be useful if pull requests must not be
out-of-date with the base branch"); it costs extra API calls per run,
which is nothing at three charts. Needs release-please >= 16.15.0 and the
action pins ^17.6.1.

Stagger the integration matrix. Five jobs starting together pull the same
large image from five clusters at once, out of the shared IP range
GitHub-hosted runners use, which registries rate limit against. This is
the suspected cause of the 2026-08-13 stalls; still unproven, and the
diagnostics added alongside it will say either way.

Let Release Please author its PRs as a GitHub App. A GITHUB_TOKEN PR
cannot start workflow runs, so release PR checks wait on manual approval
and Integration Tests — push-triggered — never covers a release PR at
all. The step is skipped when the variable is unset and the action falls
back to GITHUB_TOKEN, so this changes nothing until an App is configured.

Author: attilaedelenyi

.github/workflows/integration-tests.yml

@@ -34,6 +34,11 @@ jobs:
     timeout-minutes: 40
     strategy:
       fail-fast: false
+      # Five jobs starting at once means five k3d clusters pulling the same large Ontoserver image
+      # simultaneously, from the shared IP range GitHub-hosted runners use — which registries rate
+      # limit against. Staggering trades wall-clock for a much smaller burst. Suspected (not proven)
+      # cause of the 2026-08-13 install stalls; the diagnostics added alongside this will say.
+      max-parallel: 2
       matrix:
         mode:
           - name: read-only

.github/workflows/release-please.yml

@@ -32,9 +32,26 @@ jobs:
       # publish job fans out over.
       paths_released: ${{ steps.release.outputs.paths_released }}
     steps:
+      # A PR opened with the default GITHUB_TOKEN cannot start workflow runs (GitHub's recursion
+      # guard). The visible cost on a release PR: its `pull_request` checks sit at action_required
+      # waiting for a human to approve them, and Integration Tests — which triggers on `push` only —
+      # never runs against a release PR at all. Authoring the PR as a GitHub App instead makes both
+      # events fire normally.
+      #
+      # Optional by design: with the variable unset this step is skipped and the action falls back to
+      # GITHUB_TOKEN, exactly as before. Set the repo variable RELEASE_PLEASE_APP_ID and the secret
+      # RELEASE_PLEASE_APP_PRIVATE_KEY to switch over — no workflow edit needed. See RELEASE.md.
+      - uses: actions/create-github-app-token@v2
+        id: app-token
+        if: vars.RELEASE_PLEASE_APP_ID != ''
+        with:
+          app-id: ${{ vars.RELEASE_PLEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_PLEASE_APP_PRIVATE_KEY }}
+
       - uses: googleapis/release-please-action@v4
         id: release
         with:
+          token: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json
 

CLAUDE.md

@@ -25,9 +25,9 @@ The traps, in short:
 - **`artifacthub.io/changes` in `Chart.yaml` is hand-maintained** and Release Please does not update
   it, so it goes stale silently after a release.
 
-- **Merging one release PR conflicts the others.** All three edit `.release-please-manifest.json`,
-  and Release Please will *not* rebase them for you — it only rewrites a release branch when the
-  generated release content changes. Rebase by hand; the resolution is always the union of the
-  versions. See the recovery section in `RELEASE.md`.
+- **Merging one release PR used to conflict the others**, because all three edit
+  `.release-please-manifest.json`. Fixed by `always-update: true` in `release-please-config.json`;
+  without it Release Please rewrites a release branch only when the generated *release notes*
+  change, so a straggler keeps a stale base and conflicts. Don't remove that flag.
 
 Current releases: `ontoserver` 0.4.1, `ontoserver-extras` 0.1.2, `ontoserver-indexer` 0.2.1.

RELEASE.md

@@ -7,6 +7,7 @@ normal path; everything else in this document is fallback and recovery.
 - [How the three charts stay separate](#how-the-three-charts-stay-separate)
 - [What lands where](#what-lands-where)
 - [Conventions you must not break](#conventions-you-must-not-break)
+- [Release PRs and workflow approval (GitHub App token)](#release-prs-and-workflow-approval-github-app-token)
 - [Manual release (`release.sh`)](#manual-release-releasesh)
 - [Recovery](#recovery)
 - [Artifact Hub](#artifact-hub)
@@ -61,6 +62,10 @@ scope.** This is the single most important thing to understand:
 Practical consequence: **keep a commit to one chart** where you can. A commit that sweeps all three
 charts forces all three to release together.
 
+- `always-update: true` keeps the open release PRs rebased on `master` as each one merges. All three
+  edit the shared `.release-please-manifest.json`, so without it merging one leaves the rest
+  conflicting — see [Recovery](#a-release-pr-conflicts-after-another-one-merged).
+
 Configuration lives in `release-please-config.json` (what the packages are) and
 `.release-please-manifest.json` (what version each is currently at).
 
@@ -138,6 +143,29 @@ up the runs by commit SHA and polls for up to 10 minutes if one is still in flig
 
 If the gate reports *no run found*, the commit was never pushed to a branch. Push it before tagging.
 
+## Release PRs and workflow approval (GitHub App token)
+
+A PR opened with the default `GITHUB_TOKEN` cannot trigger workflow runs — GitHub's recursion guard.
+On a release PR that shows up two ways:
+
+- its `pull_request` checks queue at **action_required** until a human clicks approve;
+- **Integration Tests never runs on a release PR at all**, because it triggers on `push` only and
+  the bot's push is suppressed. The suite only runs after the merge, against master.
+
+`release-please.yml` will author its PRs as a GitHub App when one is configured, which makes both
+events fire normally. It is optional: with the variable unset the step is skipped and the action
+falls back to `GITHUB_TOKEN`, behaving exactly as before. To switch over — no workflow edit needed:
+
+1. Create a GitHub App under the **aehrc** org (Settings → Developer settings → GitHub Apps).
+   Permissions: **Contents: Read and write**, **Pull requests: Read and write**,
+   **Issues: Read and write** (Release Please labels its PRs, and labels are the issues API).
+2. Install it on `aehrc/ontoserver-deploy`, and generate a private key.
+3. Add repo **variable** `RELEASE_PLEASE_APP_ID` (the numeric App ID) and repo **secret**
+   `RELEASE_PLEASE_APP_PRIVATE_KEY` (the whole PEM, `BEGIN`/`END` lines included).
+
+Verify by pushing a chart change: the release PR's author becomes the App, and its checks — now
+including Integration Tests — start without an approval prompt.
+
 ## Manual release (`release.sh`)
 
 Kept for recovery and for releasing from a feature branch. **It still follows the old convention** —
@@ -221,14 +249,24 @@ git push origin gh-pages
 
 ### A release PR conflicts after another one merged
 
-Every release PR edits `.release-please-manifest.json`, so merging one leaves the others
-`CONFLICTING`. **Release Please does not fix this for you** — it rewrites a release branch only when
-the *generated release content* changes, and a straggler's content has not changed, so both the
-post-merge run and an explicit `workflow_dispatch` leave the stale branch alone (observed
-2026-08-13).
+Every release PR edits `.release-please-manifest.json`, so merging one used to leave the others
+`CONFLICTING`. **`always-update: true` in `release-please-config.json` fixes this** — it is the
+supported option for exactly this case:
+
+> if true, always update existing pull requests when changes are added, instead of only when the
+> release notes change. […] can be useful if pull requests must not be out-of-date with the base
+> branch.
+
+The default is `false`, which only rewrites a release branch when the *generated release notes*
+change. Merging extras changes the shared manifest but not the indexer's notes, so the straggler was
+left pointing at a stale base — and neither the post-merge run nor an explicit `workflow_dispatch`
+repaired it (observed 2026-08-13, before the option was set). It costs extra API calls per run,
+which is irrelevant at three charts.
+
+Requires release-please ≥ 16.15.0; `release-please-action@v4` depends on `^17.6.1`, so it is live.
 
-Rebase it by hand. The resolution is always the union: each chart's own new version, plus whatever
-the merged release just published.
+If you ever hit a conflict anyway, rebase by hand. The resolution is always the union: each chart's
+own new version, plus whatever the merged release just published.
 
 ```bash
 BR=release-please--branches--master--components--<chart>

release-please-config.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
   "separate-pull-requests": true,
+  "always-update": true,
   "packages": {
     "charts/ontoserver": {
       "release-type": "helm",