From 017736a6d20694a7ba4278c2ea4a37a69bb82b48 Mon Sep 17 00:00:00 2001 From: Cristian Magherusan-Stanciu Date: Thu, 28 May 2026 23:51:27 +0200 Subject: [PATCH 1/3] chore(ci): document required status checks + admin runbook (#377) Both branches are currently unprotected (HTTP 404 on the protection API), so the required-check cannot be added programmatically without repo-admin rights. Add docs/ci-required-checks.md with the exact gh api commands an admin must run to create the protection rule and add "Frontend build (PR)" to required checks on feat/multicloud-web-frontend and main. --- docs/ci-required-checks.md | 113 +++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 docs/ci-required-checks.md diff --git a/docs/ci-required-checks.md b/docs/ci-required-checks.md new file mode 100644 index 000000000..47d22aa0b --- /dev/null +++ b/docs/ci-required-checks.md @@ -0,0 +1,113 @@ +# CI Required Status Checks + +This document records the canonical set of required status checks for the +CUDly repository and the admin commands needed to enforce them. + +## Context + +PR #232 (merged 2026-05-03) added `.github/workflows/frontend-build.yml`, +which runs `npm ci`, `npm run typecheck`, and `npm run build` on every PR +touching `frontend/**`. The workflow shipped, but the corresponding +`Frontend build (PR)` check was never added to the branch-protection +required-checks list. A PR that breaks the frontend build can currently be +merged without a block (issue #377). + +## Required checks -- canonical list + +Both `feat/multicloud-web-frontend` and `main` should require: + +- `Frontend build (PR)` +- Any other checks already present at the time an admin applies this runbook + (retrieve the live list first; see Step 1 below). + +## Admin steps + +These commands require repo-admin permission on LeanerCloud/CUDly. + +### Step 1 -- retrieve the current required checks for each branch + +```bash +gh api repos/LeanerCloud/CUDly/branches/feat/multicloud-web-frontend/protection \ + --jq '.required_status_checks.contexts' + +gh api repos/LeanerCloud/CUDly/branches/main/protection \ + --jq '.required_status_checks.contexts' +``` + +If either returns `"Branch not protected"` (HTTP 404), the protection rule +must be created from scratch; use the `gh api -X PUT` form in Step 3. + +### Step 2 -- add the check to an already-protected branch + +Replace `EXISTING_CHECK_1` etc. with the contexts returned by Step 1: + +```bash +gh api -X PATCH \ + repos/LeanerCloud/CUDly/branches/feat/multicloud-web-frontend/protection/required_status_checks \ + -F 'contexts[]=EXISTING_CHECK_1' \ + -F 'contexts[]=Frontend build (PR)' + +gh api -X PATCH \ + repos/LeanerCloud/CUDly/branches/main/protection/required_status_checks \ + -F 'contexts[]=EXISTING_CHECK_1' \ + -F 'contexts[]=Frontend build (PR)' +``` + +### Step 3 -- create protection from scratch (if Step 1 returned 404) + +Adjust `required_pull_request_reviews` and `enforce_admins` to taste: + +```bash +gh api -X PUT \ + repos/LeanerCloud/CUDly/branches/feat/multicloud-web-frontend/protection \ + --input - <<'EOF' +{ + "required_status_checks": { + "strict": true, + "contexts": ["Frontend build (PR)"] + }, + "enforce_admins": false, + "required_pull_request_reviews": null, + "restrictions": null +} +EOF + +gh api -X PUT \ + repos/LeanerCloud/CUDly/branches/main/protection \ + --input - <<'EOF' +{ + "required_status_checks": { + "strict": true, + "contexts": ["Frontend build (PR)"] + }, + "enforce_admins": false, + "required_pull_request_reviews": null, + "restrictions": null +} +EOF +``` + +### Step 4 -- verify + +```bash +gh api repos/LeanerCloud/CUDly/branches/feat/multicloud-web-frontend/protection \ + --jq '.required_status_checks.contexts' + +gh api repos/LeanerCloud/CUDly/branches/main/protection \ + --jq '.required_status_checks.contexts' +``` + +Both should include `"Frontend build (PR)"`. + +### Step 5 -- smoke test + +Open a draft PR with a deliberate TypeScript error in `frontend/` and confirm +that the `Frontend build (PR)` check turns red and the merge button is blocked. + +## Notes + +- The `strict` flag in Step 3 requires the branch to be up to date before + merging; adjust if that is too strict for the current workflow. +- The GitHub UI path for the same change is: Settings > Branches > + Branch protection rules > Edit rule > "Require status checks to pass" > + search for `Frontend build (PR)` > save. From 1c2ac739f7f1b7afcc3374e7f229ea0918c68004 Mon Sep 17 00:00:00 2001 From: Cristian Magherusan-Stanciu Date: Sat, 6 Jun 2026 08:24:12 +0200 Subject: [PATCH 2/3] docs(ci): correct required-check context to job name 'Build frontend' (refs #377) GitHub branch-protection contexts use the job name:, not the workflow name:. The workflow is named 'Frontend build (PR)' but its single job is 'Build frontend', so the context an admin must register is 'Build frontend'. The doc had the wrong string throughout; an admin following it verbatim would add a non-existent context and branch protection would never block a failing frontend build. Also adds a note in the Context section explaining the workflow-name vs job-name distinction so future maintainers understand the correct string to use. --- docs/ci-required-checks.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/ci-required-checks.md b/docs/ci-required-checks.md index 47d22aa0b..a2323820e 100644 --- a/docs/ci-required-checks.md +++ b/docs/ci-required-checks.md @@ -8,15 +8,21 @@ CUDly repository and the admin commands needed to enforce them. PR #232 (merged 2026-05-03) added `.github/workflows/frontend-build.yml`, which runs `npm ci`, `npm run typecheck`, and `npm run build` on every PR touching `frontend/**`. The workflow shipped, but the corresponding -`Frontend build (PR)` check was never added to the branch-protection +`Build frontend` check was never added to the branch-protection required-checks list. A PR that breaks the frontend build can currently be merged without a block (issue #377). +> **Note on context naming**: GitHub branch-protection contexts are derived +> from the **job `name:`** field, not the workflow `name:` field. The workflow +> is named `Frontend build (PR)` but its single job is named `Build frontend`, +> so the context GitHub reports (and that must be entered here) is +> `Build frontend`. + ## Required checks -- canonical list Both `feat/multicloud-web-frontend` and `main` should require: -- `Frontend build (PR)` +- `Build frontend` - Any other checks already present at the time an admin applies this runbook (retrieve the live list first; see Step 1 below). @@ -45,12 +51,12 @@ Replace `EXISTING_CHECK_1` etc. with the contexts returned by Step 1: gh api -X PATCH \ repos/LeanerCloud/CUDly/branches/feat/multicloud-web-frontend/protection/required_status_checks \ -F 'contexts[]=EXISTING_CHECK_1' \ - -F 'contexts[]=Frontend build (PR)' + -F 'contexts[]=Build frontend' gh api -X PATCH \ repos/LeanerCloud/CUDly/branches/main/protection/required_status_checks \ -F 'contexts[]=EXISTING_CHECK_1' \ - -F 'contexts[]=Frontend build (PR)' + -F 'contexts[]=Build frontend' ``` ### Step 3 -- create protection from scratch (if Step 1 returned 404) @@ -64,7 +70,7 @@ gh api -X PUT \ { "required_status_checks": { "strict": true, - "contexts": ["Frontend build (PR)"] + "contexts": ["Build frontend"] }, "enforce_admins": false, "required_pull_request_reviews": null, @@ -78,7 +84,7 @@ gh api -X PUT \ { "required_status_checks": { "strict": true, - "contexts": ["Frontend build (PR)"] + "contexts": ["Build frontend"] }, "enforce_admins": false, "required_pull_request_reviews": null, @@ -97,12 +103,12 @@ gh api repos/LeanerCloud/CUDly/branches/main/protection \ --jq '.required_status_checks.contexts' ``` -Both should include `"Frontend build (PR)"`. +Both should include `"Build frontend"`. ### Step 5 -- smoke test Open a draft PR with a deliberate TypeScript error in `frontend/` and confirm -that the `Frontend build (PR)` check turns red and the merge button is blocked. +that the `Build frontend` check turns red and the merge button is blocked. ## Notes @@ -110,4 +116,4 @@ that the `Frontend build (PR)` check turns red and the merge button is blocked. merging; adjust if that is too strict for the current workflow. - The GitHub UI path for the same change is: Settings > Branches > Branch protection rules > Edit rule > "Require status checks to pass" > - search for `Frontend build (PR)` > save. + search for `Build frontend` > save. From 8baeef03f565272d97876deadd663dc3f30edc0f Mon Sep 17 00:00:00 2001 From: Cristian Magherusan-Stanciu Date: Fri, 19 Jun 2026 23:23:18 +0200 Subject: [PATCH 3/3] docs(ci): scope required-check runbook to main only The frontend-build.yml trigger for feat/multicloud-web-frontend was removed when that branch merged into main (commit 4f7d429a8). The Build frontend check therefore only fires on main-targeting PRs, so branch protection instructions for the retired branch are misleading. Removes the feat/multicloud-web-frontend commands from all four admin steps and the required-checks list; updates the Context section to explain why main is the only active target. --- docs/ci-required-checks.md | 37 ++++++++----------------------------- 1 file changed, 8 insertions(+), 29 deletions(-) diff --git a/docs/ci-required-checks.md b/docs/ci-required-checks.md index a2323820e..2c04b1fd6 100644 --- a/docs/ci-required-checks.md +++ b/docs/ci-required-checks.md @@ -12,6 +12,10 @@ touching `frontend/**`. The workflow shipped, but the corresponding required-checks list. A PR that breaks the frontend build can currently be merged without a block (issue #377). +The workflow targets the `main` branch only. The `feat/multicloud-web-frontend` +trigger was removed in the commit that merged that branch into `main` +(`4f7d429a8`), so `Build frontend` only ever runs for PRs targeting `main`. + > **Note on context naming**: GitHub branch-protection contexts are derived > from the **job `name:`** field, not the workflow `name:` field. The workflow > is named `Frontend build (PR)` but its single job is named `Build frontend`, @@ -20,7 +24,7 @@ merged without a block (issue #377). ## Required checks -- canonical list -Both `feat/multicloud-web-frontend` and `main` should require: +`main` should require: - `Build frontend` - Any other checks already present at the time an admin applies this runbook @@ -30,17 +34,14 @@ Both `feat/multicloud-web-frontend` and `main` should require: These commands require repo-admin permission on LeanerCloud/CUDly. -### Step 1 -- retrieve the current required checks for each branch +### Step 1 -- retrieve the current required checks for main ```bash -gh api repos/LeanerCloud/CUDly/branches/feat/multicloud-web-frontend/protection \ - --jq '.required_status_checks.contexts' - gh api repos/LeanerCloud/CUDly/branches/main/protection \ --jq '.required_status_checks.contexts' ``` -If either returns `"Branch not protected"` (HTTP 404), the protection rule +If this returns `"Branch not protected"` (HTTP 404), the protection rule must be created from scratch; use the `gh api -X PUT` form in Step 3. ### Step 2 -- add the check to an already-protected branch @@ -48,11 +49,6 @@ must be created from scratch; use the `gh api -X PUT` form in Step 3. Replace `EXISTING_CHECK_1` etc. with the contexts returned by Step 1: ```bash -gh api -X PATCH \ - repos/LeanerCloud/CUDly/branches/feat/multicloud-web-frontend/protection/required_status_checks \ - -F 'contexts[]=EXISTING_CHECK_1' \ - -F 'contexts[]=Build frontend' - gh api -X PATCH \ repos/LeanerCloud/CUDly/branches/main/protection/required_status_checks \ -F 'contexts[]=EXISTING_CHECK_1' \ @@ -64,20 +60,6 @@ gh api -X PATCH \ Adjust `required_pull_request_reviews` and `enforce_admins` to taste: ```bash -gh api -X PUT \ - repos/LeanerCloud/CUDly/branches/feat/multicloud-web-frontend/protection \ - --input - <<'EOF' -{ - "required_status_checks": { - "strict": true, - "contexts": ["Build frontend"] - }, - "enforce_admins": false, - "required_pull_request_reviews": null, - "restrictions": null -} -EOF - gh api -X PUT \ repos/LeanerCloud/CUDly/branches/main/protection \ --input - <<'EOF' @@ -96,14 +78,11 @@ EOF ### Step 4 -- verify ```bash -gh api repos/LeanerCloud/CUDly/branches/feat/multicloud-web-frontend/protection \ - --jq '.required_status_checks.contexts' - gh api repos/LeanerCloud/CUDly/branches/main/protection \ --jq '.required_status_checks.contexts' ``` -Both should include `"Build frontend"`. +The output should include `"Build frontend"`. ### Step 5 -- smoke test