Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/release-notes/v0.3.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
**actnode v0.3.0** — ergonomics: `--latest`, release-notes links, Action PR mode.

- **`--latest`**: suggest the newest release that already runs on the target Node (default stays the smallest major jump). Also available as Action input `latest: true`.
- **Release-notes links**: every finding with a suggested bump includes a `release_notes` URL (`https://github.com/{owner}/{repo}/releases/tag/{tag}`). Shown in text (`notes: …`), Markdown (extra column), and JSON.
- **Action PR mode**: set `create-pr: true` (plus optional `pr-branch` / `pr-title`) to apply `--fix` and open or update a pull request when there is a diff. No PR if the diff is empty. Caller needs `contents: write` and `pull-requests: write`.

Docs: https://blackman99.github.io/actnode/docs/
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# Changelog

## v0.3.0 — 2026-10-19
- `--latest` (Action input `latest`): suggest the newest node24-capable release instead of the smallest major jump; default behavior unchanged
- Release-notes links on every suggested bump (`release_notes` in JSON; text `notes:` URL; Markdown column)
- Action optional PR mode: `create-pr` (+ `pr-branch` / `pr-title`) applies `--fix` and opens or updates a PR when there is a diff (needs `contents:write` + `pull-requests:write`)

## v0.2.0 — 2026-10-12
- Reusable workflows (`uses: org/repo/.github/workflows/x.yml@ref`) scanned recursively (status `workflow` / `wfl`); nested findings show `(inside …)` and are not rewritten by `--fix`
- Remote scan without cloning: `actnode --repo owner/name` and `actnode --org owner` (public non-fork repos by default; `--fix` refused)
Expand Down
13 changes: 8 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,12 @@ jobs:
- uses: actions/checkout@v7
- uses: Blackman99/actnode@v0
with:
fail: true # inputs: path (.), target (24), fail (true), token (github.token)
fail: true # also: path, target, latest, create-pr, pr-branch, pr-title, token
```

`@v0` is a moving major tag that always points at the latest v0.x release; pin `@v0.2.0` or a SHA if you prefer.
`@v0` is a moving major tag that always points at the latest v0.x release; pin `@v0.3.0` or a SHA if you prefer.

To open a PR with the `--fix` diff on a schedule, set `create-pr: true` and grant `contents: write` + `pull-requests: write` (see [Action docs](https://blackman99.github.io/actnode/docs/action/)).

## Install (CLI, to fix locally)

Expand All @@ -38,16 +40,17 @@ Python 3.9+, zero dependencies. Set `GITHUB_TOKEN` (e.g. `export GITHUB_TOKEN=$(

```console
$ actnode
[OLD] .github/workflows/ci.yml:7 node20 actions/checkout@v4 -> actions/checkout@v5
[OLD] .github/workflows/ci.yml:10 node20 actions/upload-artifact@v4 -> actions/upload-artifact@v6
[OLD] .github/workflows/ci.yml:7 node20 actions/checkout@v4 -> actions/checkout@v5 notes: https://github.com/actions/checkout/releases/tag/v5
[OLD] .github/workflows/ci.yml:10 node20 actions/upload-artifact@v4 -> actions/upload-artifact@v6 notes: https://github.com/actions/upload-artifact/releases/tag/v6
$ actnode --latest # newest node24 release instead of the smallest major jump
$ actnode --fix # rewrite those uses: lines (SHA pins get a SHA + version comment)
$ actnode --fail # exit 1 if anything is still old
$ actnode --repo owner/name # API scan, no clone
```

![demo](site/demo.gif)

It reads each action's real `action.yml` at the exact ref you pin, follows composite actions and reusable workflows, and suggests the **smallest** major bump that runs on Node 24. Scan a remote repo without cloning: `actnode --repo owner/name` (or `--org owner`).
It reads each action's real `action.yml` at the exact ref you pin, follows composite actions and reusable workflows, and suggests the **smallest** major bump that runs on Node 24 (or `--latest` for the newest). Each suggestion includes a release-notes link. Scan a remote repo without cloning: `actnode --repo owner/name` (or `--org owner`).

Full docs: [install](https://blackman99.github.io/actnode/docs/install/) · [usage](https://blackman99.github.io/actnode/docs/usage/) · [Action](https://blackman99.github.io/actnode/docs/action/) · [reference](https://blackman99.github.io/actnode/docs/reference/) · [FAQ](https://blackman99.github.io/actnode/docs/faq/)

Expand Down
2 changes: 1 addition & 1 deletion ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
- Org/repo mode: `actnode --repo owner/name` and `--org owner` without cloning (API only)
- Cache tag lookups across runs (`~/.cache/actnode`)

## v0.3 — ergonomics
## v0.3 (2026-10-19) — shipped
- `--latest` to suggest the newest node24 release instead of the smallest jump
- Show release-notes links for each major bump
- Optional PR mode for the Action (open a PR with the `--fix` diff)
Expand Down
98 changes: 92 additions & 6 deletions action.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
name: "actnode Node 24 runtime audit"
description: "Find workflow steps whose actions still run on Node 20 or older, and the release that moves each one to Node 24."
description: "Find workflow steps whose actions still run on Node 20 or older, suggest (or PR) the release that moves each one to Node 24."
author: "Blackman99"
branding:
icon: "arrow-up-right"
Expand All @@ -14,13 +14,31 @@ inputs:
fail:
description: "Fail the step when an old-runtime action is found (true/false)"
default: "true"
latest:
description: "Suggest the newest release already on the target Node instead of the smallest major jump (true/false)"
default: "false"
create-pr:
description: "Apply --fix and open a pull request when there is a diff (true/false). Caller needs contents:write and pull-requests:write."
default: "false"
pr-branch:
description: "Branch name for create-pr"
default: "actnode/node-runtime"
pr-title:
description: "Pull request title for create-pr"
default: "chore: bump actions to Node 24 runtime"
token:
description: "Token used to list tags of the actions you use"
description: "Token used to list tags (and to push/open a PR when create-pr is true)"
default: ${{ github.token }}
outputs:
report:
description: "Path to the JSON report"
value: ${{ steps.scan.outputs.report }}
pr-number:
description: "Number of the opened/updated PR when create-pr ran; empty otherwise"
value: ${{ steps.pr.outputs.pr-number }}
pr-url:
description: "URL of the opened/updated PR when create-pr ran; empty otherwise"
value: ${{ steps.pr.outputs.pr-url }}
runs:
using: composite
steps:
Expand All @@ -33,10 +51,78 @@ runs:
IN_PATH: ${{ inputs.path }}
IN_TARGET: ${{ inputs.target }}
IN_FAIL: ${{ inputs.fail }}
IN_LATEST: ${{ inputs.latest }}
IN_CREATE_PR: ${{ inputs.create-pr }}
run: |
set -euo pipefail
out="$RUNNER_TEMP/actnode.json"
python3 -m actnode scan "$IN_PATH" --target "$IN_TARGET" --format json -o "$out"
latest=()
[ "$IN_LATEST" = "true" ] && latest=(--latest)
python3 -m actnode scan "$IN_PATH" --target "$IN_TARGET" --format json -o "$out" "${latest[@]}"
echo "report=$out" >> "$GITHUB_OUTPUT"
fail=()
[ "$IN_FAIL" = "true" ] && fail=(--fail)
python3 -m actnode scan "$IN_PATH" --target "$IN_TARGET" --format md -o "$GITHUB_STEP_SUMMARY" "${fail[@]}"
python3 -m actnode scan "$IN_PATH" --target "$IN_TARGET" --format md -o "$GITHUB_STEP_SUMMARY" "${latest[@]}"
if [ "$IN_CREATE_PR" = "true" ]; then
python3 -m actnode scan "$IN_PATH" --target "$IN_TARGET" --fix "${latest[@]}"
elif [ "$IN_FAIL" = "true" ]; then
python3 -m actnode scan "$IN_PATH" --target "$IN_TARGET" --fail "${latest[@]}" >/dev/null
fi
- id: pr
if: inputs.create-pr == 'true'
shell: bash
env:
GH_TOKEN: ${{ inputs.token }}
GITHUB_TOKEN: ${{ inputs.token }}
IN_PATH: ${{ inputs.path }}
IN_TARGET: ${{ inputs.target }}
IN_PR_BRANCH: ${{ inputs.pr-branch }}
IN_PR_TITLE: ${{ inputs.pr-title }}
IN_FAIL: ${{ inputs.fail }}
run: |
set -euo pipefail
git_root="${GITHUB_WORKSPACE:-.}"
if [ -d "${IN_PATH}/.git" ]; then
git_root="$IN_PATH"
fi
cd "$git_root"
paths=()
[ -d .github/workflows ] && paths+=(.github/workflows)
[ -f action.yml ] && paths+=(action.yml)
[ -f action.yaml ] && paths+=(action.yaml)
if [ ${#paths[@]} -eq 0 ] || git diff --quiet -- "${paths[@]}"; then
echo "actnode: no workflow changes to propose"
echo "pr-number=" >> "$GITHUB_OUTPUT"
echo "pr-url=" >> "$GITHUB_OUTPUT"
else
branch="$IN_PR_BRANCH"
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git checkout -B "$branch"
git add -- "${paths[@]}"
if git diff --cached --quiet; then
echo "actnode: nothing staged for PR"
echo "pr-number=" >> "$GITHUB_OUTPUT"
echo "pr-url=" >> "$GITHUB_OUTPUT"
else
git commit -m "chore: bump GitHub Actions to Node ${IN_TARGET} runtime"
git push -u origin "HEAD:refs/heads/${branch}" --force-with-lease
body_file="$RUNNER_TEMP/actnode-pr-body.md"
python3 "${{ github.action_path }}/pr_body.py" \
"$RUNNER_TEMP/actnode.json" "$IN_TARGET" > "$body_file"
existing_json=$(gh pr list --head "$branch" --state open --json number,url 2>/dev/null || echo "[]")
num=$(printf '%s' "$existing_json" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d[0]['number'] if d else '')")
url=$(printf '%s' "$existing_json" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d[0]['url'] if d else '')")
if [ -n "$num" ]; then
gh pr edit "$num" --title "$IN_PR_TITLE" --body-file "$body_file" || true
echo "Updated PR #$num"
else
url=$(gh pr create --title "$IN_PR_TITLE" --body-file "$body_file" --head "$branch")
num=$(gh pr view "$branch" --json number --jq .number)
echo "Opened PR #$num → $url"
fi
echo "pr-number=$num" >> "$GITHUB_OUTPUT"
echo "pr-url=$url" >> "$GITHUB_OUTPUT"
fi
fi
if [ "$IN_FAIL" = "true" ]; then
REPORT="$RUNNER_TEMP/actnode.json" python3 -c 'import json,os,pathlib,sys; data=json.loads(pathlib.Path(os.environ["REPORT"]).read_text(encoding="utf-8")); sys.exit(1 if any(f.get("status") in ("old","no-fix") for f in data.get("findings",[])) else 0)'
fi
39 changes: 37 additions & 2 deletions docs/action.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ jobs:
fail: true
```

`@v0` is a moving major tag that always points at the latest v0.x release (pin `@v0.2.0` or a SHA for a fixed version).
`@v0` is a moving major tag that always points at the latest v0.x release (pin `@v0.3.0` or a SHA for a fixed version).

The step writes a Markdown table to the job summary and fails if any step uses an action older than Node 24.

Expand All @@ -24,10 +24,45 @@ The step writes a Markdown table to the job summary and fails if any step uses a
| `path` | `.` | repository root to scan |
| `target` | `24` | minimum Node major |
| `fail` | `true` | fail the step when something old is found |
| `token` | `github.token` | used to list tags of the actions you use |
| `latest` | `false` | suggest the newest release already on the target Node instead of the smallest major jump |
| `create-pr` | `false` | apply `--fix` and open a PR when there is a diff |
| `pr-branch` | `actnode/node-runtime` | branch name for `create-pr` |
| `pr-title` | `chore: bump actions to Node 24 runtime` | PR title for `create-pr` |
| `token` | `github.token` | used to list tags; also to push/open a PR when `create-pr` is true |

## Outputs

| Output | Meaning |
|---|---|
| `report` | path to the JSON report |
| `pr-number` | number of the opened/updated PR when `create-pr` ran (empty otherwise) |
| `pr-url` | URL of that PR (empty otherwise) |

## Optional PR mode

For a scheduled (or `workflow_dispatch`) workflow on the default branch, actnode can rewrite `uses:` lines and open a PR:

```yaml
name: node-runtime-pr
on:
schedule:
- cron: "0 9 * * 1"
workflow_dispatch:
permissions:
contents: write
pull-requests: write
jobs:
bump:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: Blackman99/actnode@v0
with:
create-pr: true
fail: false # PR opened; don't fail the job after proposing fixes
# latest: true # optional: jump to the newest node24 release
```

- No PR is opened when `--fix` produces an empty diff.
- An existing open PR on `pr-branch` is updated (force-with-lease push + title/body edit).
- The calling workflow needs `contents: write` and `pull-requests: write` (and a token that can push — default `github.token` is enough for same-repo PRs).
5 changes: 4 additions & 1 deletion docs/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ It runs node20 actions on Node 24 today, but the deprecation annotation still fi
Dependabot opens version bumps if it's configured for `github-actions`, one PR per action, and doesn't tell you which ones are about the runtime or which are hidden inside composite actions. actnode answers the runtime question across the whole repo in one run, and works where Dependabot isn't set up.

**Why the smallest major and not the latest?**
Fewer breaking changes. `actions/checkout@v5` already runs on Node 24; you don't need to jump to v7 to clear the warning. Pick the latest on your own schedule.
Fewer breaking changes. `actions/checkout@v5` already runs on Node 24; you don't need to jump to v7 to clear the warning. Pass `--latest` (or Action input `latest: true`) when you *do* want the newest node24-capable release.

**An action has no Node 24 release. Now what?**
actnode reports it as `OLD` with "no release on node24 yet". Look for an open issue upstream (many exist: search "Node.js 24" in that repo), fork and change `runs.using`, or replace the action.
Expand All @@ -23,3 +23,6 @@ Yes: `actnode --repo owner/name` or `actnode --org owner`. Org mode scans public

**Where are tags cached?**
Under `~/.cache/actnode` (or `$XDG_CACHE_HOME/actnode`), 24h TTL. Use `--no-cache` to bypass.

**Where do release-notes links come from?**
Each suggested bump includes a `release_notes` URL pointing at `https://github.com/{owner}/{repo}/releases/tag/{tag}` for the suggested tag. Shown in text, Markdown, and JSON output.
6 changes: 4 additions & 2 deletions docs/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
```
actnode [scan] [PATH] [--repo OWNER/NAME] [--org OWNER]
[--target N] [--format text|json|md] [-o FILE]
[--fix] [--fail] [--all] [--no-cache]
[--fix] [--latest] [--fail] [--all] [--no-cache]
actnode demo
actnode --version
```
Expand All @@ -17,6 +17,7 @@ actnode --version
| `--format` | `text` (default), `json` (every finding), `md` (problem table, for job summaries) |
| `-o FILE` | write to a file; `md` appends (so it works with `$GITHUB_STEP_SUMMARY`) |
| `--fix` | rewrite direct `uses:` lines to the suggested ref (local PATH only) |
| `--latest` | suggest the newest release already on the target Node (default: smallest major jump) |
| `--fail` | exit code 1 if any step uses an older runtime |
| `--all` | in text mode, also show `ok`, composite, workflow and docker steps |
| `--no-cache` | skip the on-disk tag cache (`~/.cache/actnode` / `$XDG_CACHE_HOME/actnode`) |
Expand All @@ -40,7 +41,8 @@ Exit codes: `0` ok, `1` old runtime found with `--fail`, `2` usage error or GitH
```json
{"target": 24, "findings": [
{"file": ".github/workflows/ci.yml", "line": 7, "uses": "actions/checkout@v4",
"runtime": "node20", "status": "old", "suggest": "actions/checkout@v5", "via": null, "note": ""}
"runtime": "node20", "status": "old", "suggest": "actions/checkout@v5", "via": null, "note": "",
"release_notes": "https://github.com/actions/checkout/releases/tag/v5"}
]}
```

Expand Down
14 changes: 14 additions & 0 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,20 @@ Findings are labeled `owner/repo:.github/workflows/ci.yml`. Forks and archived r

`PATH`, `--repo`, and `--org` are mutually exclusive.

## Latest vs smallest jump

By default actnode suggests the **smallest major** that already runs on Node 24 (fewer breaking changes). Pass `--latest` to jump straight to the newest release that is already on the target Node:

```bash
actnode # -> actions/checkout@v5 (smallest jump)
actnode --latest # -> actions/checkout@v7 (newest on node24)
actnode --latest --fix
```

## Release notes

Every finding with a suggested bump includes a `release_notes` URL (GitHub releases page for that tag). Text mode prints `notes: https://…`; Markdown adds a **Release notes** column; JSON adds a `release_notes` field.

## Fix

```bash
Expand Down
46 changes: 46 additions & 0 deletions pr_body.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
"""Build a markdown PR body from an actnode JSON report. Usage: pr_body.py REPORT.json TARGET > body.md"""
from __future__ import annotations

import json
import sys
from pathlib import Path


def main(argv=None):
argv = list(sys.argv[1:] if argv is None else argv)
report = Path(argv[0])
target = argv[1] if len(argv) > 1 else "24"
lines = [
"## actnode Node runtime bump",
"",
"Opened by [actnode](https://github.com/Blackman99/actnode) (`create-pr: true`).",
f"Direct `uses:` lines were rewritten to releases that already run on Node {target}.",
"Major bumps can carry breaking changes — read the release-notes links before merging.",
"",
]
if report.is_file():
data = json.loads(report.read_text(encoding="utf-8"))
old = [f for f in data.get("findings", []) if f.get("status") in ("old", "no-fix")]
if not old:
lines.append(
f"All JavaScript actions already run on node{data.get('target', target)} or newer."
)
else:
lines += [
"| Where | Action | Runtime | Upgrade to | Release notes |",
"|---|---|---|---|---|",
]
for f in old:
up = f"`{f['suggest']}`" if f.get("suggest") else (f.get("note") or "")
via = f" (via `{f['via']}`)" if f.get("via") else ""
notes = f"[notes]({f['release_notes']})" if f.get("release_notes") else ""
lines.append(
f"| `{f['file']}:{f['line']}` | `{f['uses']}`{via} | "
f"{f.get('runtime') or ''} | {up} | {notes} |"
)
sys.stdout.write("\n".join(lines) + "\n")
return 0


if __name__ == "__main__":
raise SystemExit(main())
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "hatchling.build"

[project]
name = "actnode"
version = "0.2.0"
version = "0.3.0"
description = "Find GitHub Actions steps still running on Node 20 (or older) and the release that moves each one to Node 24; optionally rewrite them."
readme = "README.md"
requires-python = ">=3.9"
Expand Down
2 changes: 1 addition & 1 deletion src/actnode/__init__.py
Original file line number Diff line number Diff line change
@@ -1 +1 @@
__version__ = "0.2.0"
__version__ = "0.3.0"
Loading
Loading