node-version as fallback of node-version-file

Description

Currently the behavior is that node-version is preferred rather than node-version-file if both are provided.

Lines 85 to 95 in d86ebcd

    
           if (version && versionFileInput) { 
        
             core.warning( 
        
               'Both node-version and node-version-file inputs are specified, only node-version will be used' 
        
             ); 
        
           } 
        
           if (version) { 
        
             return version; 
        
           } 
        
           if (versionFileInput) {

I would like to propose the opposite since node-version is actually hardcoded in the action parameters, but the file is not guaranteed to be there.

setup-node/src/util.ts

Lines 8 to 12 in d86ebcd

    
           if (!fs.existsSync(versionFilePath)) { 
        
             throw new Error( 
        
               `The specified node version file at: ${versionFilePath} does not exist` 
        
             ); 
        
           }

Currently, scenarios resolved as following:

with:
  node-version: 8 # nothing to see here

with:
  node-version-file: fileExists.json # all good

with:
  node-version-file: fileDoesNotExists.json # throws error and crashes the pipeline

with:
  node-version: 8
  node-version-file: fileExists.json # ignored, picked version is 8

with:
  node-version: 8
  node-version-file: fileDoesNotExists.json # ignored, picked version is 8

What I'm requesting for is a change in the 2 lasts scenarios:

with:
  node-version: 8
  node-version-file: fileExists.json # has priority, so it's picked

with:
  node-version: 8
  node-version-file: fileDoesNotExists.json # does not throw and picks version 8 instead

Justification

This is just a nicer API, i think. it does not remove the case of conscious crash of the pipeline if no node-version is given, but it does nicely propose a fail-safe for people interested.

Note

We could also have another parameter such as node-version-fallback-if-file-not-found but it'd just increase the complexity of the api.

Are you willing to submit a PR?

Yes, i'm ok with that.

@y-nk

Hello @y-nk
Thank you for creating this issue, we will investigate it and come back to you as soon as we have some feedback.

To me this feels backwards; generally, config files are the default and "inline settings/flags" override the defaults. If you're specifying a node-version, then you most likely prefer that one over the "project-level" version defined in the package.json

@fregante

@fregante that is untrue, especially in monorepos where the node-version file can be there (or not) depending on the package/service running the job, but you could always use a hardcoded base version as a fallback.

I don’t think "monorepos" are the standard. I'm thinking more about CLIs and literally everything else:

Use call flag
Use local config
Use global config
Use default

I don’t think it should be anything but that.

@fregante

@fregante i understand your standpoint. as a mean not to remain unblocked, would you have any recommendation for something less verbose/more elegant than this:

    - if: ${{ !inputs.workspaceRelativePath }}
      uses: actions/setup-node@v4
      with:
        node-version: 20
        cache: 'pnpm'
        registry-url: https://npm.pkg.github.com/
        scope: '@company'

    - if: ${{ inputs.workspaceRelativePath }}
      uses: actions/setup-node@v4
      with:
        node-version-file: ${{ format('{0}/.node-version', inputs.workspaceRelativePath) }}
        cache: 'pnpm'
        registry-url: https://npm.pkg.github.com/
        scope: '@company'

?

@fregante

I agree with @fregante in that I expect my explicitly given parameter in the CI workflow file to have more weight than the files in the repo. My CI workflow is there to keep repo file changes in check. Maybe we can have a weak option fallback-node-version; albeit I'd prefer combining all of the possibilities into just node-version as a priority list. You could then specify something like >=16; file:package.json; file:.nvmrc; ; 0; 18; 20 that works like this:

>=16 sets a mandatory requirement. If our decision would conflict with that, it's a fatal error.
file:package.json if possible, decide by this file and ignore further entries.
file:.nvmrc if possible, decide by this file and ignore further entries.
(empty) ignore. The calling workflow probably had a variable insertion here that happened to not be used in this case.
0: Similar to empty but probably as result of a math operation with empty inputs. For convenience we should ignore literal 0; if someone really wants 0.x they can add the .x or prepend a =.
18 a literal version. Since this decision mechanism will always succeed, the list will effectively end here.
20 probably an accident since this can never be reached. We could consider warning users about this, or silently ignore it because the previous 18 may have been from an optional parameter like the empty slot was.

Update: I don't fully understand the PATH problem in #912, but it seems to in some way be a version number oracle, so we shoudl probably support it here as well. Name could be path or existing (not sure if I understood the intent enough).

I have an issue closely related to this that is related to use of multiple node version

$ cat .tool-versions 
nodejs 20.18.0 18.20.4

Basically the .tool-versions file defines two different node versions that are supported by the project, with 20 being the implicit one.

Currently it seems impossible to use actions/setup-node to create a test matrix that uses these two versions as there is no argument that I pass to tell it to use one or another.

This means that if I want to test both, I have to copy the exact version from the .tool-versions into all the GHA workflows that are running with both versions and also to find a magic way to keep this in sync, so they will not diverge.

Does anyone have a workaround for this issue?

@ssbarnea

@ssbarnea you need to create a first job which will read the .tool-versions and build a json out of it (using job outputs), then pass that json to a 2nd job into your matrix.

job1:
  runs-on: ubuntu-latest
  outputs:
    node-versions: ${{ steps.tool-versions.outputs.result }}

  steps:
    - id: tool-versions
      run: |
        # this bash was suggested by chatgpt.
        result=$(cat .tool-versions | jq -R 'split(" ") | { (.[0]): .[1:] } | .nodejs')
        echo "result=$result" >> $GITHUB_OUTPUT

job2:
  needs: job1
  runs-on: ubuntu-latest
  strategy:
    matrix:
      node-version: ${{ fromJSON(needs.job1.outputs.node-versions) }}
  steps:
    - uses: actions/setup-node@v5
      node-version: ${{ matrix.node-version }}

drafted hastily so some typos may occur ; general idea is there.

@y-nk

Hi @y-nk , thank you for the thoughtful suggestion. We understand the value this change could bring in terms of flexibility and reducing pipeline errors. However, after an internal review, we’ve decided not to move forward with it at this time, as the current behavior is widely used and changing it would introduce a breaking change that could impact existing workflows.

While we agree that the proposed fallback adds convenience, it also introduces added complexity and the potential for confusion when both inputs are provided. As a workaround, users can still read the version from a file within their workflow and pass it explicitly to the node-version input.

We truly appreciate your input and will keep this idea in mind as we consider future improvements.

@aparnajyothi-y if it is agreed to be a nice thing but i would be breaking, why not have it and bump the version by a major (which is the common practice when having a breaking change)?

@y-nk

Hi @y-nk, Thanks for the follow-up. You make a fair point about handling breaking changes with a major version bump. However, given the wide adoption of the current behavior, we've opted to avoid changes that could disrupt existing workflows, even with a version bump.

We agree your suggestion offers value and will keep it in mind for future enhancements, especially as we explore ways to improve flexibility without impacting backward compatibility. That said, we’re always open to revisiting this based on community feedback and evolving needs so please keep the suggestions coming.
Please feel free to reach us in case further clarification / concerns :)

Navigation Menu

Repository navigation

node-version as fallback of node-version-file #939

Description

Justification

Note

Are you willing to submit a PR?

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	if (version && versionFileInput) {
	core.warning(
	'Both node-version and node-version-file inputs are specified, only node-version will be used'
	);
	}

	if (version) {
	return version;
	}

	if (versionFileInput) {

	if (!fs.existsSync(versionFilePath)) {
	throw new Error(
	`The specified node version file at: ${versionFilePath} does not exist`
	);
	}

node-version as fallback of node-version-file #939

Description

Description

Justification

Note

Are you willing to submit a PR?

Activity

v-aparnajyothi-y commented on Jan 10, 2024

fregante commented on Feb 8, 2024

y-nk commented on Apr 18, 2024

fregante commented on Apr 18, 2024

y-nk commented on Apr 24, 2024

mk-pmb commented on Jun 12, 2024

ssbarnea commented on Oct 23, 2024

y-nk commented on Nov 19, 2024

v-aparnajyothi-y commented on May 15, 2025

y-nk commented on May 15, 2025

v-aparnajyothi-y commented on Jul 24, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions