Enhance scripts with standardized header blocks, usage instructions, and environment variable details

Author: Patrick Lewis

.github/copilot-instructions.md

@@ -26,29 +26,57 @@ Provides reusable helpers sourced by scripts:
 
 ### Script Anatomy (Standardized Pattern)
 
-All scripts follow this structure:
+All scripts **must** begin with a `# ===` header block, followed immediately by
+`set -euo pipefail`. Fill in the script name, description, usage, every
+environment variable the script reads (Required/Optional), and every external
+command it depends on.
 
 ```bash
 #!/bin/bash
+# =============================================================================
+# github-<script-name>.sh
+#
+# <One-paragraph description of what this script does.>
+#
+# Usage:
+#   export GITHUB_TOKEN=ghp_yourtoken
+#   export ORG=my-org
+#   ./github-<script-name>.sh [options]
+#
+# Options:                         (omit this section if there are no CLI flags)
+#   --dry-run    Preview changes without making them
+#
+# 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                # ALWAYS include: exit on error, undefined vars, pipe failures
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../lib/github-common.sh
+source "${SCRIPT_DIR}/../../lib/github-common.sh"
+
 ### GLOBAL VARIABLES
 GITHUB_TOKEN=${GITHUB_TOKEN:-''}
 ORG=${ORG:-''}
 API_URL_PREFIX=${API_URL_PREFIX:-'https://api.github.com'}
-GIT_URL_PREFIX=${GIT_URL_PREFIX:-'https://github.com'}
 # Script-specific required vars...
 
-# Source shared library (when available)
-# SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# source "${SCRIPT_DIR}/../../lib/github-common.sh"
-
 # Token validation block
 # Helper functions for pagination/processing
 # Main execution logic
 ```
 
-**Critical patterns:**
+**Rules:**
+- The `# ===` fence is exactly 79 characters.
+- Do **not** add a second `###` description block inside the body — all descriptive content belongs in the top header.
+- `set -euo pipefail` must be the first executable line after the header.
 
 ## GitHub API Patterns
 

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

@@ -1,19 +1,36 @@
 #!/bin/bash
+# =============================================================================
+# github-add-enterprise-team-read-permissions.sh
+#
+# Assigns the built-in "All-repository read" organisation role to a specified
+# enterprise team in every organisation within a GitHub Enterprise account.
+# This grants read access to all current and future repositories without
+# requiring per-repository assignments.
+#
+# Usage:
+#   export GITHUB_TOKEN=ghp_yourtoken
+#   export ENTERPRISE=my-enterprise
+#   export ENTERPRISE_TEAM_SLUG=platform-team
+#   ./github-add-enterprise-team-read-permissions.sh
+#
+# Environment variables:
+#   GITHUB_TOKEN             Required. PAT with admin:enterprise scope
+#   ENTERPRISE               Required. GitHub Enterprise slug
+#   ENTERPRISE_TEAM_SLUG     Required. Enterprise team slug (without "ent:" prefix)
+#   ALL_REPO_READ_ROLE_NAME  Optional. Org role name (default: all_repo_read)
+#   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"
 
-###
-## GitHub Enterprise Team Org Role Assignment
-## Assigns the built-in "All-repository read" organization role to the
-## configured enterprise team in every org in the enterprise.
-##
-## This org-level role grants read access to all current AND future
-## repositories, so the assignment only needs to be made once per org.
-###
-
 ###
 ## GLOBAL VARIABLES
 ###

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

@@ -1,4 +1,32 @@
 #!/bin/bash
+# =============================================================================
+# github-dockerfile-discovery.sh
+#
+# Searches all organisations in a GitHub Enterprise account for Dockerfiles,
+# extracts base image references from FROM instructions, and generates CSV
+# reports to identify common base images across the estate.
+#
+# Usage:
+#   export GITHUB_TOKEN=ghp_yourtoken
+#   export ENTERPRISE=my-enterprise
+#   ./github-dockerfile-discovery.sh
+#
+# Environment variables:
+#   GITHUB_TOKEN    Required. PAT with read:org and repo scope
+#   ENTERPRISE      Required. GitHub Enterprise slug
+#   API_URL_PREFIX  Optional. GitHub API base URL (default: https://api.github.com)
+#   REPORT_DIR      Optional. Output directory (default: ./reports)
+#   ORGS            Optional. Comma-separated org list; skips enterprise lookup
+#   ORG_FILTER      Optional. ERE regex to keep only matching org names
+#   ORG_EXCLUDE     Optional. ERE regex to drop matching org names
+#   SEARCH_SLEEP    Optional. Seconds between code-search requests (default: 2)
+#   CONTENT_SLEEP   Optional. Seconds between content-fetch requests (default: 1)
+#
+# Requirements:
+#   - curl
+#   - jq
+# =============================================================================
+
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -10,27 +38,6 @@ print_success() { echo -e "${GREEN}[SUCCESS]${NC} $1" >&2; }
 print_warning() { echo -e "${YELLOW}[WARNING]${NC} $1" >&2; }
 print_error()   { echo -e "${RED}[ERROR]${NC}   $1" >&2; }
 
