From bec21fd810743dae550340b8b0bfbc981ad70bfc Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Fri, 23 Jan 2026 16:15:16 +0000
Subject: [PATCH] docs: add guide for cancelling CI runs and improve script

- Updates `scripts/cancel-all-ci-runs.sh` with a safer, more robust version that handles repository detection and `xargs` limitations.
- Adds `docs/cancelling-ci-runs.md` explaining how to use the script.
- Links the new documentation in `README.md` under Quickstart Commands.

Co-authored-by: PR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
---
 README.md                     |  1 +
 docs/cancelling-ci-runs.md    | 53 +++++++++++++++++++++++++++++++++++
 scripts/cancel-all-ci-runs.sh | 20 ++++++++++---
 3 files changed, 70 insertions(+), 4 deletions(-)
 create mode 100644 docs/cancelling-ci-runs.md

diff --git a/README.md b/README.md
index 72fe7be6..70585d26 100644
--- a/README.md
+++ b/README.md
@@ -139,6 +139,7 @@ http://localhost:8000
 - **Run DM unit tests**: `npm run test:dm:unit`
 - **Run DM integration tests**: `npm run test:dm:integration`
 - **Run headless E2E tests**: `npm run test:e2e`
+- **Cancel CI runs**: See [`docs/cancelling-ci-runs.md`](docs/cancelling-ci-runs.md) for a script to clear pending workflows.
 
 ### Running Tests in Docker
 
diff --git a/docs/cancelling-ci-runs.md b/docs/cancelling-ci-runs.md
new file mode 100644
index 00000000..7d2276e3
--- /dev/null
+++ b/docs/cancelling-ci-runs.md
@@ -0,0 +1,53 @@
+# Cancelling CI Runs
+
+This document explains how to use the `scripts/cancel-all-ci-runs.sh` script to cancel pending or in-progress CI workflows. This is useful when you have a backlog of runs that are no longer needed.
+
+## Prerequisites
+
+- **GitHub CLI (`gh`)**: You must have the GitHub CLI installed and authenticated.
+  - Install: [GitHub CLI Installation Guide](https://github.com/cli/cli#installation)
+  - Authenticate: `gh auth login`
+
+## Usage
+
+### Basic Usage (Repo Root)
+
+From the root of the repository, you can simply run:
+
+```bash
+./scripts/cancel-all-ci-runs.sh
+```
+
+The script will automatically detect the repository from your git configuration.
+
+### Running from Anywhere
+
+You can run the script from any directory by setting the `REPO` environment variable:
+
+```bash
+REPO=PR0M3TH3AN/bitvid ./scripts/cancel-all-ci-runs.sh
+```
+
+### Previewing Runs
+
+Before cancelling, you might want to see which runs are currently active. You can use the following commands:
+
+```bash
+# List in-progress runs
+gh run list --repo PR0M3TH3AN/bitvid --status in_progress --limit 1000 --json databaseId,headBranch,name,createdAt | jq .
+
+# List queued runs
+gh run list --repo PR0M3TH3AN/bitvid --status queued --limit 1000 --json databaseId,headBranch,name,createdAt | jq .
+```
+
+## How it Works
+
+The script performs the following steps:
+1.  Checks if `gh` is installed.
+2.  Determines the repository (either from `REPO` env var or `gh repo view`).
+3.  Fetches IDs of all runs with status `in_progress` and `queued`.
+4.  Cancels them one by one using `gh run cancel`.
+
+### Why use this script?
+
+Trying to cancel runs in bulk using `xargs gh run cancel` directly can fail because some versions of `gh` only accept a single run ID per invocation. This script uses `xargs -n1` to ensure `gh run cancel` is called individually for each run ID, preventing "accepts at most 1 arg(s)" errors.
diff --git a/scripts/cancel-all-ci-runs.sh b/scripts/cancel-all-ci-runs.sh
index 187c53f6..8ccbec24 100755
--- a/scripts/cancel-all-ci-runs.sh
+++ b/scripts/cancel-all-ci-runs.sh
@@ -1,4 +1,5 @@
 #!/bin/bash
+set -euo pipefail
 
 # Check if gh is installed
 if ! command -v gh &> /dev/null
@@ -7,6 +8,18 @@ then
     exit 1
 fi
 
+# Allow override with REPO=owner/repo
+REPO="${REPO:-}"
+if [ -z "$REPO" ]; then
+  # try to discover the repo from the current git folder
+  REPO="$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || true)"
+  if [ -z "$REPO" ]; then
+    echo "Unable to determine repository. Either run this inside the repo or set REPO=owner/repo"
+    exit 1
+  fi
+fi
+
+echo "Repo: $REPO"
 echo "Fetching active runs..."
 
 # Function to cancel runs by status
@@ -14,14 +27,13 @@ cancel_runs() {
     local status=$1
     echo "Cancelling $status runs..."
     # Use --limit 1000 to capture up to 1000 runs (default is 30)
-    ids=$(gh run list --status "$status" --limit 1000 --json databaseId -q '.[].databaseId')
+    ids=$(gh run list --repo "$REPO" --status "$status" --limit 1000 --json databaseId -q '.[].databaseId')
 
     if [ -z "$ids" ]; then
         echo "No $status runs found."
     else
-        # Pass IDs to xargs to batch cancel commands
-        # gh run cancel accepts multiple arguments
-        echo "$ids" | xargs gh run cancel
+        # Call gh run cancel once per id (some gh versions accept only one id per call)
+        printf '%s\n' "$ids" | xargs -r -n1 -I{} gh run cancel --repo "$REPO" {}
     fi
 }