feat: add GitHub API helpers for organization management and enhance existing functions

Author: locus313

README.md

@@ -804,6 +804,10 @@ All scripts can leverage a shared utility library for common operations like val
 **API helpers:**
 - `get_repo_page_count <url>` — Get total page count from paginated REST endpoint
 - `validate_slug <value> <label>` — Exit if value contains characters other than alphanumeric, hyphen, or underscore
+- `gh_api <path|url> [curl args...]` — Bearer-auth REST helper with automatic rate-limit retry (up to 5 attempts); returns `__404__` / `__422__` for those status codes instead of failing
+- `_paginate_orgs_endpoint <jq_filter> <url_template>` — Page through an org-list REST endpoint, printing one login per line; use `PAGE` as a placeholder in the URL template
+- `_graphql_enterprise_orgs` — Cursor-based GraphQL pagination for all orgs in `ENTERPRISE`; prints one login per line
+- `get_enterprise_orgs` — Three-tier enterprise org resolver: tries REST `/enterprises/{slug}/organizations`, falls back to GraphQL, then falls back to `/user/orgs`
 
 ### Using the Shared Library in Scripts
 

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

@@ -53,45 +53,6 @@ print_status "Enterprise: ${ENTERPRISE}"
 print_status "Enterprise team slug: ${ENTERPRISE_TEAM_SLUG}"
 print_status "Org role to assign: ${ALL_REPO_READ_ROLE_NAME}"
 
-###
-## Fetch all organization logins in the enterprise via GraphQL (cursor-based pagination)
-###
-get_enterprise_orgs () {
-  local orgs=()
-  local cursor=""
-  local has_next_page="true"
-
-  while [ "${has_next_page}" = "true" ]; do
-    local after_clause=""
-    if [ -n "${cursor}" ]; then
-      after_clause=", after: \\\"${cursor}\\\""
-    fi
-
-    local query="{\"query\":\"{ enterprise(slug: \\\"${ENTERPRISE}\\\") { organizations(first: 100${after_clause}) { nodes { login } pageInfo { hasNextPage endCursor } } } }\"}"
-
-    local response
-    response=$(curl -s \
-      -H "Authorization: token ${GITHUB_TOKEN}" \
-      -H "Content-Type: application/json" \
-      "${API_URL_PREFIX}/graphql" \
-      -d "${query}")
-
-    local batch
-    batch=$(echo "${response}" | jq -r '.data.enterprise.organizations.nodes[].login // empty' 2>/dev/null)
-
-    [ -z "${batch}" ] && break
-
-    while IFS= read -r org; do
-      orgs+=("${org}")
-    done <<< "${batch}"
-
-    has_next_page=$(echo "${response}" | jq -r '.data.enterprise.organizations.pageInfo.hasNextPage')
-    cursor=$(echo "${response}" | jq -r '.data.enterprise.organizations.pageInfo.endCursor')
-  done
-
-  printf '%s\n' "${orgs[@]}"
-}
-
 ###
 ## Look up the numeric role_id for the all_repo_read built-in org role
 ###

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

@@ -80,52 +80,6 @@ check_prerequisites() {
   print_success "Prerequisites OK"
 }
 
-###
-## GitHub API helper – handles rate-limit retries
-## Usage: gh_api <path_or_url> [extra curl args...]
-###
-gh_api() {
-  local url="$1"
-  shift
-  # Prepend base URL if path starts with /
-  [[ "${url}" == http* ]] || url="${API_URL_PREFIX}${url}"
-
-  local attempt
-  for attempt in 1 2 3 4 5; do
-    local http_code
-    local body
-    body=$(curl -s -w "\n%{http_code}" \
-      -H "Authorization: Bearer ${GITHUB_TOKEN}" \
-      -H "Accept: application/vnd.github+json" \
-      -H "X-GitHub-Api-Version: 2022-11-28" \
-      "$@" "${url}")
-    http_code=$(echo "${body}" | tail -1)
-    body=$(echo "${body}" | head -n -1)
-
-    if [[ "${http_code}" == "200" ]]; then
-      echo "${body}"
-      return 0
-    elif [[ "${http_code}" == "403" || "${http_code}" == "429" ]]; then
-      local retry_after=60
-      print_warning "Rate limited (HTTP ${http_code}). Sleeping ${retry_after}s before retry ${attempt}/5..."
-      sleep "${retry_after}"
-    elif [[ "${http_code}" == "404" ]]; then
-      echo "__404__"
-      return 0
-    elif [[ "${http_code}" == "422" ]]; then
-      # Code search not available for this org
-      echo "__422__"
-      return 0
-    else
-      print_warning "HTTP ${http_code} for ${url} (attempt ${attempt}/5)"
-      sleep 5
-    fi
-  done
-
-  print_error "Failed to GET ${url} after 5 attempts"
-  return 1
-}
-
 ###
 ## gh_api_link – like gh_api but also returns the Link header for pagination
 ## Writes body to stdout, sets global RESPONSE_LINK
@@ -168,140 +122,6 @@ gh_api_link() {
   return 1
 }
 