-###
-## GitHub Enterprise Dockerfile Discovery
-## Searches all organisations in a GitHub Enterprise account for Dockerfiles,
-## extracts base image references from FROM instructions, and generates CSV
-## reports to identify common base images across the estate.
-##
-## Usage:
-##   export GITHUB_TOKEN=ghp_yourtoken
-##   export ENTERPRISE=my-enterprise
-##   ./github-dockerfile-discovery.sh
-##
-## Optional env vars:
-##   API_URL_PREFIX  - GitHub API base URL (default: https://api.github.com)
-##   REPORT_DIR      - Output directory    (default: ./reports)
-##   ORGS            - Comma-separated org list; skips enterprise lookup
-##   ORG_FILTER      - ERE regex to keep only matching org names (e.g. '^my-enterprise-prefix')
-##   ORG_EXCLUDE     - ERE regex to drop matching org names
-##   SEARCH_SLEEP    - Seconds between code-search requests (default: 2)
-##   CONTENT_SLEEP   - Seconds between content-fetch requests (default: 1)
-###
-
 ###
 ## GLOBAL VARIABLES
 ###

enterprise/github-get-consumed-licenses/github-get-consumed-licenses.sh

@@ -1,4 +1,25 @@
 #!/bin/bash
+# =============================================================================
+# github-get-consumed-licenses.sh
+#
+# Displays the total number of GitHub Enterprise license seats consumed and
+# purchased for the given enterprise account.
+#
+# Usage:
+#   export GITHUB_TOKEN=ghp_yourtoken
+#   export ENTERPRISE=my-enterprise
+#   ./github-get-consumed-licenses.sh
+#
+# Environment variables:
+#   GITHUB_TOKEN    Required. PAT with manage_billing:enterprise scope
+#   ENTERPRISE      Required. GitHub Enterprise slug
+#   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)"

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

@@ -1,4 +1,29 @@
 #!/bin/bash
+# =============================================================================
+# github-get-public-repos.sh
+#
+# Lists all repositories with public visibility across every organisation in a
+# GitHub Enterprise account and writes a timestamped CSV report.
+#
+# Usage:
+#   export GITHUB_TOKEN=ghp_yourtoken
+#   export ENTERPRISE=my-enterprise
+#   ./github-get-public-repos.sh
+#
+# Environment variables:
+#   GITHUB_TOKEN    Required. PAT with read:org and repo scope
+#   ENTERPRISE      Required. GitHub Enterprise slug
+#   API_URL_PREFIX  Optional. GitHub API base URL (default: https://api.github.com)
+#   REPORT_DIR      Optional. Output directory (default: ./reports)
+#   ORGS            Optional. Comma-separated org list; skips enterprise lookup
+#   ORG_FILTER      Optional. ERE regex to keep only matching org names
+#   ORG_EXCLUDE     Optional. ERE regex to drop matching org names
+#
+# Requirements:
+#   - curl
+#   - jq
+# =============================================================================
+
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -10,24 +35,6 @@ print_success() { echo -e "${GREEN}[SUCCESS]${NC} $1" >&2; }
 print_warning() { echo -e "${YELLOW}[WARNING]${NC} $1" >&2; }
 print_error()   { echo -e "${RED}[ERROR]${NC}   $1" >&2; }
 
-###
-## GitHub Enterprise Public Repo Discovery
-## Lists all repositories with public visibility across every organisation
-## in a GitHub Cloud Enterprise account and writes a timestamped CSV report.
-##
-## Usage:
-##   export GITHUB_TOKEN=ghp_yourtoken
-##   export ENTERPRISE=my-enterprise
-##   ./github-get-public-repos.sh
-##
-## Optional env vars:
-##   API_URL_PREFIX  - GitHub API base URL (default: https://api.github.com)
-##   REPORT_DIR      - Output directory    (default: ./reports)
-##   ORGS            - Comma-separated org list; skips enterprise org lookup
-##   ORG_FILTER      - ERE regex to keep only matching org names (e.g. '^my-enterprise-prefix')
-##   ORG_EXCLUDE     - ERE regex to drop matching org names
-###
-
 ###
 ## GLOBAL VARIABLES
 ###

