From 98d30b3f690e289f7042ae179aef78f8f0d27d22 Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 07:17:42 +1100 Subject: [PATCH 01/18] feat: add pre-commit hook manifest --- .pre-commit-hooks.yaml | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 .pre-commit-hooks.yaml diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml new file mode 100644 index 00000000..2b673bfa --- /dev/null +++ b/.pre-commit-hooks.yaml @@ -0,0 +1,10 @@ +- id: github-action-readme-generator + name: Generate GitHub Action README + description: Sync generated README sections from action.yml. + entry: github-action-readme-generator + language: node + language_version: 24.19.0 + minimum_pre_commit_version: 4.6.2 + always_run: true + pass_filenames: false + stages: [pre-commit] From 546303b1135d5c912f21c12a57b91a17cc167a9f Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 07:19:20 +1100 Subject: [PATCH 02/18] fix: skip dev bootstrap for global installs --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 01338920..c5833c52 100644 --- a/package.json +++ b/package.json @@ -67,7 +67,7 @@ "lint:markdown": "rumdl check --config .rumdl.toml .", "lint:markdown:fix": "npm run lint:markdown -- --fix", "pre-commit": "vp staged && npm run build && npm run generate-docs && npm run lint:markdown", - "prepare": "[ -n \"${GITHUB_ACTIONS:-}\" ] || { husky install; command -v vp >/dev/null 2>&1 || curl -fsSL https://viteplus.dev/install.sh | VP_NODE_MANAGER=no bash; }", + "prepare": "[ -n \"${GITHUB_ACTIONS:-}\" ] || [ \"${npm_config_global:-false}\" = \"true\" ] || { husky install; command -v vp >/dev/null 2>&1 || curl -fsSL https://viteplus.dev/install.sh | VP_NODE_MANAGER=no bash; }", "semantic-release": "semantic-release", "test": "vp test", "coverage": "vp test --coverage" From 7ee995b217d24bebda2da69811333445caf6ecd5 Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 07:20:08 +1100 Subject: [PATCH 03/18] docs: document pre-commit provider hook --- README.md | 24 +++++------------------- 1 file changed, 5 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 2ae33192..0ae1f3c4 100644 --- a/README.md +++ b/README.md @@ -154,33 +154,19 @@ You can modify the script below to include any extra variables you like or use n ### Using as a Pre-commit Hook -You can automate README generation on every commit by using this tool as a pre-commit hook. This ensures your documentation stays up-to-date automatically. +This repository publishes a pre-commit hook, so consumers do not need to install this package separately. -1. **Install the tool locally** (if you haven't already): - -```sh -npm install --save-dev github-action-readme-generator -# or -yarn add -D github-action-readme-generator -``` - -2. **Configure pre-commit**: - -Add the following to your `.pre-commit-config.yaml` file: +Add it to your `.pre-commit-config.yaml`: ```yaml repos: - - repo: local + - repo: https://github.com/bitflight-devops/github-action-readme-generator + rev: v2 hooks: - id: github-action-readme-generator - name: Generate README from action.yml - entry: npx github-action-readme-generator - language: system - files: ^(action\.yml|\.ghadocs\.json)$ - pass_filenames: false ``` -This configuration will automatically regenerate your README whenever `action.yml` or `.ghadocs.json` changes. +The hook runs on every commit so custom action, README, and config paths are covered. It manages its own supported Node runtime and does not pass staged filenames to the generator. ## Configuration From a16d26d6b329cd241f9b15fa921ce374428050bb Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 07:52:01 +1100 Subject: [PATCH 04/18] test: smoke test published pre-commit hook --- .github/workflows/integration-test.yml | 79 ++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/.github/workflows/integration-test.yml b/.github/workflows/integration-test.yml index f8aeee56..fc21cbef 100644 --- a/.github/workflows/integration-test.yml +++ b/.github/workflows/integration-test.yml @@ -361,3 +361,82 @@ jobs: run: | echo "✅ Integration test passed for ${{ matrix.repo }}" echo "The action successfully generated README from ${{ matrix.action_path }}" + + + pre-commit-hook: + name: Test published pre-commit hook + runs-on: ubuntu-latest + + steps: + - name: Checkout hook provider + uses: actions/checkout@v7.0.1 + with: + path: hook-source + + - name: Setup Python + uses: actions/setup-python@v6 + with: + python-version: '3.13' + + - name: Install pre-commit + run: python -m pip install pre-commit==4.6.2 + + - name: Create consumer fixture + run: | + mkdir consumer + cd consumer + git init + git config user.name "pre-commit smoke test" + git config user.email "pre-commit-smoke@example.invalid" + + cat > action.yml <<'YAML' + name: Consumer Action + description: Generated through the published pre-commit hook + runs: + using: composite + steps: [] + YAML + + cat > README.md <<'MARKDOWN' + # Consumer + + + stale description + + MARKDOWN + + cat > .ghadocs.json <<'JSON' + { + "owner": "example", + "repo": "consumer-action", + "paths": { + "action": "action.yml", + "readme": "README.md" + }, + "sections": ["description"], + "prettier": false + } + JSON + + git add action.yml README.md .ghadocs.json + git commit -m "test: add consumer fixture" + + - name: Install and run hook through pre-commit + working-directory: consumer + run: | + set +e + pre-commit try-repo ../hook-source github-action-readme-generator --all-files --verbose + first_status=$? + set -e + + if [ "$first_status" -eq 0 ]; then + echo "::error::first run should report the README modification" + exit 1 + fi + + grep -F "Generated through the published pre-commit hook" README.md + cp README.md README.after-first-run.md + git add README.md + + pre-commit try-repo ../hook-source github-action-readme-generator --all-files --verbose + cmp README.after-first-run.md README.md From 5cb051cdad5fa5e94bc947b0d9be9b321fad266e Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 07:53:02 +1100 Subject: [PATCH 05/18] test: exercise pre-commit hook from remote ref --- .github/workflows/integration-test.yml | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/.github/workflows/integration-test.yml b/.github/workflows/integration-test.yml index fc21cbef..caa13213 100644 --- a/.github/workflows/integration-test.yml +++ b/.github/workflows/integration-test.yml @@ -423,9 +423,14 @@ jobs: - name: Install and run hook through pre-commit working-directory: consumer + env: + HOOK_REPO: ${{ github.event.pull_request.head.repo.clone_url || format('https://github.com/{0}', github.repository) }} + HOOK_REF: ${{ github.event.pull_request.head.sha || github.sha }} run: | + pre-commit validate-manifest ../hook-source/.pre-commit-hooks.yaml + set +e - pre-commit try-repo ../hook-source github-action-readme-generator --all-files --verbose + pre-commit try-repo "$HOOK_REPO" --ref "$HOOK_REF" github-action-readme-generator --all-files --verbose first_status=$? set -e @@ -438,5 +443,5 @@ jobs: cp README.md README.after-first-run.md git add README.md - pre-commit try-repo ../hook-source github-action-readme-generator --all-files --verbose + pre-commit try-repo "$HOOK_REPO" --ref "$HOOK_REF" github-action-readme-generator --all-files --verbose cmp README.after-first-run.md README.md From 1ca17ef938dc5ad9dce577af982de7be54b0d279 Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 07:54:35 +1100 Subject: [PATCH 06/18] fix: keep dev bootstrap out of git package preparation --- package.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/package.json b/package.json index c5833c52..f3ec7d86 100644 --- a/package.json +++ b/package.json @@ -59,7 +59,7 @@ "format": "vp fmt --write ./src ./__tests__", "format:check": "vp fmt --check ./src ./__tests__", "generate-docs": "echo 'Generating docs' && node dist/bin/index.js && (git add README.md ./.github/ghadocs .ghadocs.json || true)", - "postinstall": "echo '✨ Successfully Installed'", + "postinstall": "echo '✨ Successfully Installed' && { [ -n \"${GITHUB_ACTIONS:-}\" ] || [ \"${npm_config_global:-false}\" = \"true\" ] || [ \"${INIT_CWD:-}\" != \"$PWD\" ] || { husky install; command -v vp >/dev/null 2>&1 || curl -fsSL https://viteplus.dev/install.sh | VP_NODE_MANAGER=no bash; }; }", "lint": "vp lint --type-aware --type-check ./src/ ./__tests__/ && npm run lint:markdown", "lint:fix": "vp lint --type-aware --type-check --fix ./src/ ./__tests__/ && npm run lint:markdown:fix", "check": "vp check ./src/ ./__tests__/", @@ -67,7 +67,6 @@ "lint:markdown": "rumdl check --config .rumdl.toml .", "lint:markdown:fix": "npm run lint:markdown -- --fix", "pre-commit": "vp staged && npm run build && npm run generate-docs && npm run lint:markdown", - "prepare": "[ -n \"${GITHUB_ACTIONS:-}\" ] || [ \"${npm_config_global:-false}\" = \"true\" ] || { husky install; command -v vp >/dev/null 2>&1 || curl -fsSL https://viteplus.dev/install.sh | VP_NODE_MANAGER=no bash; }", "semantic-release": "semantic-release", "test": "vp test", "coverage": "vp test --coverage" From c2c5b48628b9f19e98b8c97d3af18013c3db69d7 Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 07:57:09 +1100 Subject: [PATCH 07/18] fix: use pre-commit tested Node runtime --- .pre-commit-hooks.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml index 2b673bfa..93eea098 100644 --- a/.pre-commit-hooks.yaml +++ b/.pre-commit-hooks.yaml @@ -3,7 +3,7 @@ description: Sync generated README sections from action.yml. entry: github-action-readme-generator language: node - language_version: 24.19.0 + language_version: 26.7.0 minimum_pre_commit_version: 4.6.2 always_run: true pass_filenames: false From 30461fbffbafa697d0620a8078d03c472a6c9a2f Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 07:59:53 +1100 Subject: [PATCH 08/18] chore: keep package lifecycle unchanged --- package.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index f3ec7d86..01338920 100644 --- a/package.json +++ b/package.json @@ -59,7 +59,7 @@ "format": "vp fmt --write ./src ./__tests__", "format:check": "vp fmt --check ./src ./__tests__", "generate-docs": "echo 'Generating docs' && node dist/bin/index.js && (git add README.md ./.github/ghadocs .ghadocs.json || true)", - "postinstall": "echo '✨ Successfully Installed' && { [ -n \"${GITHUB_ACTIONS:-}\" ] || [ \"${npm_config_global:-false}\" = \"true\" ] || [ \"${INIT_CWD:-}\" != \"$PWD\" ] || { husky install; command -v vp >/dev/null 2>&1 || curl -fsSL https://viteplus.dev/install.sh | VP_NODE_MANAGER=no bash; }; }", + "postinstall": "echo '✨ Successfully Installed'", "lint": "vp lint --type-aware --type-check ./src/ ./__tests__/ && npm run lint:markdown", "lint:fix": "vp lint --type-aware --type-check --fix ./src/ ./__tests__/ && npm run lint:markdown:fix", "check": "vp check ./src/ ./__tests__/", @@ -67,6 +67,7 @@ "lint:markdown": "rumdl check --config .rumdl.toml .", "lint:markdown:fix": "npm run lint:markdown -- --fix", "pre-commit": "vp staged && npm run build && npm run generate-docs && npm run lint:markdown", + "prepare": "[ -n \"${GITHUB_ACTIONS:-}\" ] || { husky install; command -v vp >/dev/null 2>&1 || curl -fsSL https://viteplus.dev/install.sh | VP_NODE_MANAGER=no bash; }", "semantic-release": "semantic-release", "test": "vp test", "coverage": "vp test --coverage" From 95721b15c11203a3e00e6320d4cc42bbc447053b Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 07:59:57 +1100 Subject: [PATCH 09/18] fix: run pre-commit hook through provider wrapper --- .pre-commit-hooks.yaml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml index 93eea098..407d45fd 100644 --- a/.pre-commit-hooks.yaml +++ b/.pre-commit-hooks.yaml @@ -1,10 +1,8 @@ - id: github-action-readme-generator name: Generate GitHub Action README description: Sync generated README sections from action.yml. - entry: github-action-readme-generator - language: node - language_version: 26.7.0 - minimum_pre_commit_version: 4.6.2 + entry: scripts/pre-commit-hook.sh + language: script always_run: true pass_filenames: false stages: [pre-commit] From 060fc8318ee89eb6f5d1a6d35fd37293018fc193 Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 08:00:00 +1100 Subject: [PATCH 10/18] docs: describe pre-commit runtime requirement --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0ae1f3c4..6e0b86df 100644 --- a/README.md +++ b/README.md @@ -166,7 +166,7 @@ repos: - id: github-action-readme-generator ``` -The hook runs on every commit so custom action, README, and config paths are covered. It manages its own supported Node runtime and does not pass staged filenames to the generator. +The hook runs on every commit so custom action, README, and config paths are covered. It uses the consumer's Node/npm installation, requires a Node version supported by this package, and executes the npm release matching the selected repository revision. Staged filenames are not passed to the generator. ## Configuration From 805b7b31bedb0ab487fc542d0ea73133d44a5cd7 Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 08:00:04 +1100 Subject: [PATCH 11/18] test: provide supported Node runtime to hook consumer --- .github/workflows/integration-test.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/integration-test.yml b/.github/workflows/integration-test.yml index caa13213..74444482 100644 --- a/.github/workflows/integration-test.yml +++ b/.github/workflows/integration-test.yml @@ -378,6 +378,11 @@ jobs: with: python-version: '3.13' + - name: Setup Node.js for hook consumer + uses: actions/setup-node@v7.1.0 + with: + node-version: '24.19.0' + - name: Install pre-commit run: python -m pip install pre-commit==4.6.2 From 22899021f19091104003e6d09cb73576a2319b16 Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 08:00:25 +1100 Subject: [PATCH 12/18] feat: add pre-commit provider wrapper --- scripts/pre-commit-hook.sh | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100755 scripts/pre-commit-hook.sh diff --git a/scripts/pre-commit-hook.sh b/scripts/pre-commit-hook.sh new file mode 100755 index 00000000..d924ba5a --- /dev/null +++ b/scripts/pre-commit-hook.sh @@ -0,0 +1,13 @@ +#!/bin/sh +set -eu + +if ! command -v node >/dev/null 2>&1 || ! command -v npx >/dev/null 2>&1; then + echo "github-action-readme-generator pre-commit hook requires Node.js and npm/npx." >&2 + exit 1 +fi + +script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +package_json="$script_dir/../package.json" +version=$(node -e 'const fs = require("node:fs"); const p = JSON.parse(fs.readFileSync(process.argv[1], "utf8")); process.stdout.write(p.version);' "$package_json") + +exec npx --yes "github-action-readme-generator@$version" From 573c2f3b2104ee1ef860ee849aea09b9a072bf4a Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 08:02:26 +1100 Subject: [PATCH 13/18] fix: use current pre-commit script language --- .pre-commit-hooks.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml index 407d45fd..2c097107 100644 --- a/.pre-commit-hooks.yaml +++ b/.pre-commit-hooks.yaml @@ -2,7 +2,8 @@ name: Generate GitHub Action README description: Sync generated README sections from action.yml. entry: scripts/pre-commit-hook.sh - language: script + language: unsupported_script + minimum_pre_commit_version: 4.4.0 always_run: true pass_filenames: false stages: [pre-commit] From e79bd58fcaea83660aa869c87a4cb7558adbd87b Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 09:38:04 +1100 Subject: [PATCH 14/18] fix: forward pre-commit hook arguments --- scripts/pre-commit-hook.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/pre-commit-hook.sh b/scripts/pre-commit-hook.sh index d924ba5a..e4277a01 100755 --- a/scripts/pre-commit-hook.sh +++ b/scripts/pre-commit-hook.sh @@ -10,4 +10,4 @@ script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) package_json="$script_dir/../package.json" version=$(node -e 'const fs = require("node:fs"); const p = JSON.parse(fs.readFileSync(process.argv[1], "utf8")); process.stdout.write(p.version);' "$package_json") -exec npx --yes "github-action-readme-generator@$version" +exec npx --yes "github-action-readme-generator@$version" "$@" From 3e75f865f868dc3b751bd54ed9f121d60561cc62 Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 09:38:08 +1100 Subject: [PATCH 15/18] test: verify pre-commit hook arguments --- .github/workflows/integration-test.yml | 43 +++++++++++++++++++------- 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/.github/workflows/integration-test.yml b/.github/workflows/integration-test.yml index 74444482..749fab34 100644 --- a/.github/workflows/integration-test.yml +++ b/.github/workflows/integration-test.yml @@ -387,8 +387,11 @@ jobs: run: python -m pip install pre-commit==4.6.2 - name: Create consumer fixture + env: + HOOK_REPO: ${{ github.event.pull_request.head.repo.clone_url || format('https://github.com/{0}', github.repository) }} + HOOK_REF: ${{ github.event.pull_request.head.sha || github.sha }} run: | - mkdir consumer + mkdir -p consumer/docs cd consumer git init git config user.name "pre-commit smoke test" @@ -403,6 +406,14 @@ jobs: YAML cat > README.md <<'MARKDOWN' + # Default README + + + default README must stay stale + + MARKDOWN + + cat > docs/ACTION.md <<'MARKDOWN' # Consumer @@ -423,30 +434,38 @@ jobs: } JSON - git add action.yml README.md .ghadocs.json + cat > .pre-commit-config.yaml < Date: Tue, 13 Oct 2026 21:22:24 +1100 Subject: [PATCH 16/18] ci: avoid persisting hook checkout credentials --- .github/workflows/integration-test.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/integration-test.yml b/.github/workflows/integration-test.yml index 749fab34..9d09e193 100644 --- a/.github/workflows/integration-test.yml +++ b/.github/workflows/integration-test.yml @@ -372,6 +372,7 @@ jobs: uses: actions/checkout@v7.0.1 with: path: hook-source + persist-credentials: false - name: Setup Python uses: actions/setup-python@v6 From 14cb4b6f8090ac189767f80371cd3dadefc3d5b6 Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 21:26:11 +1100 Subject: [PATCH 17/18] docs: clarify pre-commit path support --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6e0b86df..5feca030 100644 --- a/README.md +++ b/README.md @@ -166,7 +166,7 @@ repos: - id: github-action-readme-generator ``` -The hook runs on every commit so custom action, README, and config paths are covered. It uses the consumer's Node/npm installation, requires a Node version supported by this package, and executes the npm release matching the selected repository revision. Staged filenames are not passed to the generator. +The hook runs on every commit so configurable action and README paths are covered. It uses the consumer's Node/npm installation, requires a Node version supported by this package, and executes the npm release matching the selected repository revision. Staged filenames are not passed to the generator. ## Configuration From dfbc0e8bdfcfa4fa6bcb4e7ef279743ca21ce33f Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 21:30:34 +1100 Subject: [PATCH 18/18] docs: defer released-hook usage until publication --- README.md | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 5feca030..2ae33192 100644 --- a/README.md +++ b/README.md @@ -154,19 +154,33 @@ You can modify the script below to include any extra variables you like or use n ### Using as a Pre-commit Hook -This repository publishes a pre-commit hook, so consumers do not need to install this package separately. +You can automate README generation on every commit by using this tool as a pre-commit hook. This ensures your documentation stays up-to-date automatically. -Add it to your `.pre-commit-config.yaml`: +1. **Install the tool locally** (if you haven't already): + +```sh +npm install --save-dev github-action-readme-generator +# or +yarn add -D github-action-readme-generator +``` + +2. **Configure pre-commit**: + +Add the following to your `.pre-commit-config.yaml` file: ```yaml repos: - - repo: https://github.com/bitflight-devops/github-action-readme-generator - rev: v2 + - repo: local hooks: - id: github-action-readme-generator + name: Generate README from action.yml + entry: npx github-action-readme-generator + language: system + files: ^(action\.yml|\.ghadocs\.json)$ + pass_filenames: false ``` -The hook runs on every commit so configurable action and README paths are covered. It uses the consumer's Node/npm installation, requires a Node version supported by this package, and executes the npm release matching the selected repository revision. Staged filenames are not passed to the generator. +This configuration will automatically regenerate your README whenever `action.yml` or `.ghadocs.json` changes. ## Configuration