refactor: replace get_all_pages with gh_api_paginate and use err() helper

- Replace 52-line hand-rolled get_all_pages() paginator in
  github-close-archived-repo-security-alerts with gh_api_paginate
  streaming via 'while read'; non-array responses (e.g. Advanced
  Security not enabled) silently filtered by select(.number)
- Replace print_error + exit 1 two-liners with err() across 9 scripts
  (17 sites); two multi-message sites merged into single err() calls
- Merge CI shellcheck and unit-test jobs into one job to eliminate
  duplicate checkout + apt-get update; update ci-skip.yml to match
- Merge two apt-get steps in copilot-setup-steps.yml into one
- Remove ~96 lines of verbatim-duplicate content from AGENTS.md
  (script anatomy, helpers table, adding-a-script steps); replace with
  cross-reference to .github/copilot-instructions.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: locus313

.github/workflows/ci-skip.yml

@@ -1,10 +1,11 @@
 name: CI
 
 # Companion to ci.yml. When a pull request only touches documentation or other
-# path-ignored files, ci.yml is skipped entirely and its required "Shellcheck"
-# check never reports — which blocks the PR from merging. This workflow runs on
-# exactly those ignored paths and emits a passing check with the same job name,
-# so the required status is always satisfied without a manual bypass.
+# path-ignored files, ci.yml is skipped entirely and its required
+# "Shellcheck + Unit Tests" check never reports — which blocks the PR from
+# merging. This workflow runs on exactly those ignored paths and emits a passing
+# check with the same job name, so the required status is always satisfied
+# without a manual bypass.
 
 on:
   pull_request:
@@ -14,8 +15,8 @@ on:
       - '.github/FUNDING.yml'
 
 jobs:
-  shellcheck:
-    name: Shellcheck
+  ci:
+    name: Shellcheck + Unit Tests
     runs-on: ubuntu-latest
     permissions:
       contents: read

.github/workflows/ci.yml

@@ -15,17 +15,17 @@ on:
       - '.github/FUNDING.yml'
 
 jobs:
-  shellcheck:
-    name: Shellcheck
+  ci:
+    name: Shellcheck + Unit Tests
     runs-on: ubuntu-latest
     permissions:
       contents: read
     steps:
       - name: Checkout code
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
-      - name: Install shellcheck
-        run: sudo apt-get update -qq && sudo apt-get install -y shellcheck
+      - name: Install shellcheck and bats
+        run: sudo apt-get update -qq && sudo apt-get install -y shellcheck bats
 
       - name: Run shellcheck on all scripts
         run: |
@@ -34,17 +34,5 @@ jobs:
             --exclude=SC2034,SC1091 \
             --shell=bash
 
-  test:
-    name: Unit Tests
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-
-      - name: Install bats
-        run: sudo apt-get update -qq && sudo apt-get install -y bats
-
       - name: Run unit tests
         run: bats tests/

.github/workflows/copilot-setup-steps.yml

@@ -10,11 +10,8 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
-      - name: Install jq
-        run: sudo apt-get update -qq && sudo apt-get install -y jq
-
-      - name: Install shellcheck
-        run: sudo apt-get install -y shellcheck
+      - name: Install jq, shellcheck, and bats
+        run: sudo apt-get update -qq && sudo apt-get install -y jq shellcheck bats
 
       - name: Install gitleaks
         run: |

AGENTS.md

@@ -136,106 +136,10 @@ Use `_mock_curl_200` (defined in `test_script_validation.bats`) when a test must
 
 ## Key Patterns and Conventions
 
