ci(platform): add on-demand backend CI run (workflow_dispatch) with optional PR coverage refresh

.github/workflows/platform-backend-ci.yml

@@ -16,6 +16,20 @@ on:
       - "autogpt_platform/backend/**"
       - "autogpt_platform/autogpt_libs/**"
   merge_group:
+  # On-demand run of the full backend test + coverage suite for any branch.
+  # Useful when a branch's changes don't match the paths filter above (so the
+  # automatic push/pull_request runs are skipped) but you still want to run the
+  # suite and produce a fresh coverage upload for that branch's HEAD commit.
+  #   gh workflow run platform-backend-ci.yml --ref <branch>
+  # Pass pr_number to attach the coverage upload to an open PR (refreshes that
+  # PR's codecov/project/platform-backend status):
+  #   gh workflow run platform-backend-ci.yml --ref <branch> -f pr_number=<PR#>
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: "Open PR number to attach this coverage upload to (refreshes that PR's codecov status). Leave blank for a plain branch run."
+        required: false
+        type: string
 
 concurrency:
   group: ${{ format('backend-ci-{0}', github.head_ref && format('{0}-{1}', github.event_name, github.event.pull_request.number) || github.sha) }}
@@ -395,6 +409,11 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
           flags: platform-backend
           files: ./autogpt_platform/backend/coverage.xml
+          # On a manual workflow_dispatch, attach the upload to the given PR so
+          # codecov re-evaluates that PR's project status against its base.
+          # Empty for all automatic events (push/pull_request/merge_group), so
+          # their normal PR/commit detection is unchanged.
+          override_pr: ${{ github.event_name == 'workflow_dispatch' && inputs.pr_number || '' }}
 
     env:
       CI: true

autogpt_platform/backend/TESTING.md

@@ -274,6 +274,47 @@ Snapshot tests work in CI by:
 2. CI compares against committed snapshots
 3. Fails if snapshots don't match
 
+### Running backend CI on demand
+
+The backend CI workflow (`.github/workflows/platform-backend-ci.yml`) also supports a
+manual `workflow_dispatch` trigger, so you can run the full lint / type-check / test +
+coverage suite against any branch without pushing a new commit:
+
+```bash
+gh workflow run platform-backend-ci.yml --ref <branch>
+```
+
+This runs the same `test` job as the automatic triggers, including the coverage upload
+to Codecov for that branch's HEAD commit.
+
+When it's useful:
+- The automatic `push` / `pull_request` runs are **path-filtered** (they only fire when
+  the change touches `autogpt_platform/backend/**`, `autogpt_platform/autogpt_libs/**`,
+  the workflow file, or the lockfile script). A branch that changes only frontend/docs
+  never triggers backend CI — a manual run lets you exercise the backend suite anyway.
+- It produces a **fresh backend coverage upload** for a branch that didn't otherwise run
+  backend CI (for example, to refresh coverage on a long-lived branch).
+
+#### Refreshing an open PR's coverage status
+
+If the branch has an open PR, pass `pr_number` so the upload is attached to that PR and
+Codecov re-evaluates its `codecov/project/platform-backend` status against the PR base:
+
+```bash
+gh workflow run platform-backend-ci.yml --ref <pr-head-branch> -f pr_number=<PR#>
+```
+
+This is handy when a PR's `codecov/project/platform-backend` check is red only because
+the branch never ran backend CI (so Codecov is comparing stale carried-forward coverage);
+a dispatch with `pr_number` produces a current upload for the PR head and refreshes the
+check. Internally this sets the Codecov action's `override_pr`; for all automatic events
+it is left empty, so normal PR/commit detection is unchanged.
+
+> Note: `workflow_dispatch` is only available once the trigger exists on the repository's
+> **default branch** (`master`); dispatching another branch with `--ref` still requires
+> that. The `pr_number` / `override_pr` refresh path therefore can't be exercised until
+> this change reaches `master` — validate it with one real dispatch then.
+
 ## Troubleshooting
 
 ### Snapshot Mismatches