lib/github-common.sh

@@ -1,10 +1,22 @@
 #!/bin/bash
-# lib/github-common.sh — Shared utility functions for GitHub API scripts.
+# =============================================================================
+# github-common.sh
 #
-# Source this from any script:
+# Shared utility functions for GitHub API scripts. Source this library from
+# any script; do not execute it directly.
+#
+# Usage (from a script two directory levels deep):
 #   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 #   # shellcheck source=../../lib/github-common.sh
 #   source "${SCRIPT_DIR}/../../lib/github-common.sh"
+#
+# Provides:
+#   print_status / print_success / print_warning / print_error
+#   require_env_var <VAR> [description]  — exit if variable is unset/empty
+#   require_command <cmd>                — exit if command not found
+#   validate_github_token [bearer]       — verify token via /user endpoint
+#   validate_token <VAR_NAME>            — verify a secondary token variable
+# =============================================================================
 
 ###
 ## COLOR CODES

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

@@ -1,4 +1,31 @@
 #!/bin/bash
+# =============================================================================
+# github-add-repo-collaborators-by-pattern.sh
+#
+# Adds one or more individual collaborators to all repositories in an
+# organisation whose names match a given regex pattern.
+#
+# Usage:
+#   export GITHUB_TOKEN=ghp_yourtoken
+#   export ORG=my-org
+#   export COLLABORATORS=alice,bob
+#   export REPO_NAME_REGEX='^service-'
+#   ./github-add-repo-collaborators-by-pattern.sh
+#
+# Environment variables:
+#   GITHUB_TOKEN        Required. PAT with repo and admin:org scope
+#   ORG                 Required. GitHub organization name
+#   COLLABORATORS       Required. Comma-separated GitHub usernames
+#   REPO_NAME_REGEX     Required. ERE regex to match repository names
+#   PERMISSION          Optional. Permission level: pull|triage|push|maintain|admin (default: push)
+#   REPO_EXCLUDE_REGEX  Optional. ERE regex to exclude matching repository names
+#   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)"

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

@@ -1,4 +1,35 @@
 #!/bin/bash
+# =============================================================================
+# github-add-repo-permissions.sh
+#
+# Grants team-level permissions across all repositories in a GitHub
+# organisation. Supports all five permission levels: admin, maintain, push,
+# triage, and pull. At least one permission level must be specified.
+#
+# Usage:
+#   export GITHUB_TOKEN=ghp_yourtoken
+#   export ORG=my-org
+#   export REPO_PUSH="platform-team ci-team"
+#   ./github-add-repo-permissions.sh
+#
+# Environment variables:
+#   GITHUB_TOKEN    Required. PAT with admin:org scope
+#   ORG             Required. GitHub organization name
+#   REPO_ADMIN      Optional. Space-separated team slugs to grant admin access
+#   REPO_MAINTAIN   Optional. Space-separated team slugs to grant maintain access
+#   REPO_PUSH       Optional. Space-separated team slugs to grant push access
+#   REPO_TRIAGE     Optional. Space-separated team slugs to grant triage access
+#   REPO_PULL       Optional. Space-separated team slugs to grant pull access
+#   API_URL_PREFIX  Optional. GitHub API base URL (default: https://api.github.com)
+#
+# Note: At least one of REPO_ADMIN, REPO_MAINTAIN, REPO_PUSH, REPO_TRIAGE,
+#       or REPO_PULL must be set.
+#
+# Requirements:
+#   - curl
+#   - jq
+# =============================================================================
+
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

org-admin/github-archive-old-repos/github-archive-old-repos.sh

@@ -1,9 +1,26 @@
 #!/bin/bash
-
-# GitHub Archive Old Repositories
-# Identifies and archives repositories not updated in the last 5 years
-# Author: Patrick Lewis (locus313)
-# Date: October 15, 2025
+# =============================================================================
+# github-archive-old-repos.sh
+#
+# Identifies and archives repositories that have not been updated within a
+# configurable number of years. Generates a timestamped CSV report of all
+# archived repositories.
+#
+# Usage:
+#   export GITHUB_TOKEN=ghp_yourtoken
+#   export ORG=my-org
+#   ./github-archive-old-repos.sh
+#
+# Environment variables:
+#   GITHUB_TOKEN      Required. PAT with repo scope
+#   ORG               Required. GitHub organization name
+#   YEARS_THRESHOLD   Optional. Age threshold in years (default: 5)
+#   API_URL_PREFIX    Optional. GitHub API base URL (default: https://api.github.com)
+#
+# Requirements:
+#   - curl
+#   - jq
+# =============================================================================
 
 set -euo pipefail