DeployTo setting supported as environment variable (#1702)

With this change, it is now possible to define your DeployTo setting as
an environment variable in your GitHub environments.

Author: spetersenms

Actions/.Modules/ReadSettings.psm1

@@ -237,6 +237,7 @@ function GetDefaultSettings
         - .github/<workflowName>.settings.json                 = Workflow settings file
         - <project>/.AL-Go/<workflowName>.settings.json        = Project workflow settings file
         - <project>/.AL-Go/<userName>.settings.json            = User settings file
+        - ALGoEnvSettings (github Variable)                    = Deployment Environment settings variable
     .PARAMETER baseFolder
         The base folder where the settings files are located. Default is $ENV:GITHUB_WORKSPACE when running in GitHub Actions.
     .PARAMETER repoName
@@ -255,6 +256,10 @@ function GetDefaultSettings
         The value of the organization settings variable. Default is $ENV:ALGoOrgSettings.
     .PARAMETER repoSettingsVariableValue
         The value of the repository settings variable. Default is $ENV:ALGoRepoSettings.
+    .PARAMETER environmentSettingsVariableValue
+        The value of the current GitHub environment settings variable, based on workflow context. Default is $ENV:ALGoEnvSettings.
+    .PARAMETER environmentName
+        The value of the environment name, based on the workflow context. Default is $ENV:ALGoEnvName.
     .PARAMETER silent
         If specified, the function will not output any messages to the console.
 #>
@@ -269,6 +274,8 @@ function ReadSettings {
         [string] $branchName = "$ENV:GITHUB_REF_NAME",
         [string] $orgSettingsVariableValue = "$ENV:ALGoOrgSettings",
         [string] $repoSettingsVariableValue = "$ENV:ALGoRepoSettings",
+        [string] $environmentSettingsVariableValue = "$ENV:ALGoEnvSettings",
+        [string] $environmentName = "$ENV:ALGoEnvName",
         [switch] $silent
     )
 
@@ -353,6 +360,24 @@ function ReadSettings {
         }
     }
 
+    if ($environmentSettingsVariableValue) {
+        # Read settings from environment variable (parameter)
+        $environmentVariableObject = $environmentSettingsVariableValue | ConvertFrom-Json
+        # Warn user that 'DeployTo' setting needs to include environment name
+        if ($environmentVariableObject.PSObject.Properties.Name -contains "DeployTo") {
+            OutputWarning "The environment settings variable contains the property 'DeployTo'. Did you intend to use 'DeployTo$environmentName' instead? The 'DeployTo' property without a specific environment name is not supported."
+        }
+        # Warn user if 'runs-on', 'shell' or 'ContinuousDeployment' is defined in the environment settings variable, as these are not supported when defined there.
+        if ($environmentVariableObject.PSObject.Properties.Name -contains "DeployTo$environmentName") {
+            @('runs-on', 'shell', 'ContinuousDeployment') | ForEach-Object {
+                if ($environmentVariableObject."DeployTo$environmentName".PSObject.Properties.Name -contains $_) {
+                    OutputWarning "The property $_ in the DeployTo setting is not supported when defined within a GitHub deployment environment variable. Please define this property elsewhere."
+                }
+            }
+        }
+        $settingsObjects += @($environmentVariableObject)
+    }
+
     foreach($settingsJson in $settingsObjects) {
         if ($settingsJson) {
             MergeCustomObjectIntoOrderedDictionary -dst $settings -src $settingsJson

RELEASENOTES.md

@@ -2,6 +2,28 @@
 
 AL-Go now offers a dataexplorer dashboard to get started with AL-Go telemetry. Additionally, we've updated the documentation to include a couple of kusto queries if you would rather build your own reports.
 
+### Support for AL-Go settings as GitHub environment variable: ALGoEnvSettings
+
+AL-Go settings can now be defined in GitHub environment variables. To use this feature, create a new variable under your GitHub environment called `ALGoEnvironmentSettings`. Please note that this variable should not include your environment name.
+
+Settings loaded this way, will only be available during the Deploy step of the CI/CD or Publish to Environment actions, but not the Build step, making it most suitable for the [DeployTo setting](https://aka.ms/algosettings#deployto). Settings defined in this variable will take priority over any setting defined in AL-Go repo, org or settings files.
+
+The contents of the variable should be a JSON block, similar to any other settings file or variable. When defining the `DeployTo\<EnvName>` setting in this variable, it should still include the environment name. Eg:
+
+```
+{
+  DeployToProduction {
+    "Branches": [
+        "*"
+    ],
+    "includeTestAppsInSandboxEnvironment": false,
+    "excludeAppIds": [ 1234 ]
+  }
+}
+```
+
+Please note, that due to certain security limitations, the properties `runs-on`, `shell` and `ContinousDeployment` of the `DeployTo` setting will <ins>**NOT**</ins> be respected if defined in a GitHub environment variable. To use these properties, please keep them defined elsewhere, such as your AL-Go settings file or Org/Repo settings variables.
+
 ### Issues
 
 - Issue 1770 Wrong type of _projects_ setting in settings schema

Templates/AppSource App/.github/workflows/CICD.yaml

@@ -256,6 +256,9 @@ jobs:
     environment:
       name: ${{ matrix.environment }}
       url: ${{ steps.Deploy.outputs.environmentUrl }}
+    env:
+      ALGoEnvSettings: ${{ vars.ALGoEnvironmentSettings }}
+      ALGoEnvName: ${{ matrix.environment }}
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

Templates/AppSource App/.github/workflows/PublishToEnvironment.yaml

@@ -131,6 +131,8 @@ jobs:
       url: ${{ steps.Deploy.outputs.environmentUrl }}
     env:
       deviceCode: ${{ needs.Initialization.outputs.deviceCode }}
+      ALGoEnvSettings: ${{ vars.ALGoEnvironmentSettings }}
+      ALGoEnvName: ${{ matrix.environment }}
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

Templates/Per Tenant Extension/.github/workflows/CICD.yaml

@@ -270,6 +270,9 @@ jobs:
     environment:
       name: ${{ matrix.environment }}
       url: ${{ steps.Deploy.outputs.environmentUrl }}
+    env:
+      ALGoEnvSettings: ${{ vars.ALGoEnvironmentSettings }}
+      ALGoEnvName: ${{ matrix.environment }}
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

Templates/Per Tenant Extension/.github/workflows/PublishToEnvironment.yaml

@@ -131,6 +131,8 @@ jobs:
       url: ${{ steps.Deploy.outputs.environmentUrl }}
     env:
       deviceCode: ${{ needs.Initialization.outputs.deviceCode }}
+      ALGoEnvSettings: ${{ vars.ALGoEnvironmentSettings }}
+      ALGoEnvName: ${{ matrix.environment }}
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2