Node 20 -> Node 24 migration feature flagging, opt-in and opt-out environment variables

[salmanmkc]

Node 20 to Node 24 Migration Strategy

This is a proposal for the migration strategy, nothing here is 100% confirmed yet.

Overview

This PR implements the migration strategy for GitHub Actions JavaScript/TypeScript actions from Node 20 to Node 24, preparing for Node 20's end of life. The approach uses feature flags for a phased rollout, similar to the previous Node 16 to Node 20 migration.

Key Features

• Phased migration with clear transition points
• User controls via environment variables
• Feature flags for controlled rollout
• Compatibility handling for Linux ARM32
• Informative messaging to guide users through the transition

Migration Phases

Phase 1: Node 20 Default

Initially Node 20 remains the default:

• Default: Node 20
• Opt-in to Node 24: Set FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true

Phase 2: Node 24 Default

When the actions.runner.usenode24bydefault flag is enabled:

• Default: Node 24
• Temporary fallback to Node 20: Set ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true
• Informational message appears explaining Node 20 deprecation and opt-out options

Phase 3: Node 24 Required

When the actions.runner.requirenode24 flag is enabled:

• All actions use Node 24
• No opt-out options available

Environment Variables

The migration uses two environment variables:

• FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true: Opt into Node 24 during Phase 1
• ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true: Fall back to Node 20 during Phase 2

These can be set at either the workflow level (in YAML) or runner level (system environment). Workflow settings override runner settings to ensure job-specific control.

Implementation Details

Core Components

The migration strategy includes:

1. Centralized Constants

   • Version identifiers: Node20 and Node24
   • Environment variable definitions
   • Feature flag definitions

2. Version Selection Logic

   • Logic that factors in:
     • Current migration phase
     • Environment variables (workflow and runner)
     • Action metadata
     • Platform compatibility

3. User Feedback

   • Warning when conflicting settings are detected
   • Helpful messages during Phase 2 explaining the Node version change
   • Clear instructions for temporarily using Node 20 when needed

4. Platform Compatibility

   • Special handling for Linux ARM32 where Node 24 isn't supported
   • Automatic fallback to Node 20 with explanatory message
   • Multiple safeguards to ensure consistent behavior

Testing & Compatibility

Tests cover:

• Various feature flag and environment variable combinations
• All migration phases
• Environment variable precedence scenarios
• Platform-specific behavior (including ARM32)
• Conflict detection

Backward compatibility is maintained through:

• Zero-change workflow execution during migration
• Clear warning messages for configuration issues
• Automatic fallbacks on unsupported platforms
• Feature-flagged rollout for controlled deployment

Node Version Selection Logic - Truth Table

Variable Precedence

• Workflow-level variables always take precedence over System-level variables for the same variable
• Each variable (FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 and ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION) is evaluated independently
• Variables from different sources can be combined in the final decision

Phase 1: Node 20 Default (No Feature Flags)

ForceNode24 (Workflow)	AllowUnsecure (Workflow)	ForceNode24 (System)	AllowUnsecure (System)	Resulting Node Version	Notes
true	true	-	-	Node 20	Warning: conflicting settings
true	false	-	-	Node 24
true	-	-	-	Node 24
false	true	-	-	Node 20
false	false	-	-	Node 20
false	-	-	-	Node 20
-	true	-	-	Node 20
-	false	-	-	Node 20
-	-	true	true	Node 20	Warning: conflicting settings
-	-	true	false	Node 24
-	-	true	-	Node 24
-	-	false	true	Node 20
-	-	false	false	Node 20
-	-	false	-	Node 20
-	-	-	true	Node 20
-	-	-	false	Node 20
-	-	-	-	Node 20	Default

Phase 2: Node 24 Default (useNode24ByDefault=true)

