feat: add composite actions, automated releases, and Conventional Commits workflow

- Add action.yml for all 16 automation scripts (enables uses: in GitHub
  Actions workflows and Dependabot version tracking)
- Add Release Please workflow for automated releases on push to main
- Add release-please-config.json, .release-please-manifest.json, and
  VERSION bootstrap files
- Remove update-readme-sha.yml (superseded by release tags)
- fix: make REPORT_DIR overridable via env var in github-archive-old-repos
- docs: restructure GitHub Actions section in README to lead with
  composite action syntax; add Available Actions table
- docs: update Contributing guide with action.yml step and Conventional
  Commits requirement
- docs: mandate Conventional Commits in AGENTS.md and copilot-instructions.md;
  CHANGELOG.md is now fully managed by Release Please

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

Author: locus313

.github/copilot-instructions.md

@@ -218,14 +218,31 @@ Uses API version `2026-03-10` and the new usage-metrics NDJSON endpoints (signed
 2. Create script: `github-<action-verb-object>.sh` (match directory name)
 3. Source `lib/github-common.sh` for validation and output helpers
 4. Start with the standard boilerplate (see Script Anatomy above)
-5. Document in README.md following existing format:
+5. Create `action.yml` in the same directory — expose every env var as a named input (required inputs without defaults, optional inputs with sensible defaults); map CLI flags such as `--dry-run` and `--type` to boolean/string inputs and build an `ARGS` array in the `run:` step. Mirror the pattern of any existing `action.yml`.
+6. Document in README.md following existing format:
    - Use case description
    - Required variables table
    - Usage example with exports
    - Output format (if applicable)
+   - Add a row to the Available Actions table in the "Using Scripts in GitHub Actions" section
 
 ### Testing Approach
 - **Always test on a test organization first**
+
+### Commit Messages — Conventional Commits (required)
+
+All commits **must** follow [Conventional Commits](https://www.conventionalcommits.org/). Release Please reads commit messages to auto-generate `CHANGELOG.md` and determine the version bump. Never update `CHANGELOG.md` manually.
+
+| Prefix | Effect | Example |
+|--------|--------|---------|
+| `feat:` | minor bump | `feat: add REPO_NAME_FILTER to github-add-repo-permissions` |
+| `fix:` | patch bump | `fix: make REPORT_DIR overridable in github-archive-old-repos` |
+| `feat!:` / `BREAKING CHANGE:` | major bump | `feat!: rename ENTERPRISE_SLUG to ENTERPRISE` |
+| `docs:` | patch bump (visible) | `docs: update GitHub Actions examples in README` |
+| `chore:` | no bump (hidden) | `chore: update actions/checkout to v7` |
+| `ci:` | no bump (hidden) | `ci: pin release-please-action SHA` |
+| `refactor:` | no bump (hidden) | `refactor: extract pagination helper` |
+
 ### Variable Naming Conventions
 - `GITHUB_TOKEN` — main admin token
 ### Dependencies
@@ -243,22 +260,23 @@ Keep new scripts dependency-minimal; document any non-standard dependencies expl
 7. **URL encoding:** Labels in API calls must be URL-encoded (`Linked [AC]` → `Linked%20[AC]`)
 8. **Public repo filtering:** Do not rely on `?type=public` for enterprise-managed orgs — fetch all and filter in jq
 9. **macOS vs Linux date:** `github-archive-old-repos.sh` handles both BSD `date -v` (macOS) and GNU `date -d` (Linux)
+10. **Never edit CHANGELOG.md manually** — it is fully managed by Release Please via Conventional Commits
 
 ## Maintenance Matrix
 
 When you change one of these files, you must also update the files in the "Also update" column.
 
 | When you change… | Also update |
 |------------------|-------------|
-| `lib/github-common.sh` — any public function signature or behaviour | All 19 scripts that source it; verify each caller still passes the right arguments. Check with: `grep -r "source.*github-common" . --include="*.sh"` |
+| `lib/github-common.sh` — any public function signature or behaviour | All 18 scripts that source it; verify each caller still passes the right arguments. Check with: `grep -r "github-common" . --include="*.sh"` |
 | `lib/github-common.sh` — add a new helper function | `AGENTS.md` shared library table; `README.md` if the function affects usage |
-| Any script's required env vars | That script's `# ===` header comment; the corresponding README.md section's env var table |
-| Any script's optional env vars or defaults | Same as above |
-| Any script's `--dry-run` or CLI flag behaviour | README.md usage example for that script |
+| Any script's required env vars | That script's `# ===` header comment; the corresponding README.md section's env var table; that script's `action.yml` inputs (add/remove required inputs to match) |
+| Any script's optional env vars or defaults | Same as above; update the `action.yml` optional inputs and their defaults |
+| Any script's `--dry-run` or CLI flag behaviour | README.md usage example for that script; that script's `action.yml` inputs and `run:` step flag construction |
 | `README.md` — script documentation | Verify the script's `# ===` header comment still matches (env vars, options, requirements) |
 | `.githooks/pre-commit` | `install-hooks.sh` if hook path or installation instructions change; README.md Best Practices section |
 | `install-hooks.sh` | README.md Installation section |
-| Add a new script | `README.md` (add use case, env var table, usage example); `CHANGELOG.md` under `[Unreleased]` |
+| Add a new script | `action.yml` in the same directory; `README.md` (add use case, env var table, usage example, Available Actions table row) |
 | Add a new domain folder | `README.md` top-level structure description; `AGENTS.md` Repository Structure section |
 | `.github/workflows/ci.yml` — shellcheck flags | `.githooks/pre-commit` shellcheck invocation (keep them in sync) |
 | `.github/workflows/copilot-setup-steps.yml` — tool versions | `AGENTS.md` Tech Stack table |

.github/workflows/release.yml

@@ -0,0 +1,18 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5
+        with:
+          release-type: simple

.github/workflows/update-readme-sha.yml

@@ -0,0 +1,3 @@
+{
+  ".": "1.0.0"
+}

.release-please-manifest.json

@@ -52,6 +52,7 @@ github-api-scripts/
 | 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`) |
 
 ---
 
@@ -177,8 +178,9 @@ done
 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. **Add to README.md** — follow the existing format: use case, env var table, usage example, output format
-7. Place in the correct domain:
+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 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
+8. 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
@@ -192,6 +194,24 @@ done
 - **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`)
+- **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](https://www.conventionalcommits.org/). `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:` | none | hidden |
+| `test:` | none | hidden |
 
 ---
 
@@ -205,3 +225,4 @@ done
 - **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

AGENTS.md

@@ -2,44 +2,35 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+This changelog is automatically maintained by [Release Please](https://github.com/googleapis/release-please) using [Conventional Commits](https://www.conventionalcommits.org/). Do not edit the versioned sections manually.
 
-## [Unreleased]
-
-### Added
-- `github-install-enterprise-app` — programmatically installs an enterprise-owned automation GitHub App into an org using an installer GitHub App (JWT → installation token flow); supports `--dry-run` and optional org-scoped token verification. Adds `openssl` as a dependency
-- `github-copilot-report`: NDJSON usage-metrics endpoints, Entra ID enrichment via `az rest`, auto-detection of credits per seat with promo/standard table, `--no-entra` flag
-- README: GitHub Actions integration examples (workflow_dispatch, artifact upload, environment protection)
-- `.github/workflows/update-readme-sha.yml` — automatically updates the pinned commit SHA in README.md on every push to `main`
-
-### Changed
-- README: updated all `actions/checkout` references from `v4` to `v7.0.0` (pinned SHA `9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0`)
-- README: replaced `ref: main` in the GitHub Actions usage example with a pinned commit SHA, and updated the accompanying note to recommend SHA pinning
+<!-- Release Please inserts new entries above this line -->
 
 ---
 
-## [2026-06-21]
+## Pre-release history
 
-### Added
-- `github-copilot-report`: NDJSON usage-metrics endpoints, Entra ID enrichment via `az rest`, auto-detection of credits per seat with promo/standard table, `--no-entra` flag
-- README: GitHub Actions integration examples (workflow_dispatch, artifact upload, environment protection)
+### 2026-06-26
 
-### Changed
-- Validated all required environment variables across all scripts before any API calls
-- Improved error handling with descriptive exit messages throughout
+- feat: composite `action.yml` for all 16 automation scripts — each script is now usable as a `uses:` step in GitHub Actions workflows, enabling Dependabot to track and bump version pins automatically
+- feat: Release Please workflow for automated releases on push to `main`
+- feat: `github-install-enterprise-app` — programmatically installs an enterprise-owned GitHub App using a second installer app (JWT flow); supports `--dry-run`
+- feat: `github-copilot-report` — Copilot usage report with Entra ID enrichment, AI credit accounting, and new usage-metrics endpoints
+- fix: `github-archive-old-repos` — `REPORT_DIR` is now overridable via environment variable
+- chore: remove `update-readme-sha.yml` workflow (superseded by release tags)
+- docs: GitHub Actions section in README restructured to lead with composite action `uses:` syntax
 
----
+### 2026-06-21
 
-## [2026-06-20]
+- feat: `github-copilot-report` — NDJSON usage-metrics endpoints, Entra ID enrichment via `az rest`, credits per seat auto-detection
+- docs: GitHub Actions integration examples (workflow_dispatch, artifact upload, environment protection)
+- fix: validated all required environment variables across all scripts before any API calls
 
-### Added
-- `github-add-repo-permissions`: `REPO_NAME_FILTER` option to restrict permission grants to repos matching a name prefix
+### 2026-06-20
 
-### Changed
-- Enhanced validation for user-supplied inputs (slugs, regex patterns, date formats) across multiple scripts
-- Improved payload handling and JSON construction in enterprise scripts
+- feat: `github-add-repo-permissions` — `REPO_NAME_FILTER` option to restrict permission grants to repos matching a name prefix
+- fix: enhanced validation for user-supplied inputs (slugs, regex patterns, date formats) across multiple scripts
 
----
 
 ## [2026-06-19]