-### Script anatomy
-
-Every script begins with a `# ===` header (exactly 79 `=` chars), then immediately `set -euo pipefail`:
-
-```bash
-#!/usr/bin/env bash
-# =============================================================================
-# github-<name>.sh
-#
-# <description>
-#
-# Usage:
-#   export GITHUB_TOKEN=ghp_yourtoken
-#   export ORG=my-org
-#   ./github-<name>.sh
-#
-# Environment variables:
-#   GITHUB_TOKEN    Required. PAT with <scope> scope
-#   ORG             Required. GitHub organization name
-#   API_URL_PREFIX  Optional. GitHub API base URL (default: https://api.github.com)
-#
-# Requirements:
-#   - curl
-#   - jq
-# =============================================================================
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=../../lib/github-common.sh
-source "${SCRIPT_DIR}/../../lib/github-common.sh"
-```
-
-### Sourcing the shared library
-
-Always use `SCRIPT_DIR` to build the path to `lib/github-common.sh`. The library is two directory levels up from any script (`../../lib/github-common.sh`). Never hardcode absolute paths.
-
-### Authentication
-
-- Standard org/repo REST calls: `Authorization: token ${GITHUB_TOKEN}`
-- Enterprise endpoints and GraphQL: `Authorization: Bearer ${GITHUB_TOKEN}`
-- The `gh_api` helper in `lib/github-common.sh` always uses Bearer; pass `"bearer"` to `validate_github_token` for enterprise scripts
-
-### Shared library helpers
-
-| Function | Purpose |
-|----------|---------|
-| `print_status` / `print_success` / `print_warning` / `print_error` | Colored output |
-| `err <message>` | `print_error` + `exit 1` in one call |
-| `require_env_var <VAR>` | Exit with message if variable unset/empty |
-| `require_command <cmd>` | Exit if binary not in PATH |
-| `configure_gh_auth [scope_hint]` | Bridge GITHUB_TOKEN→GH_TOKEN or verify gh auth session |
-| `validate_github_token [bearer]` | Verify GITHUB_TOKEN via /user endpoint |
-| `validate_slug <value> <label>` | Reject values with non-alphanumeric/hyphen/underscore chars |
-| `gh_api <path> [--api-version V] [curl args...]` | Bearer-auth REST helper with 5-retry rate-limit handling; optional `--api-version` overrides the default `2022-11-28` header; returns literal `__404__` or `__422__` for those HTTP statuses — callers must check for these sentinels |
-| `gh_api_paginate <path> [filter] [version]` | Paginated REST helper, follows Link headers, streams items; returns silently with empty output on 404/422 |
-| `get_enterprise_orgs` | Three-tier enterprise org resolver (REST → GraphQL → /user/orgs) |
-| `get_repo_page_count <url>` | Returns total pages for a paginated endpoint |
-
-### Error handling sequence
-
-1. `require_env_var` all required variables
-2. `validate_github_token` (or `validate_token` for secondary tokens)
-3. Validate additional inputs with `validate_slug` where needed
-4. Proceed with main logic
-
-> **Note on token auto-resolution:** Sourcing `lib/github-common.sh` automatically populates `GITHUB_TOKEN` from an active `gh` auth session if the variable is unset. This means `require_env_var GITHUB_TOKEN` may pass even when no explicit token was provided by the caller — the token was silently resolved from `gh auth token`. Script headers should document `GITHUB_TOKEN` as "Required (or provided by an active gh auth session)". Scripts that use the `gh` CLI instead of `curl` should call `configure_gh_auth` instead of step 2 above.
-
-### Pagination (REST)
-
-```bash
-for PAGE in $(seq "$(get_repo_page_count "${API_URL_PREFIX}/orgs/${ORG}/repos?per_page=100")"); do
-  # process page
-done
-```
-
-### Rate limiting
-
-- Repo-level operations (permission grants, archival): `sleep 5` between each repo
-- Code search: configurable `SEARCH_SLEEP` (default 2s) and `CONTENT_SLEEP` (default 1s)
-- `gh_api` auto-retries on HTTP 403/429 with 60s sleep
-- `gh_api` returns the literal string `__404__` or `__422__` (exit 0) for those HTTP statuses — callers must check for these sentinels before passing output to `jq`
-
----
-
-## Adding a New Script
-
-1. **Create the directory:** `<domain>/github-<verb-noun>/`
-2. **Create the script:** `github-<verb-noun>.sh` (name must match the directory)
-3. **Copy the header template** from Script Anatomy above — fill in description, all env vars, requirements
-4. **Source the shared library** using `SCRIPT_DIR`
-5. **Validate all inputs** before any API calls
-6. **Create `action.yml`** in the same directory — expose every env var as an input (required inputs first, optional inputs with defaults); map CLI flags (`--dry-run`, `--type`, etc.) to boolean/string inputs and construct the `ARGS` array in the `run:` step. See existing `action.yml` files for the pattern.
-7. **Add tests to `tests/test_script_validation.bats`** — add a labelled section (`# ═══ github-<name> ═══`) with tests for: every required env var missing (exit 1), unknown CLI args (exit 1), `--help` exits 0, and any script-specific validation (enum guards, URL allowlists, positional args). See existing sections for the pattern.
-8. **Add to README.md** — follow the existing format: use case, env var table, usage example, output format; add a row to the Available Actions table in the "Using Scripts in GitHub Actions" section
-9. Place in the correct domain:
-   - `org-admin/` — organization-level operations (repos, teams, members)
-   - `enterprise/` — enterprise-level operations (licenses, org enumeration)
-   - `reporting/` — read-only reports and audits
-   - `personal/` — personal GitHub utilities (stars, profile)
+> The full reference for script anatomy, shared library helpers, authentication,
+> pagination, and adding new scripts lives in
+> [`.github/copilot-instructions.md`](.github/copilot-instructions.md).
+> The sections below cover only what is unique to this guide.
 
 ---
 
@@ -244,7 +148,7 @@ done
 - **Pre-commit hook:** `.githooks/pre-commit` — runs gitleaks + shellcheck on staged `.sh` files
 - **Install:** `./install-hooks.sh` or `git config core.hooksPath .githooks`
 - **Bypass (emergency only):** `git commit --no-verify`