ForceNode24 (Workflow)	AllowUnsecure (Workflow)	ForceNode24 (System)	AllowUnsecure (System)	Resulting Node Version	Notes
true	true	-	-	Node 20	Warning: conflicting settings
true	false	-	-	Node 24
true	-	-	-	Node 24
false	true	-	-	Node 20
false	false	-	-	Node 24
false	-	-	-	Node 24
-	true	-	-	Node 20
-	false	-	-	Node 24
-	-	true	true	Node 20	Warning: conflicting settings
-	-	true	false	Node 24
-	-	true	-	Node 24
-	-	false	true	Node 20
-	-	false	false	Node 24
-	-	false	-	Node 24
-	-	-	true	Node 20
-	-	-	false	Node 24
-	-	-	-	Node 24	Default
true	-	-	true	Node 20	Important edge case: AllowUnsecure=true always takes precedence in Phase 2
-	true	true	-	Node 20	Important edge case: AllowUnsecure=true always takes precedence in Phase 2

Phase 3: Node 24 Required (requireNode24=true)

In Phase 3, the environment variables are ignored and Node 24 is always used.

Notable Edge Cases

1. Mixed-Source Variables (Workflow vs System)

When variables come from different sources, each is evaluated independently:

Example: ForceNode24=false (Workflow), AllowUnsecure=true (System)

• The workflow explicitly opts out of Node 24 by setting ForceNode24=false
• The system has AllowUnsecure=true
• Result: Node 20 is used (workflow's opt-out from Node 24 is respected)

Example: AllowUnsecure=false (Workflow), ForceNode24=true (System)

• The workflow explicitly disallows Node 20 by setting AllowUnsecure=false
• The system has ForceNode24=true
• Result: Node 24 is used (system's ForceNode24 is respected since workflow doesn't override it)

Key Edge Case in Phase 2: When both variables are true (from any sources)

• If ForceNode24=true (Workflow) and AllowUnsecure=true (System)
• Or ForceNode24=true (System) and AllowUnsecure=true (Workflow)
• Result: Node 20 is used because AllowUnsecure=true takes precedence in Phase 2
• This is logical since in Phase 2, Node 24 is already the default, so the request to use Node 20 is more important

2. Conflicting Settings

When both variables are set to true from the same source (both from workflow or both from system):

• Warning message is displayed
• Default version for the current phase is used
• Workflow level conflicts trigger the same behavior as system level conflicts

3. ARM32 Linux Platform Compatibility

For Linux ARM32 platforms, Node 24 is not supported:

• If Node 24 would normally be selected, it automatically falls back to Node 20
• Warning message is displayed explaining the compatibility issue
• This occurs regardless of environment variables or feature flags

4. Phase 2 User Notification

In Phase 2, when Node 24 is selected:

• Users see an informational message explaining that Node 20 is deprecated
• Instructions are provided for temporarily using Node 20 if needed

Environment Variable Examples

Opt-in to Node 24 using workflow environment variable

You can opt in to Node 24 during Phase 1 by adding the environment variable to your workflow:

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

jobs:
  build:
    runs-on: node24
    
    steps:
      - uses: actions/checkout@v4

This forces actions like actions/checkout@v4 (which normally uses Node 20) to run with Node 24 instead:

Opt-in to Node 24 using system environment variable

You can also opt in at the runner level by setting the system environment variable:

This is how it behaves when node24 is default

When node24 is default, actions can be opted out using the ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION environment variable

ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION

For example:

on:
  workflow_dispatch:

env:
  ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: true

jobs:
  build:
    runs-on: node24
    
    steps:
      - uses: actions/checkout@v4

Environment Variable Precedence

When both system-level and workflow-level environment variables are set:

1. Workflow-level variables always take precedence over system-level variables for the same variable
2. Variables are evaluated independently based on their source
3. In Phase 1 (Node 20 default):
   • If FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true, Node 24 is used
   • Otherwise, Node 20 is used
4. In Phase 2 (Node 24 default):
   • If ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true, Node 20 is used
   • Otherwise, Node 24 is used