Introducing breaking changes without bumping major version

[alec-drw]

Ensure the following before filing this issue

• I verified it reproduces with the latest version with - uses: ruby/setup-ruby@v1 (see Versioning policy)

• I tried to reproduce the issue locally by following the workflow steps (including all commands done by ruby/setup-ruby, except for Downloading Ruby & Extracting Ruby),
  and it did not reproduce locally (if it does reproduce locally, it's not a ruby/setup-ruby issue)

Are you running on a GitHub-hosted runner or a self-hosted runner?

self-hosted runner

Link to the failed workflow job (must be a public workflow job, so the necessary information is available)

N/A, GHE instance is not exposed to the public web

Any other notes?

Most common actions have been rolling out the newest change that uses node20 as the default runtime. As they do this, they have released it as a new major version, due to the fact that many users are running with self hosted runners that may not be running the latest version of the action runner.

Examples:

• https://github.com/actions/checkout/releases/tag/v4.0.0
• https://github.com/docker/metadata-action/releases/tag/v5.0.0

In addition, Github themselves had to quickly release a new version reverting this change as it broke so many workflows for users, see actions/runner#2918.

They finally added it via an environment variable ACTIONS_RUNNER_FORCED_INTERNAL_NODE_VERSION to support both cases, see actions/runner#2844

The newly release setup-ruby action from earlier today has broken many jobs on my enterprise instance, and our teams had to quickly edit their workflows to update from ruby/setup-ruby@v1 to ruby/setup-ruby@v1.158.0.

I would highly recommend adopting a process that uses semver properly to avoid introducing breaking changes.

[eregon]

I shared my opinion in #539 (comment).
This was also done for the previous node update (12 -> 16) and there was zero reported problem.

IMO it's far more work to update hundreds of thousands workflows to @v2 when none of them actually need that (the API of the action does not change at all), the real fix is to install node20, and that's the responsibility of whoever maintains the runner. Only them can do that.

I will not do v2, because I do not have time to maintain multiple branches and then users on v1 (i.e. all current users) would not get newer Ruby versions, while they didn't do anything wrong.

They finally added it via an environment variable ACTIONS_RUNNER_FORCED_INTERNAL_NODE_VERSION to support both cases, see actions/runner#2844

That seems a reasonable solution if node20 cannot easily be installed on your self-hosted runners for some reason.
Of course it's not actually tested and so not officially supported but is very likely to work.
Indeed this action doesn't really care about which node version it uses, but it should also not cause deprecation warnings like in #539 (comment).

[eregon]

Some more thoughts on this:

• Bumping to node20 is a seamless change for workflows using GitHub-hosted runners. In fact it even fixes a warning.
• Self-hosted runners can never be supported fully, because they can't be tested by this action and every self-hosted runner is potentially different. The docs in https://github.com/ruby/setup-ruby/blob/master/README.md#using-self-hosted-runners says: This action might work with self-hosted runners if the Runner Image is very similar to the ones used by GitHub runners. The same node version is part of that, we could add it to make it more explicit.
• It's unfortunate that action.yml cannot specify a version constraint like node >= 12, <= 20 (AFAIK), and that one cannot test an action easily with different node versions on GitHub-hosted runners (AFAIK). I would support a request to GitHub to make this possible, and it would be a proper solution to this issue.
• ACTIONS_RUNNER_FORCED_INTERNAL_NODE_VERSION is probably the best workaround until then for self-hosted runners, if they cannot reuse https://github.com/actions/runner-images to automatically keep their runner images up-to-date. EDIT: there is now ACTIONS_RUNNER_FORCE_ACTIONS_NODE_VERSION which you may be able to use for your self-hosted runners, see Create an env variable to force node12 actions to run on node16 actions/runner#1911.
• I could add a node16 tag or so, but not sure if it helps anything?
• Semantic versioning has no good solution when it comes to changes like this. A major version bump is e.g. a bad deal for workflows using GitHub-hosted runners, these users would want to still use the latest release with a compatible API (inputs, etc) like 1.x. Maybe a 4th digit or so would make sense, like APIcompatibility.dependenciesVersion.newFeature.bugFix or so.

[nekketsuuu]

I encountered this problem again on our self-hosted runners due to the recent upgrade to node24 runtime at v1.259.0: https://github.com/ruby/setup-ruby/releases/tag/v1.259.0.

I understand the support range of ruby/setup-ruby and respect it. I only want to share our situation here. Our self-hosted runners use the actions/runner scripts. The latest release of actions/runner, v2.328.0, just added an option for the node20 to node24 migration (https://github.com/actions/runner/releases/tag/v2.328.0), meaning our runners haven't support node24 yet. As a result, we are seeing the following error:

Error: System.ArgumentOutOfRangeException: Specified argument was out of the range of valid values. (Parameter ''using: node24' is not supported, use 'docker', 'node12', 'node16' or 'node20' instead.')
   at GitHub.Runner.Worker.ActionManifestManager.ConvertRuns(IExecutionContext executionContext, TemplateContext templateContext, TemplateToken inputsToken, String fileRelativePath, MappingToken outputs)
   at GitHub.Runner.Worker.ActionManifestManager.Load(IExecutionContext executionContext, String manifestFile)
Error: Failed to load ruby/setup-ruby/v1/action.yml

Since many other workflows bump their major version for their runtime Node.js version upgrade, ruby/setup-ruby is the only case that we see this kind of migration errors. As the deprecation of node20 has been announced today (https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/), we have just begun planning for the node24 migration on our end. I hope that GitHub could give us any workarounds such as eregon said at #541 (comment)...

[eregon]

@nekketsuuu Thanks for that info, there is more discussion at #806 and that answers some questions there.

Given https://github.com/actions/runner/releases/tag/v2.328.0 has been released 5 weeks ago, how often do you update your self-hosted runners? And is there a way to auto-update them regularly?
It also seems node24 was added in https://github.com/actions/runner/releases/tag/v2.327.1 (July 25), actions/runner#3948 seems about controlling the version used for all actions, which I don't think is necessary here to get things working, what is needed AFAIK is having both node20 and node24 on the runner.

[nekketsuuu]

@eregon Thanks for catching this up! I wrote my details there #806 (comment). I'm sorry that I was not aware the new issue has been created.