-- **CI:** shellcheck runs on all `.sh` files on every PR (`.github/workflows/ci.yml`); bats unit tests run in a dedicated `test` job (`bats tests/`)
+- **CI:** shellcheck + bats unit tests run together on every PR (`.github/workflows/ci.yml`)
 - **Releases:** automated by Release Please (`.github/workflows/release.yml`) — pushes to `main` trigger a release PR; merging it publishes the GitHub Release and tag
 
 ## Commit Messages — Conventional Commits (required)

enterprise/github-add-enterprise-team-read-permissions/github-add-enterprise-team-read-permissions.sh

@@ -138,8 +138,7 @@ print_status "Fetching organizations in enterprise: ${ENTERPRISE}..."
 mapfile -t ORG_LIST < <(get_enterprise_orgs)
 
 if [ "${#ORG_LIST[@]}" -eq 0 ]; then
-  print_error "No organizations found in enterprise '${ENTERPRISE}'. Check the enterprise slug and token permissions."
-  exit 1
+  err "No organizations found in enterprise '${ENTERPRISE}'. Check the enterprise slug and token permissions."
 fi
 
 print_status "Found ${#ORG_LIST[@]} organization(s)"

enterprise/github-dockerfile-discovery/github-dockerfile-discovery.sh

@@ -350,17 +350,15 @@ main() {
   fi
 
   if [ "${#orgs[@]}" -eq 0 ]; then
-    print_error "No organisations found. Check ENTERPRISE slug and token permissions."
-    exit 1
+    err "No organisations found. Check ENTERPRISE slug and token permissions."
   fi
 
 # ── Apply ORG_FILTER (inclusion) if set ────────────────────────────────
   if [ -n "${ORG_FILTER}" ]; then
     local _rc=0
     echo "" | grep -qE "${ORG_FILTER}" 2>/dev/null || _rc=$?
     if [ "${_rc}" -eq 2 ]; then
-      print_error "ORG_FILTER is not a valid ERE regex: ${ORG_FILTER}"
-      exit 1
+      err "ORG_FILTER is not a valid ERE regex: ${ORG_FILTER}"
     fi
     local filtered=()
     for org in "${orgs[@]}"; do
@@ -378,8 +376,7 @@ main() {
     local _rc=0
     echo "" | grep -qE "${ORG_EXCLUDE}" 2>/dev/null || _rc=$?
     if [ "${_rc}" -eq 2 ]; then
-      print_error "ORG_EXCLUDE is not a valid ERE regex: ${ORG_EXCLUDE}"
-      exit 1
+      err "ORG_EXCLUDE is not a valid ERE regex: ${ORG_EXCLUDE}"
     fi
     local kept=()
     for org in "${orgs[@]}"; do
@@ -393,8 +390,7 @@ main() {
   fi
 
   if [ "${#orgs[@]}" -eq 0 ]; then
-    print_error "No organisations remain after applying ORG_FILTER/ORG_EXCLUDE filters."
-    exit 1
+    err "No organisations remain after applying ORG_FILTER/ORG_EXCLUDE filters."
   fi
   print_success "Found ${#orgs[@]} organisation(s): ${orgs[*]}"
 

enterprise/github-get-public-repos/github-get-public-repos.sh

@@ -78,8 +78,7 @@ resolve_orgs() {
     local _rc=0
     echo "" | grep -qE "${ORG_FILTER}" 2>/dev/null || _rc=$?
     if [ "${_rc}" -eq 2 ]; then
-      print_error "ORG_FILTER is not a valid ERE regex: ${ORG_FILTER}"
-      exit 1
+      err "ORG_FILTER is not a valid ERE regex: ${ORG_FILTER}"
     fi
     raw_orgs=$(echo "${raw_orgs}" | grep -E "${ORG_FILTER}" || true)
   fi
@@ -89,8 +88,7 @@ resolve_orgs() {
     local _rc=0
     echo "" | grep -qE "${ORG_EXCLUDE}" 2>/dev/null || _rc=$?
     if [ "${_rc}" -eq 2 ]; then
-      print_error "ORG_EXCLUDE is not a valid ERE regex: ${ORG_EXCLUDE}"
-      exit 1
+      err "ORG_EXCLUDE is not a valid ERE regex: ${ORG_EXCLUDE}"
     fi
     raw_orgs=$(echo "${raw_orgs}" | grep -Ev "${ORG_EXCLUDE}" || true)
   fi
@@ -186,8 +184,7 @@ main() {
   orgs=$(resolve_orgs)
 
   if [ -z "${orgs}" ]; then
-    print_error "No organisations found. Check your ENTERPRISE/ORGS/ORG_FILTER settings."
-    exit 1
+    err "No organisations found. Check your ENTERPRISE/ORGS/ORG_FILTER settings."
   fi
 
   local org_count

enterprise/github-install-enterprise-app/github-install-enterprise-app.sh

@@ -76,8 +76,7 @@ for arg in "$@"; do
       exit 0
       ;;
     *)
-      print_error "Unknown option: ${arg}"
-      exit 1
+      err "Unknown option: ${arg}"
       ;;
   esac
 done
@@ -100,8 +99,7 @@ validate_slug "${INSTALLER_APP_INSTALL_ID}" "installer app installation ID"
 case "${REPO_SELECTION}" in
   all|selected) ;;
   *)
-    print_error "REPO_SELECTION must be 'all' or 'selected' (got '${REPO_SELECTION}')"
-    exit 1
+    err "REPO_SELECTION must be 'all' or 'selected' (got '${REPO_SELECTION}')"
     ;;
 esac
 
@@ -111,12 +109,10 @@ INSTALLER_APP_PRIVATE_KEY="${INSTALLER_APP_PRIVATE_KEY/#\~/${HOME}}"
   AUTOMATION_APP_PRIVATE_KEY="${AUTOMATION_APP_PRIVATE_KEY/#\~/${HOME}}"
 
 if [ ! -r "${INSTALLER_APP_PRIVATE_KEY}" ]; then
-  print_error "Installer app private key not readable: ${INSTALLER_APP_PRIVATE_KEY}"
-  exit 1
+  err "Installer app private key not readable: ${INSTALLER_APP_PRIVATE_KEY}"
 fi
 if [ -n "${AUTOMATION_APP_PRIVATE_KEY}" ] && [ ! -r "${AUTOMATION_APP_PRIVATE_KEY}" ]; then
-  print_error "Automation app private key not readable: ${AUTOMATION_APP_PRIVATE_KEY}"
-  exit 1
+  err "Automation app private key not readable: ${AUTOMATION_APP_PRIVATE_KEY}"
 fi
 
 ###
@@ -233,8 +229,7 @@ case "${INSTALL_HTTP_CODE}" in
     ;;
   *)
     INSTALL_MESSAGE=$(echo "${INSTALL_BODY}" | jq -r '.message // empty' 2>/dev/null || true)
-    print_error "Failed to install automation app (HTTP ${INSTALL_HTTP_CODE}): ${INSTALL_MESSAGE:-unknown error}"
-    exit 1
+    err "Failed to install automation app (HTTP ${INSTALL_HTTP_CODE}): ${INSTALL_MESSAGE:-unknown error}"
     ;;
 esac
 
@@ -256,6 +251,5 @@ if mint_installation_token \
   "${AUTOMATION_APP_INSTALL_ID}" > /dev/null; then
   print_success "Automation app authenticated successfully in '${ORG}'. Installation is live."
 else
-  print_error "Could not authenticate the automation app after install."
-  exit 1
+  err "Could not authenticate the automation app after install."
 fi

org-admin/github-add-repo-collaborators-by-pattern/github-add-repo-collaborators-by-pattern.sh

@@ -59,8 +59,7 @@ validate() {
   case "${PERMISSION}" in
     pull|triage|push|maintain|admin) ;;
     *)
-      print_error "Invalid PERMISSION '${PERMISSION}'. Must be one of: pull, triage, push, maintain, admin"
-      exit 1
+      err "Invalid PERMISSION '${PERMISSION}'. Must be one of: pull, triage, push, maintain, admin"
       ;;
   esac
   require_command jq

org-admin/github-add-repo-permissions/github-add-repo-permissions.sh

@@ -58,9 +58,7 @@ require_command jq
 
 # Check if at least one permission level is set
 if [ -z "${REPO_ADMIN}" ] && [ -z "${REPO_MAINTAIN}" ] && [ -z "${REPO_PUSH}" ] && [ -z "${REPO_TRIAGE}" ] && [ -z "${REPO_PULL}" ]; then
-  print_error "At least one permission level must be set."
-  print_error "Available variables: REPO_ADMIN, REPO_MAINTAIN, REPO_PUSH, REPO_TRIAGE, REPO_PULL"
-  exit 1
+  err "At least one permission level must be set. Available: REPO_ADMIN, REPO_MAINTAIN, REPO_PUSH, REPO_TRIAGE, REPO_PULL"
 fi
 
 validate_github_token
@@ -103,8 +101,7 @@ process_repos () {
 
     if ! echo "${repos_json}" | jq -e 'type == "array"' > /dev/null 2>&1; then
       print_error "Unexpected API response for page ${PAGE}"
-      print_error "$(echo "${repos_json}" | jq -r '.message // "unknown error"')"
-      exit 1
+      err "$(echo "${repos_json}" | jq -r '.message // "unknown error"')"
     fi
 
     while IFS= read -r REPO; do