-###
-## Validate token
-###
-validate_token() {
-  print_status "Validating GitHub token..."
-  local resp
-  resp=$(gh_api "/user")
-  local login
-  login=$(echo "${resp}" | jq -r '.login // empty')
-  if [ -z "${login}" ]; then
-    print_error "GITHUB_TOKEN is invalid or lacks required scopes."
-    exit 1
-  fi
-  print_success "Token validated."
-}
-
-###
-## _paginate_orgs_endpoint <jq_filter> <url_template_with_PAGE_placeholder>
-## Internal helper: paginates an orgs list endpoint, prints one login per line.
-###
-_paginate_orgs_endpoint() {
-  local jq_filter="$1"
-  local url_template="$2"   # must contain the literal string PAGE
-  local page=1
-  while true; do
-    local url resp orgs_on_page count
-    url="${url_template/PAGE/${page}}"
-    resp=$(gh_api "${url}")
-    if [[ "${resp}" == "__404__" || "${resp}" == "__422__" || -z "${resp}" ]]; then
-      break
-    fi
-    orgs_on_page=$(echo "${resp}" | jq -r "${jq_filter}" 2>/dev/null || true)
-    if [ -z "${orgs_on_page}" ]; then
-      break
-    fi
-    echo "${orgs_on_page}"
-    count=$(echo "${orgs_on_page}" | wc -l)
-    if [ "${count}" -lt 100 ]; then
-      break
-    fi
-    page=$(( page + 1 ))
-  done
-}
-
-###
-## _graphql_enterprise_orgs
-## Queries the GraphQL API for enterprise orgs (works for enterprise members,
-## not just owners). Prints one org login per line.
-###
-_graphql_enterprise_orgs() {
-  local cursor="null"
-  while true; do
-    local query
-    query=$(printf '{ "query": "{ enterprise(slug: \\"%s\\") { organizations(first: 100, after: %s) { nodes { login } pageInfo { hasNextPage endCursor } } } }" }' \
-      "${ENTERPRISE}" "${cursor}")
-
-    local resp
-    resp=$(curl -s -w "\n%{http_code}" \
-      -X POST \
-      -H "Authorization: Bearer ${GITHUB_TOKEN}" \
-      -H "Content-Type: application/json" \
-      -H "X-GitHub-Api-Version: 2022-11-28" \
-      "${API_URL_PREFIX}/graphql" \
-      -d "${query}")
-
-    local http_code body
-    http_code=$(echo "${resp}" | tail -1)
-    body=$(echo "${resp}" | head -n -1)
-
-    if [[ "${http_code}" != "200" ]]; then
-      return 1
-    fi
-
-    # Surface any GraphQL-level errors (e.g. token lacks enterprise access)
-    local gql_errors
-    gql_errors=$(echo "${body}" | jq -r '.errors // empty' 2>/dev/null || true)
-    if [ -n "${gql_errors}" ]; then
-      return 1
-    fi
-
-    echo "${body}" | jq -r '.data.enterprise.organizations.nodes[].login' 2>/dev/null || true
-
-    local has_next end_cursor
-    has_next=$(echo "${body}" | jq -r '.data.enterprise.organizations.pageInfo.hasNextPage')
-    end_cursor=$(echo "${body}" | jq -r '.data.enterprise.organizations.pageInfo.endCursor')
-
-    if [[ "${has_next}" != "true" ]]; then
-      break
-    fi
-    cursor="\"${end_cursor}\""
-  done
-}
-
-###
-## get_enterprise_orgs
-## Prints one org login per line.
-## Strategy:
-##   1. Try /enterprises/{slug}/organizations REST endpoint (enterprise-owner token)
-##   2. Try GraphQL enterprise(slug).organizations      (enterprise member token)
-##   3. Fall back to /user/orgs                         (any read:org token)
-###
-get_enterprise_orgs() {
-  print_status "Fetching organisations for enterprise '${ENTERPRISE}'..."
-
-  # -- Attempt 1: REST enterprise endpoint --------------------------------
-  local probe
-  probe=$(gh_api "/enterprises/${ENTERPRISE}/organizations?per_page=1&page=1")
-  if [[ "${probe}" != "__404__" && "${probe}" != "__422__" && -n "${probe}" ]]; then
-    print_status "Using REST enterprise API endpoint."
-    _paginate_orgs_endpoint \
-      '.organizations[].login' \
-      "/enterprises/${ENTERPRISE}/organizations?per_page=100&page=PAGE"
-    return 0
-  fi
-
-  # -- Attempt 2: GraphQL enterprise query --------------------------------
-  print_warning "REST enterprise endpoint unavailable — trying GraphQL enterprise query..."
-  local gql_orgs
-  gql_orgs=$(_graphql_enterprise_orgs 2>/dev/null || true)
-  if [ -n "${gql_orgs}" ]; then
-    print_status "Using GraphQL enterprise endpoint."
-    echo "${gql_orgs}"
-    return 0
-  fi
-
-  # -- Attempt 3: /user/orgs fallback -------------------------------------
-  print_warning "GraphQL enterprise query unavailable — falling back to /user/orgs."
-  print_warning "Set ORG_FILTER env var to restrict results to enterprise orgs only."
-  print_status  "  Example: export ORG_FILTER='^my-enterprise-prefix'"
-  _paginate_orgs_endpoint \
-    '.[].login' \
-    "/user/orgs?per_page=100&page=PAGE"
-}
-
 ###
 ## search_dockerfiles_in_org <org>
 ## Appends TSV rows (org TAB repo_full_name TAB path TAB html_url) to REFS_TEMP
@@ -564,7 +384,7 @@ build_text_summary() {
 ###
 main() {
   check_prerequisites
-  validate_token
+  validate_github_token
 
   mkdir -p "${REPORT_DIR}"