actions/checkout v5: Fix Node 24 Runner Errors Safely

What changed in checkout v5#

The checkout v5.0.0 release moved the action to Node 24 and lists v2.327.1 as the minimum compatible runner. The checkout README repeats that boundary.

This is an action-runtime change, not a new checkout input. Settings such as fetch-depth, fetch-tags, submodules, sparse-checkout, and persist-credentials keep their own meanings. Do not remove them just because the major version changed.

Choose the checkout version before migrating#

actions/checkout@v5 is still the version this error points to, but it is not the current upstream release. The checkout README currently documents v7, so treat the runner fix and the version upgrade as separate decisions:

The guard is not a v7-only change. GitHub backported it to supported major lines on 2026-07-20: v2.8.0, v3.7.0, v4.4.0, v5.1.0, and v6.1.0; v7.0.0 already included it. A floating major reference such as actions/checkout@v5 receives the backport, but a pinned minor, patch, or commit SHA does not move automatically. If checkout starts failing only for fork pull requests after a tag update, check the trigger and ref before treating it as a Node 24 runner error.

Do not jump from a v5 runner error to a blanket action upgrade. First prove the runner version, then choose the version whose security and container behavior matches the workflow.

The smallest workflow diff is usually:

1
steps:
2
  - name: Check out repository
3
    uses: actions/checkout@v5

If the existing workflow has with: options, keep them while making the version change:

1
- uses: actions/checkout@v5
2
  with:
3
    fetch-depth: 0
4
    persist-credentials: false

fetch-depth: 0 is still an intentional choice for workflows that need tags or full history. It is not required for Node 24 compatibility.

Check the runner before changing more code#

GitHub-hosted runners are maintained by GitHub, but self-hosted runners are part of your infrastructure. Check the version of every eligible self-hosted runner, not only the machine you used for a local test. A label can route the same job to an older machine on the next run.

You can inspect runner versions in the repository or organization Actions settings. With suitable read permission, the REST API also exposes each runner’s version:

1
gh api --paginate repos/OWNER/REPO/actions/runners \
2
  --jq '.runners[] | [.name, .os, .architecture, .status, .busy, .version] | @tsv'

Replace OWNER/REPO and treat the output as inventory data. Do not paste registration tokens or other credentials into a bug report. If the runner is below 2.327.1, upgrade the runner application using the installation instructions for its operating system, then wait for it to reconnect before testing checkout v5.

The self-hosted runner documentation is the right place to check the runner’s update and platform requirements. An action’s Node runtime support and the host’s operating-system support are separate checks; the Node 24 runner troubleshooting guide covers that wider boundary.

Verify the migration with a representative job#

Use a branch or a low-risk workflow first. The test should cover the real behavior that follows checkout, not only whether the action step turns green.

1. Confirm the job is scheduled on the runner class you intend to upgrade.
2. Run actions/checkout@v5 with the same ref, history depth, submodule, or sparse-checkout settings used in production.
3. Check that the next step can read the expected files and, when needed, tags or commit history.
4. Run the workflow on every self-hosted label that can receive the production job.
5. Keep the workflow diff and runner upgrade in the same change record so a future rollback is understandable.

For a diagnostic workflow, printing non-secret runner metadata can make the boundary visible:

1
- name: Show runner boundary
2
  shell: bash
3
  run: |
4
    echo "runner=${RUNNER_NAME}"
5
    echo "os=${RUNNER_OS} arch=${RUNNER_ARCH}"
6

7
- uses: actions/checkout@v5

The checkout action does not turn a shallow clone into a full clone. If a later step runs git describe, compares branches, or reads tags, validate those inputs explicitly instead of attributing the failure to the Node runtime.

Common failure paths#

FAQ#