Skip to content

AGENTS.md

Latest commit

 

History

History
279 lines (215 loc) · 12.9 KB

AGENTS.md

File metadata and controls

279 lines (215 loc) · 12.9 KB
Raw

GitHub API Scripts — Agent Guide

Project Overview

A collection of standalone bash automation scripts for GitHub organization and enterprise administration. Each script is a self-contained, self-validating CLI utility that interacts with the GitHub REST and GraphQL APIs using curl + jq. A shared utility library (lib/github-common.sh) provides common validation, output, and API helpers.

Key principle: Scripts are independent — they are never imported or called by each other. Every script manages its own validation, error handling, and environment variable requirements.

Repository Structure

github-api-scripts/
├── lib/
│   └── github-common.sh          # Shared helpers (source this, never execute directly)
├── org-admin/                    # Organization-level administration scripts
│   └── github-<name>/
│       └── github-<name>.sh
├── enterprise/                   # Enterprise-level scripts
│   └── github-<name>/
│       └── github-<name>.sh
├── reporting/                    # Reporting and audit scripts
│   └── github-<name>/
│       └── github-<name>.sh
├── personal/                     # Personal GitHub utility scripts
│   └── github-<name>/
│       └── github-<name>.sh
├── .githooks/
│   └── pre-commit                # Secret scanning (gitleaks) + shellcheck
├── .github/
│   ├── copilot-instructions.md   # Detailed AI agent conventions
│   ├── agents/                   # Custom agent profiles
│   ├── skills/                   # Custom skills
│   └── instructions/             # Path-scoped instruction files
├── install-hooks.sh              # Installs .githooks/pre-commit via git config
├── LICENSE                       # MIT
└── README.md                     # Full script documentation with usage examples

Tech Stack

Tool Role
bash 4+ All scripts
curl GitHub REST and GraphQL API calls
jq JSON parsing and transformation
gh CLI Used in github-organize-stars
base64 Used in github-auto-repo-creation for CODEOWNERS encoding
git Used in github-import-repo for bare clone + mirror push
shellcheck Linting (pre-commit hook + CI)
gitleaks Secret scanning (pre-commit hook)
Release Please Automated releases and CHANGELOG generation (.github/workflows/release.yml)

Build & Run

There is no build step. Scripts run directly:

# Install the pre-commit hook (one-time setup)
./install-hooks.sh

# Run any script directly after exporting required env vars
export GITHUB_TOKEN=ghp_yourtoken
export ORG=my-org
./org-admin/github-get-repo-list/github-get-repo-list.sh

Lint all scripts:

find . -name "*.sh" | xargs shellcheck --severity=warning --exclude=SC2034,SC1091 --shell=bash

Testing

The project has a bats unit-test suite in tests/. Every new script must ship with tests.

# Run all tests
bats tests/

# Run a single file
bats tests/test_common.bats

Test files

File What it covers
tests/test_common.bats lib/github-common.sh — pure-logic functions (validate_slug, require_env_var, require_command, err, configure_gh_auth, validate_token, get_repo_page_count) and API helpers (gh_api sentinels, gh_api_paginate)
tests/test_script_validation.bats Every script — missing required env vars exit 1, invalid CLI args exit 1, --help exits 0, script-specific enum/allowlist validation
tests/mock_curl.sh Universal drop-in curl mock (used by both test files); response data via env vars MOCK_CURL_CODE, MOCK_CURL_BODY, MOCK_CURL_LINK

What to test for every new script

  1. Missing required env vars — one @test per required variable, in the order the script checks them. Each test asserts status -eq 1.
  2. Invalid CLI args — unknown flag exits 1 with an "Unknown" message.
  3. --help flag — exits 0 (for scripts that implement it).
  4. Recognised flags — --dry-run and other known flags do not trigger the unknown-arg error (test by asserting output does not contain "Unknown").
  5. Script-specific guards — enum validation (--type, DEPENDABOT_REASON), URL allowlists (GIT_URL_PREFIX), required positional args.

Mocking pattern

Tests shadow real binaries by prepending a MOCK_BIN directory to PATH:

setup() {
  MOCK_BIN="$(mktemp -d)"
  # Fail gh auth so GITHUB_TOKEN is never auto-resolved from a session
  printf '#!/bin/sh\nexit 1\n' > "$MOCK_BIN/gh"
  chmod +x "$MOCK_BIN/gh"
}

teardown() { rm -rf "$MOCK_BIN"; }

@test "my-script: exits 1 when GITHUB_TOKEN is not set" {
  run bash -c "export PATH='${MOCK_BIN}:${PATH}'; unset GITHUB_TOKEN; bash '${REPO_ROOT}/domain/my-script/my-script.sh'"
  [ "$status" -eq 1 ]
}

Use _mock_curl_200 (defined in test_script_validation.bats) when a test must reach code that runs after validate_github_token.

Dry-run flags and other testing approaches

  • --dry-run — several scripts support it to preview changes without applying them.
  • Test org first — always run against a non-production GitHub org before production.

Key Patterns and Conventions

Script anatomy

Every script begins with a # === header (exactly 79 = chars), then immediately set -euo pipefail:

#!/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)

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)

CI/CD

  • 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/)
  • 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)

All commits must follow Conventional Commits. CHANGELOG.md is fully managed by Release Please and must never be edited manually.

Prefix Version bump Visible in changelog
feat: minor ✅ Features
fix: patch ✅ Bug Fixes
docs: patch ✅ Documentation
perf: patch ✅ Performance Improvements
revert: patch ✅ Reverts
feat!: / BREAKING CHANGE: major ✅
chore: none hidden
ci: none hidden
refactor: patch Code Refactoring
test: none hidden

Common Pitfalls

  • Team slugs vs names: API uses slugs (lowercase, hyphenated). "Platform Team" → platform-team
  • Bearer vs token auth: Enterprise endpoints need Bearer; standard org/repo endpoints use token
  • Space-separated lists: REPO_ADMIN and similar accept multiple space-separated values — loop with for item in ${VAR}
  • Comma-separated lists: COLLABORATORS, REPO_NAMES, ORGS use commas — split with IFS=','
  • URL encoding: Labels in API calls must be URL-encoded (e.g., Linked [AC] → Linked%20[AC])
  • Public repo filtering: Do not rely on ?type=public for enterprise-managed orgs — fetch all and filter in jq
  • macOS vs Linux date: github-archive-old-repos.sh handles both BSD date -v and GNU date -d
  • set -euo pipefail: Must be the first executable line after the header — never omit it
  • Never edit CHANGELOG.md manually — it is fully managed by Release Please via Conventional Commits