Add support for importantSettings to override lower priority settings

Actions/.Modules/ReadSettings.psm1

@@ -16,9 +16,16 @@ $CustomTemplateProjectSettingsFile = Join-Path '.github' $CustomTemplateProjectS
 function MergeCustomObjectIntoOrderedDictionary {
     Param(
         [System.Collections.Specialized.OrderedDictionary] $dst,
-        [PSCustomObject] $src
+        [PSCustomObject] $src,
+        [string[]] $importantSettingsFromHigherPriority = @(),
+        [ref]$importantSettingsAtThisLevel
     )
 
+    # Initialize importantSettingsAtThisLevel if passed
+    if ($null -eq $importantSettingsAtThisLevel) {
+        $importantSettingsAtThisLevel = [ref]@()
+    }
+
     # If the src object contains property 'overwriteSettings' (list of settings), remove these settings from the dst object, so that they can be re-added with the new value later on
     if ($src.PSObject.Properties.Name -contains "overwriteSettings") {
         $src.overwriteSettings | ForEach-Object {
@@ -31,14 +38,22 @@ function MergeCustomObjectIntoOrderedDictionary {
         }
     }
 
+    # Collect important settings from this level
+    # Only set if importantSettings is explicitly defined; otherwise set to $null to signal no update
+    if ($src.PSObject.Properties.Name -contains "importantSettings") {
+        $importantSettingsAtThisLevel.Value = @($src.importantSettings)
+    } else {
+        $importantSettingsAtThisLevel.Value = $null
+    }
+
     # Loop through all properties in the source object
     # If the property does not exist in the destination object, add it with the right type, but no value
     # Types supported: PSCustomObject, Object[] and simple types
     $src.PSObject.Properties.GetEnumerator() | ForEach-Object {
         $prop = $_.Name
 
-        # Skip overwriteSettings property as it's only used to remove settings from the destination object and is specific to the source object
-        if ($prop -eq "overwriteSettings") {
+        # Skip overwriteSettings and importantSettings properties as they're only used for configuration, not actual settings
+        if ($prop -eq "overwriteSettings" -or $prop -eq "importantSettings") {
             return
         }
 
@@ -62,15 +77,22 @@ function MergeCustomObjectIntoOrderedDictionary {
     # If the property exists in the source object, but is of a different type, throw an error
     # If the property exists in the source object:
     # If the property is an Object, call this function recursively to merge values
-    # If the property is an Object[], merge the arrays
+    # If the property is an Object[], merge the arrays (even if important - arrays always merge)
     # If the property is a simple type, replace the value in the destination object with the value from the source object
     @($dst.Keys) | ForEach-Object {
         $prop = $_
+
         if ($src.PSObject.Properties.Name -eq $prop) {
             $dstProp = $dst."$prop"
             $srcProp = $src."$prop"
             $dstPropType = $dstProp.GetType().Name
             $srcPropType = $srcProp.GetType().Name
+
+            # For non-array properties: skip if this setting is marked as important from higher priority source
+            if ($importantSettingsFromHigherPriority -contains $prop -and $srcPropType -ne "Object[]") {
+                OutputDebug "Skipping important setting '$prop' marked from higher priority source (non-array type)"
+                return
+            }
             if ($srcPropType -eq "PSCustomObject" -and $dstPropType -eq "OrderedDictionary") {
                 MergeCustomObjectIntoOrderedDictionary -dst $dst."$prop" -src $srcProp
             }
@@ -262,6 +284,7 @@ function GetDefaultSettings
             "filesToExclude"                            = @()
         }
         "postponeProjectInBuildOrder"                  = $false
+        "importantSettings"                            = @()
     }
 }
 
@@ -482,11 +505,18 @@ function ReadSettings {
         }
     }
 
+    $currentImportantSettings = @()
     foreach($settingsObject in $settingsObjects) {
         $settingsJson = $settingsObject.Settings
         if ($settingsJson) {
             OutputDebug "Applying settings from $($settingsObject.Source) ($($settingsObject.Type))"
-            MergeCustomObjectIntoOrderedDictionary -dst $settings -src $settingsJson
+            $importantAtThisLevel = @()
+            $importantRef = [ref]$importantAtThisLevel
+            MergeCustomObjectIntoOrderedDictionary -dst $settings -src $settingsJson -importantSettingsFromHigherPriority $currentImportantSettings -importantSettingsAtThisLevel $importantRef
+            # Only update currentImportantSettings if this level explicitly defined importantSettings (not null)
+            if ($null -ne $importantAtThisLevel) {
+                $currentImportantSettings = $importantAtThisLevel
+            }
             if ($settingsJson.PSObject.Properties.Name -eq "ConditionalSettings") {
                 foreach($conditionalSetting in $settingsJson.ConditionalSettings) {
                     if ("$conditionalSetting" -ne "") {
@@ -508,7 +538,13 @@ function ReadSettings {
                         }
                         if ($conditionMet) {
                             OutputDebug "Applying conditional settings for $($conditions -join ", ")"
-                            MergeCustomObjectIntoOrderedDictionary -dst $settings -src $conditionalSetting.settings
+                            $importantAtThisLevel = @()
+                            $importantRef = [ref]$importantAtThisLevel
+                            MergeCustomObjectIntoOrderedDictionary -dst $settings -src $conditionalSetting.settings -importantSettingsFromHigherPriority $currentImportantSettings -importantSettingsAtThisLevel $importantRef
+                            # Only update currentImportantSettings if conditional settings explicitly defined importantSettings
+                            if ($null -ne $importantAtThisLevel) {
+                                $currentImportantSettings = $importantAtThisLevel
+                            }
                         }
                     }
                 }

Actions/.Modules/settings.schema.json

@@ -730,6 +730,14 @@
             },
             "description": "An array of settings to be overwritten by the current settings. See https://aka.ms/ALGoSettings#overwriteSettings"
         },
+        "importantSettings": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            },
+            "default": [],
+            "description": "An array of setting names that should take precedence over normal inheritance hierarchy. Settings listed here will override settings from lower priority sources. See https://aka.ms/ALGoSettings#importantSettings"
+        },
         "reportSuppressedDiagnostics": {
             "type": "boolean",
             "description": "Report suppressed diagnostics. See https://aka.ms/ALGoSettings#reportsuppresseddiagnostics"

RELEASENOTES.md

@@ -1,3 +1,37 @@
+### Important settings protection
+
+A new `importantSettings` setting allows you to protect specific settings from being overridden by lower-priority sources in the settings hierarchy. When a setting is marked as important at a higher priority level, it cannot be overridden by non-important settings from lower priority sources.
+
+```json
+{
+  "importantSettings": ["country", "keyVaultName"],
+  "country": "de",
+  "keyVaultName": "orgVault"
+}
+```
+
+**Behavior:**
+- Settings marked as important in organization or repository settings cannot be overridden by project, workflow, user, or environment settings
+- Important settings from higher priority sources always win, even if lower levels mark the same setting as important
+- Important arrays are still merged (not replaced) with lower-priority arrays, unless `overwriteSettings` is explicitly used
+- The `overwriteSettings` mechanism can override important settings when explicitly specified
+- `ConditionalSettings` respect importantSettings markings, allowing you to enforce conditional important settings based on buildMode, branch, trigger, or user
+
+**Example with ConditionalSettings:**
+```json
+{
+  "ConditionalSettings": [
+    {
+      "buildModes": ["Validate"],
+      "settings": {
+        "importantSettings": ["country"],
+        "country": "us"
+      }
+    }
+  ]
+}
+```
+
 ### Resilient Pull Request Status Check for large builds
 
 The Pull Request Status Check action no longer fails on builds with more than one page of jobs (more than 100 jobs). The jobs API call now uses `--slurp` so multi-page responses are parsed as a single JSON array (previously `gh api --paginate | ConvertFrom-Json` failed with "Invalid JSON primitive" when more than one page was returned). The call is also retried, and requests a smaller page size, to tolerate the intermittent HTTP 502 responses that the GitHub jobs endpoint returns for large builds.

Scenarios/settings.md

@@ -316,6 +316,83 @@ then, after merging, the result settings object will contain the following value
 
 > _**Note**_: `overwriteSettings` isn't a setting on its own and it isn't available in the output of `ReadSetting` action, for example. It's merely used to control the settings merging mechanism and allow overwriting complex settings types. The value of `overwriteSettings` should only contain settings of types _array_ or _object_ and all the settings in `overwriteSettings` should be present with the new value.
 
+## Important settings <a id="importantSettings"></a>
+
+By default, AL-Go follows a standard settings hierarchy where settings from higher priority levels (closer to deployment) override settings from lower priority levels. However, you can mark specific settings as **important** to protect them from being overridden by lower priority settings using the `importantSettings` array.
+
+When a setting is marked as important at a higher level in the hierarchy, it cannot be overridden by settings from lower priority levels. This is useful for enforcing organizational or repository-wide policies that should not be changed at the project or workflow level.
+
+_Example_:
+Say, `ALGoOrgSettings` (organization level) contains the following values:
+
+```json
+{
+    "importantSettings": ["country", "keyVaultName"],
+    "country": "de",
+    "keyVaultName": "OrgVault"
+}
+```
+
+and `.AL-Go\settings.json` (project level, lower priority) contains the following values:
+
+```json
+{
+    "country": "us",
+    "keyVaultName": "ProjectVault"
+}
+```
+
+then, after merging, the result settings object will contain the following values:
+
+```json
+{
+    "importantSettings": ["country", "keyVaultName"],
+    "country": "de",
+    "keyVaultName": "OrgVault"
+}
+```
+
+The `country` and `keyVaultName` settings from the organization level are protected and cannot be overridden by the project level settings.
+
+_Example with ConditionalSettings_:
+Say, `ALGoOrgSettings` (organization level) contains conditional settings that set country based on buildMode:
+
+```json
+{
+    "ConditionalSettings": [
+        {
+            "buildModes": ["ValidateUS"],
+            "settings": {
+                "importantSettings": ["country"],
+                "country": "us"
+            }
+        }
+    ]
+}
+```
+
+and `.AL-Go\settings.json` (project level) contains:
+
+```json
+{
+    "country": "w1",
+    "buildModes": ["Default", "ValidateUS"]
+}
+```
+
+When reading settings for buildMode `ValidateUS`, the conditional setting from the organization level will apply. The result will be:
+
+```json
+{
+    "country": "us",
+    "buildModes": ["Default", "ValidateUS"]
+}
+```
+
+Even though the project specifies `country: "w1"`, the conditional setting from the organization level marked the country as important for the `ValidateUS` buildMode, so it takes precedence.
+
+> _**Note**_: `importantSettings` is an array of setting names that should be protected from being overridden by lower priority settings. When a setting is marked as important at a higher level, it will not be overridden by normal (non-important) settings from lower levels. If a setting is marked as important at multiple levels, the value from the highest priority level wins (following normal hierarchy rules). Only top-level setting names can be marked as important; nested properties within complex objects cannot be individually marked as important. Array settings marked as important are still merged with lower-priority arrays, unless `overwriteSettings` is used to force replacement.
+
 <a id="customdelivery"></a>
 
 ## Custom Delivery