diff --git a/Actions/.Modules/settings.schema.json b/Actions/.Modules/settings.schema.json index 27781556c2..5f908cc2c0 100644 --- a/Actions/.Modules/settings.schema.json +++ b/Actions/.Modules/settings.schema.json @@ -919,6 +919,7 @@ "type": "object", "properties": { "filesToInclude": { + "description": "An array of file specifications to include in the update. Files that match these specifications are copied from the template to the repository. When used in a custom template's settings, inclusions are also propagated from the original template to consumer repos even if the files no longer exist in the custom template.", "type": "array", "items": { "type": "object", @@ -935,6 +936,10 @@ "type": "string", "description": "The destination folder where the files should be updated, relative to the repository root. If not specified, defaults to the same as the source file folder." }, + "destinationName": { + "type": "string", + "description": "The filename to use at the destination. If specified, overrides the source filename, allowing the file to be renamed when copied. Should be used together with a filter that matches a single file." + }, "perProject": { "type": "boolean", "description": "Indicates whether the file update should be applied per project. In that case, the destinationFolder is considered relative to each project folder." @@ -943,6 +948,7 @@ } }, "filesToExclude": { + "description": "An array of file specifications to exclude from the update. Files that match these specifications are not copied from the template to the repository. Existing destination files selected for exclusion are removed unless another included source targets the same destination. When a custom template is in use, exclusion rules from the custom template or consumer repository settings are matched against files in both the custom template and the original AL-Go template.", "type": "array", "items": { "type": "object", diff --git a/Actions/CheckForUpdates/CheckForUpdates.HelperFunctions.ps1 b/Actions/CheckForUpdates/CheckForUpdates.HelperFunctions.ps1 index a41774e7d7..4a641864e2 100644 --- a/Actions/CheckForUpdates/CheckForUpdates.HelperFunctions.ps1 +++ b/Actions/CheckForUpdates/CheckForUpdates.HelperFunctions.ps1 @@ -1,1204 +1,1552 @@ -Import-Module (Join-Path $PSScriptRoot '../.Modules/ReadSettings.psm1') -DisableNameChecking -Import-Module (Join-Path $PSScriptRoot '../.Modules/DebugLogHelper.psm1') -DisableNameChecking - -<# -.SYNOPSIS -Downloads a template repository and returns the path to the downloaded folder -.PARAMETER token -The GitHub token / PAT to use for authentication (if the template repository is private/internal) -.PARAMETER templateUrl -The URL to the template repository -.PARAMETER templateSha -The SHA of the template repository (returned by reference if downloadLatest is true) -.PARAMETER downloadLatest -If true, the latest SHA of the template repository will be downloaded -#> -function DownloadTemplateRepository { - Param( - [string] $token, - [string] $templateUrl, - [ref] $templateSha, - [bool] $downloadLatest - ) - - # Construct API URL - if ($templateUrl -like 'https://github.com/*') { - # templateUrl is github.com - use the github.com API URL - $apiUrl = $templateUrl.Split('@')[0] -replace "^($([regex]::Escape('https://github.com') -replace '/', '\/'))/(.*)$", "https://api.github.com/repos/`$2" - } - else { - # templateUrl is not github.com (e.g. github enterprise) - use the GITHUB_SERVER_URL and GITHUB_API_URL environment variables - $apiUrl = $templateUrl.Split('@')[0] -replace "^($([regex]::Escape($env:GITHUB_SERVER_URL) -replace '/', '\/'))/(.*)$", "$ENV:GITHUB_API_URL/repos/`$2" - } - - Write-Host "TemplateUrl: $templateUrl" - Write-Host "ApiUrl: $apiUrl" - Write-Host "TemplateSha: $($templateSha.Value)" - Write-Host "DownloadLatest: $downloadLatest" - - $templateRepositoryUrl = $templateUrl.Split('@')[0] - $templateRepository = $templateRepositoryUrl.Split('/')[-2..-1] -join '/' - - # Use Authenticated API request if possible to avoid the 60 API calls per hour limit - if ($templateUrl -like "$env:GITHUB_SERVER_URL/*") { - # Use authenticated request if the templateUrl is on the same GitHub server as the current repository - Write-Host "Getting template repository ($templateRepository) with GITHUB_TOKEN" - $headers = GetHeaders -token $env:GITHUB_TOKEN -repository $templateRepository - } - else { - # Use unauthenticated request if the templateUrl is on a different GitHub server - Write-Host "Getting template repository ($templateRepository) anonymously" - $headers = GetHeaders -repository $templateRepository - } - try { - # This ONLY fails if the template repository is private/internal and the GITHUB_TOKEN does not have access to it - $response = Invoke-WebRequest -UseBasicParsing -Headers $headers -Method Head -Uri $templateRepositoryUrl - OutputDebug -message ($response | Format-List | Out-String) - } - catch { - # Ignore error - OutputDebug -message "Error getting template repository:" - OutputDebug -message $_ - $response = $null - } - if (-not $response -or $response.StatusCode -ne 200) { - # GITHUB_TOKEN doesn't have access to template repository, must be private/internal - # Get token with read permissions for the template repository - # NOTE that the GitHub app needs to be installed in the template repository for this to work - $headers = GetHeaders -token $token -repository $templateRepository - } - - if ($downloadLatest) { - # Get latest commit SHA from the template repository - $templateSha.Value = GetLatestTemplateSha -headers $headers -apiUrl $apiUrl -templateUrl $templateUrl - Write-Host "Latest SHA for $($templateUrl): $($templateSha.Value)" - } - $archiveUrl = "$apiUrl/zipball/$($templateSha.Value)" - Write-Host "Using ArchiveUrl: $archiveUrl" - - # Download template repository - $tempName = Join-Path (GetTemporaryPath) ([Guid]::NewGuid().ToString()) - InvokeWebRequest -Headers $headers -Uri $archiveUrl -OutFile "$tempName.zip" - Expand-7zipArchive -Path "$tempName.zip" -DestinationPath $tempName - Remove-Item -Path "$tempName.zip" - - return $tempName -} - -function GetLatestTemplateSha { - Param( - [hashtable] $headers, - [string] $apiUrl, - [string] $templateUrl - ) - - $branch = $templateUrl.Split('@')[1] - Write-Host "Get latest SHA for $templateUrl" - try { - $url = "$apiUrl/branches/$branch" - Write-Host "Api URL: $url" - $result = InvokeWebRequest -Headers $headers -Uri $url - $branchInfo = $result.Content | ConvertFrom-Json - } catch { - throw "Failed to update AL-Go System Files. Could not get the latest SHA from template ($templateUrl). (Error was $($_.Exception.Message))" - } - return $branchInfo.commit.sha -} - -function ModifyCICDWorkflow { - Param( - [Yaml] $yaml, - [hashtable] $repoSettings - ) - - # The CICD workflow can have a RepoSetting called CICDPushBranches, which will be used to set the branches for the workflow - # Setting the CICDSchedule will disable the push trigger for the CI/CD workflow (unless CICDPushBranches is set) - if ($repoSettings.Keys -contains 'CICDPushBranches') { - $CICDPushBranches = $repoSettings.CICDPushBranches - } - elseif ($repoSettings.Keys -contains $workflowScheduleKey) { - $CICDPushBranches = '' - } - else { - $CICDPushBranches = $defaultCICDPushBranches - } - # update the branches: line with the new branches - if ($CICDPushBranches) { - $yaml.Replace('on:/push:/branches:', "branches: [ '$($CICDPushBranches -join "', '")' ]") - } - else { - $yaml.Replace('on:/push:',@()) - } -} - -function ModifyPullRequestHandlerWorkflow { - Param( - [Yaml] $yaml, - [hashtable] $repoSettings - ) - # The PullRequestHandler workflow can have a RepoSetting called pullRequestTrigger which specifies the trigger to use for Pull Requests - $triggerSection = $yaml.Get('on:/pull') - $triggerSection.content = "$($repoSettings.pullRequestTrigger):" - $yaml.Replace('on:/pull', $triggerSection.Content) - - # The PullRequestHandler workflow can have a RepoSetting called CICDPullRequestBranches, which will be used to set the branches for the workflow - if ($repoSettings.Keys -contains 'CICDPullRequestBranches') { - $CICDPullRequestBranches = $repoSettings.CICDPullRequestBranches - } - else { - $CICDPullRequestBranches = $defaultCICDPullRequestBranches - } - - # update the branches: line with the new branches - $yaml.Replace("on:/$($repoSettings.pullRequestTrigger):/branches:", "branches: [ '$($CICDPullRequestBranches -join "', '")' ]") - - if ($repoSettings.ContainsKey('skipDraftPullRequests') -and $repoSettings.skipDraftPullRequests) { - $yaml.Add("on:/$($repoSettings.pullRequestTrigger):/", 'types: [ opened, reopened, synchronize, ready_for_review ]') - # Only AL-Go jobs are present here; custom jobs are appended afterwards and remain user-managed. - # Preserve fork validation even when draft build jobs are skipped. - foreach ($job in $yaml.GetNextLevel('jobs:/') | Where-Object { $_ -ne 'PregateCheck:' }) { - $condition = $yaml.GetProperty("jobs:/$job/if:") - $yaml.Replace("jobs:/$job/if:", "if: (github.event_name == 'merge_group' || github.event.pull_request.draft == false) && ($condition)") - } - } -} - -<# -.SYNOPSIS -Adds the pull request trigger and configured target branches to the enabled review intake workflow. -#> -function ModifyCopilotPRReviewWorkflow { - Param( - [Yaml] $yaml, - [hashtable] $repoSettings - ) - - $codeReviewBranches = @('main') - if ( - $repoSettings.Keys -contains 'CodeReviewAgent' -and - $repoSettings.CodeReviewAgent -is [System.Collections.IDictionary] -and - $repoSettings.CodeReviewAgent.Keys -contains 'branches' -and - @($repoSettings.CodeReviewAgent.branches).Count -gt 0 - ) { - $codeReviewBranches = @($repoSettings.CodeReviewAgent.branches) - } - - $branchesJson = ConvertTo-Json -InputObject $codeReviewBranches -Compress - $yaml.ReplaceOrAdd('on:/', 'pull_request:', @( - "branches: $branchesJson" - 'types: [ opened, reopened, synchronize, ready_for_review ]' - )) -} - -function ModifyRunsOnAndShell { - Param( - [Yaml] $yaml, - [hashtable] $repoSettings - ) - - # The default for runs-on is windows-latest and the default for shell is powershell - # The default for GitHubRunner/GitHubRunnerShell is runs-on/shell (unless Ubuntu-latest are selected here, as build jobs cannot run on Ubuntu) - # We do not change runs-on in Update AL-Go System Files and Pull Request Handler workflows - # These workflows will always run on windows-latest (or maybe Ubuntu-latest later) and not follow settings - # Reasons: - # - Update AL-Go System files is needed for changing runs-on - by having non-functioning runners, you might dead-lock yourself - # - Pull Request Handler workflow for security reasons - if ($repoSettings."runs-on" -ne "windows-latest") { - Write-Host "Setting runs-on to [ $($repoSettings."runs-on") ]" - $yaml.ReplaceAll('runs-on: [ windows-latest ]', "runs-on: [ $($repoSettings."runs-on") ]") - } - if ($repoSettings.shell -ne "powershell" -and $repoSettings.shell -ne "pwsh") { - throw "The shell can only be set to powershell or pwsh" - } - if ($repoSettings."runs-on" -eq "ubuntu-latest" -and $repoSettings.shell -eq "powershell") { - throw "The shell cannot be set to powershell when runs-on is ubuntu-latest. Use pwsh instead." - } - Write-Host "Setting shell to $($repoSettings.shell)" - $yaml.ReplaceAll('shell: powershell', "shell: $($repoSettings.shell)") -} - -function ModifyBuildWorkflows { - Param( - [Yaml] $yaml, - [int] $depth, - [bool] $includeBuildPP - ) - - $yaml.Replace('env:/workflowDepth:',"workflowDepth: $depth") - $build = $yaml.Get('jobs:/Build:/') - $buildPP = $yaml.Get('jobs:/BuildPP:/') - $deliver = $yaml.Get('jobs:/Deliver:/') - $deploy = $yaml.Get('jobs:/Deploy:/') - $deployALDoc = $yaml.Get('jobs:/DeployALDoc:/') - $codeAnalysisUpload = $yaml.Get('jobs:/CodeAnalysisUpload:/') - $postProcess = $yaml.Get('jobs:/PostProcess:/') - if (!$build) { - throw "No build job found in the workflow" - } - - # Duplicate the build job for each dependency depth - $newBuild = @() - for($index = 0; $index -lt $depth; $index++) { - # All build job needs to have a dependency on the Initialization job - $needs = @('Initialization') - if ($index -eq 0) { - # First build job needs to have a dependency on the Initialization job only - # Example (depth 1): - # needs: [ Initialization ] - # if: (!failure()) && (!cancelled()) && fromJson(needs.Initialization.outputs.buildOrderJson)[0].projectsCount > 0 - $if = "if: (!failure()) && (!cancelled()) && fromJson(needs.Initialization.outputs.buildOrderJson)[$index].projectsCount > 0" - } - else { - # Subsequent build jobs needs to have a dependency on all previous build jobs - # Example (depth 2): - # needs: [ Initialization, Build1 ] - # if: (!failure()) && (!cancelled()) && (needs.Build1.result == 'success' || needs.Build1.result == 'skipped') && fromJson(needs.Initialization.outputs.buildOrderJson)[0].projectsCount > 0 - # Another example (depth 3): - # needs: [ Initialization, Build2, Build1 ] - # if: (!failure()) && (!cancelled()) && (needs.Build2.result == 'success' || needs.Build2.result == 'skipped') && (needs.Build1.result == 'success' || needs.Build1.result == 'skipped') && fromJson(needs.Initialization.outputs.buildOrderJson)[0].projectsCount > 0 - $newBuild += @('') - $ifpart = "" - $index..1 | ForEach-Object { - $needs += @("Build$_") - $ifpart += " && (needs.Build$_.result == 'success' || needs.Build$_.result == 'skipped')" - } - $if = "if: (!failure()) && (!cancelled())$ifpart && fromJson(needs.Initialization.outputs.buildOrderJson)[$index].projectsCount > 0" - } - - # Replace the if:, the needs: and the strategy/matrix/project: in the build job with the correct values - $build.Replace('if:', $if) - $build.Replace('needs:', "needs: [ $($needs -join ', ') ]") - $build.Replace('strategy:/matrix:/include:',"include: `${{ fromJson(needs.Initialization.outputs.buildOrderJson)[$index].buildDimensions }}") - - # Last build job is called build, all other build jobs are called build1, build2, etc. - if ($depth -eq ($index + 1)) { - $newBuild += @("Build:") - } - else { - $newBuild += @("Build$($index + 1):") - } - - # Add the content of the calculated build job to the new build job list with an indentation of 2 spaces - $build.content | ForEach-Object { $newBuild += @(" $_") } - } - - # Replace the entire build: job with the new build job list - $yaml.Replace('jobs:/Build:', $newBuild) - - if (!$includeBuildPP -and $buildPP) { - # Remove the BuildPP job from the workflow - [int]$start = 0 - [int]$count = 0 - if ($yaml.Find('jobs:/BuildPP:', [ref] $start, [ref] $count)) { - $yaml.Remove($start, $count+1) - } - } - - $needs += @("Build") - $ifpart += " && (needs.Build.result == 'success' || needs.Build.result == 'skipped')" - if ($includeBuildPP -and $buildPP) { - $needs += @("BuildPP") - $ifpart += " && (needs.BuildPP.result == 'success' || needs.BuildPP.result == 'skipped')" - } - - $postProcessNeeds = $needs - # Modify Deliver and Deploy steps depending on build jobs - if ($deploy) { - $deploy.Replace('needs:', "needs: [ $($needs -join ', ') ]") - $deploy.Replace('if:', "if: (!cancelled())$ifpart && needs.Initialization.outputs.environmentCount > 0") - $yaml.Replace('jobs:/Deploy:/', $deploy.content) - $postProcessNeeds += @('Deploy') - } - if ($deliver) { - $deliver.Replace('needs:', "needs: [ $($needs -join ', ') ]") - $deliver.Replace('if:', "if: (!cancelled())$ifpart && needs.Initialization.outputs.deliveryTargetsJson != '[]'") - $yaml.Replace('jobs:/Deliver:/', $deliver.content) - $postProcessNeeds += @('Deliver') - } - if ($deployALDoc) { - $postProcessNeeds += @('DeployALDoc') - } - if ($codeAnalysisUpload) { - $postProcessNeeds += @('CodeAnalysisUpload') - } - if ($postProcess) { - $postProcess.Replace('needs:', "needs: [ $($postProcessNeeds -join ', ') ]") - $yaml.Replace('jobs:/PostProcess:/', $postProcess.content) - } -} - -function ModifyUpdateALGoSystemFiles { - Param( - [Yaml] $yaml, - [hashtable] $repoSettings - ) - - if($repoSettings.Keys -notcontains 'UpdateALGoSystemFilesEnvironment') { - # If UpdateALGoSystemFilesEnvironment is not set, we don't need to do anything - return - } - - $updateALGoSystemFilesEnvironment = $repoSettings.UpdateALGoSystemFilesEnvironment - Write-Host "Setting 'Update AL-Go System Files' environment to $updateALGoSystemFilesEnvironment" - - # Add or replace the environment: section in the UpdateALGoSystemFiles job - $updateALGoSystemFilesJob = $yaml.Get('jobs:/UpdateALGoSystemFiles:/') - - if(-not $updateALGoSystemFilesJob) { - # Defensively check that the UpdateALGoSystemFiles job exists - throw "No UpdateALGoSystemFiles job found in the workflow" - } - - $environmentSection = $updateALGoSystemFilesJob.Get('environment:') - if($environmentSection) { - # If the environment: section already exists, replace it with the new environment - $updateALGoSystemFilesJob.Replace($environmentSection, "environment: $updateALGoSystemFilesEnvironment") - } - else { - # If the environment: section does not exist, add it - $updateALGoSystemFilesJob.Insert(1, "environment: $updateALGoSystemFilesEnvironment") - } - - $yaml.Replace('jobs:/UpdateALGoSystemFiles:/', $updateALGoSystemFilesJob.content) -} - -function ApplyWorkflowDefaultInputs { - Param( - [Yaml] $yaml, - [hashtable] $repoSettings, - [string] $workflowName - ) - - # Check if workflow_dispatch inputs exist - $workflowDispatch = $yaml.Get('on:/workflow_dispatch:/') - if (-not $workflowDispatch) { - # No workflow_dispatch section, nothing to do - return - } - - $inputs = $workflowDispatch.Get('inputs:/') - if (-not $inputs) { - # No inputs section, nothing to do - return - } - - if ($repoSettings.workflowDefaultInputs.Count -eq 0) { - # No defaults for this workflow - return - } - - # Get workflow_call inputs - $workflowCallInputs = $yaml.Get('on:/workflow_call:/inputs:/') - - # Apply defaults to matching inputs - $workflowDispatchInputsModified = $false - $workflowCallInputsModified = $false - - foreach ($defaultInput in $repoSettings.workflowDefaultInputs) { - # Apply to workflow_dispatch inputs and only update workflow_call if dispatch was modified - if (ApplyWorkflowDefaultInput -workflowName $workflowName -inputs $inputs -defaultInput $defaultInput) { - $workflowDispatchInputsModified = $true - - # Only apply to workflow_call inputs if the workflow_dispatch input was modified - if ($workflowCallInputs) { - if (ApplyWorkflowDefaultInput -workflowName $workflowName -inputs $workflowCallInputs -defaultInput $defaultInput) { - $workflowCallInputsModified = $true - } - } - } - } - - # Update the workflow_dispatch section if modified - if ($workflowDispatchInputsModified) { - $workflowDispatch.Replace('inputs:/', $inputs.content) - $yaml.Replace('on:/workflow_dispatch:/', $workflowDispatch.content) - } - - # Update workflow_call inputs if modified - if ($workflowCallInputsModified) { - $yaml.Replace('on:/workflow_call:/inputs:/', $workflowCallInputs.content) - } -} - -function ApplyWorkflowDefaultInput { - Param( - [string] $workflowName, - [Yaml] $inputs, - [hashtable] $defaultInput - ) - - $inputName = $defaultInput.name - $defaultValue = $defaultInput.value - - # Check if this input exists in the inputs collection - $inputSection = $inputs.Get("$($inputName):/") - if (-not $inputSection) { - # Input is not present in the workflow - return $false - } - - # Get the input type from the YAML if specified - $inputType = $null - $typeStart = 0 - $typeCount = 0 - if ($inputSection.Find('type:', [ref] $typeStart, [ref] $typeCount)) { - $typeLine = $inputSection.content[$typeStart].Trim() - if ($typeLine -match 'type:\s*(.+)') { - $inputType = $matches[1].Trim() - } - } - - # Validate that the value type matches the input type - $validationError = $null - if ($inputType) { - switch ($inputType) { - 'boolean' { - if ($defaultValue -isnot [bool]) { - $validationError = "Workflow '$workflowName', input '$inputName': Expected boolean value, but got $($defaultValue.GetType().Name). Please use `$true or `$false." - } - } - 'number' { - if ($defaultValue -isnot [int] -and $defaultValue -isnot [long] -and $defaultValue -isnot [double]) { - $validationError = "Workflow '$workflowName', input '$inputName': Expected number value, but got $($defaultValue.GetType().Name)." - } - } - 'string' { - if ($defaultValue -isnot [string]) { - $validationError = "Workflow '$workflowName', input '$inputName': Expected string value, but got $($defaultValue.GetType().Name)." - } - } - 'choice' { - # Choice inputs accept strings and must match one of the available options (case-sensitive) - if ($defaultValue -isnot [string]) { - $validationError = "Workflow '$workflowName', input '$inputName': Expected string value for choice input, but got $($defaultValue.GetType().Name)." - } - else { - # Validate that the value is one of the available options - $optionsStart = 0 - $optionsCount = 0 - if ($inputSection.Find('options:', [ref] $optionsStart, [ref] $optionsCount)) { - $availableOptions = @() - # Parse the options from the YAML (they are indented list items starting with "- ") - for ($i = $optionsStart + 1; $i -lt ($optionsStart + $optionsCount); $i++) { - $optionLine = $inputSection.content[$i].Trim() - if ($optionLine -match '^-\s*(.+)$') { - $availableOptions += $matches[1].Trim() - } - } - - if ($availableOptions.Count -gt 0 -and $availableOptions -cnotcontains $defaultValue) { - $validationError = "Workflow '$workflowName', input '$inputName': Value '$defaultValue' is not a valid choice (case-sensitive match required). Available options: $($availableOptions -join ', ')." - } - } - } - } - } - } - else { - # If no type is specified in the workflow, it defaults to string - if ($defaultValue -isnot [string]) { - OutputWarning "Workflow '$workflowName', input '$inputName': No type specified in workflow (defaults to string), but configured value is $($defaultValue.GetType().Name). This may cause issues." - } - } - - if ($validationError) { - throw $validationError - } - - # Convert the default value to the appropriate YAML format - $yamlValue = $defaultValue - if ($defaultValue -is [bool]) { - $yamlValue = $defaultValue.ToString().ToLower() - } - elseif ($defaultValue -is [string]) { - # Quote strings and escape single quotes per YAML spec - $escapedValue = $defaultValue.Replace("'", "''") - $yamlValue = "'$escapedValue'" - } - - # Find and replace the default: line in the input section - $start = 0 - $count = 0 - - if ($inputSection.Find('default:', [ref] $start, [ref] $count)) { - # Replace existing default value - $inputSection.Replace('default:', "default: $yamlValue") - } - else { - # Add default value - find the best place to insert it - # Insert after type, required, or description (whichever comes last) - $insertAfter = -1 - $typeLine = 0 - $typeCount = 0 - $requiredLine = 0 - $requiredCount = 0 - $descLine = 0 - $descCount = 0 - - if ($inputSection.Find('type:', [ref] $typeLine, [ref] $typeCount)) { - $insertAfter = $typeLine + $typeCount - } - if ($inputSection.Find('required:', [ref] $requiredLine, [ref] $requiredCount)) { - if (($requiredLine + $requiredCount) -gt $insertAfter) { - $insertAfter = $requiredLine + $requiredCount - } - } - if ($inputSection.Find('description:', [ref] $descLine, [ref] $descCount)) { - if (($descLine + $descCount) -gt $insertAfter) { - $insertAfter = $descLine + $descCount - } - } - - if ($insertAfter -eq -1) { - # No other properties, insert at position 1 (after the input name) - $insertAfter = 1 - } - - $inputSection.Insert($insertAfter, "default: $yamlValue") - } - - # Update the inputs collection with the modified input section - $inputs.Replace("$($inputName):/", $inputSection.content) - - return $true -} - -function GetWorkflowContentWithChangesFromSettings { - Param( - [string] $srcFile, - [hashtable] $repoSettings, - [int] $depth - ) - - $baseName = [System.IO.Path]::GetFileNameWithoutExtension($srcFile) - $yaml = [Yaml]::Load($srcFile) - $yamlName = $yaml.get('name:') - if ($yamlName) { - $workflowName = $yamlName.content.SubString('name:'.Length).Trim().Trim('''"').Trim() - } - else { - $workflowName = $baseName - } - - $workflowScheduleKey = "WorkflowSchedule" - $workflowConcurrencyKey = "WorkflowConcurrency" - foreach($key in @($workflowScheduleKey,$workflowConcurrencyKey)) { - if ($repoSettings.Keys -contains $key -and ($repoSettings."$key")) { - throw "The $key setting is not allowed in the global repository settings. Please use the workflow specific settings file or conditional settings." - } - } - - # Re-read settings and this time include workflow specific settings - $repoSettings = ReadSettings -buildMode '' -project '' -workflowName $workflowName -userName '' -branchName '' | ConvertTo-HashTable -recurse - - # Old Schedule key is deprecated, but still supported - $oldWorkflowScheduleKey = "$($baseName)Schedule" - if ($repoSettings.Keys -contains $oldWorkflowScheduleKey) { - # DEPRECATION: REPLACE WITH ERROR AFTER October 1st 2025 ---> - if ($repoSettings.Keys -contains $workflowScheduleKey) { - OutputWarning "Both $oldWorkflowScheduleKey and $workflowScheduleKey are defined in the settings file. $oldWorkflowScheduleKey will be ignored. This warning will become an error in the future" - } - else { - Trace-DeprecationWarning -Message "$oldWorkflowScheduleKey is deprecated" -DeprecationTag "_workflow_Schedule" -WillBecomeError - # Convert the old Schedule setting to the new WorkflowSchedule setting - $repoSettings."$workflowScheduleKey" = @{ "cron" = $repoSettings."$oldWorkflowScheduleKey" } - } - # <--- REPLACE WITH ERROR AFTER October 1st 2025 - } - - # Any workflow (except for the PullRequestHandler and reusable workflows (_*)) can have concurrency and schedule defined - if ($baseName -ne "PullRequestHandler" -and $baseName -notlike '_*') { - # Add Schedule and Concurrency settings to the workflow - if ($repoSettings.Keys -contains $workflowScheduleKey) { - if ($repoSettings."$workflowScheduleKey" -isnot [hashtable] -or $repoSettings."$workflowScheduleKey".Keys -notcontains 'cron' -or $repoSettings."$workflowScheduleKey".cron -isnot [string]) { - throw "The $workflowScheduleKey setting must be a structure containing a cron property" - } - # Replace or add the schedule part under the on: key - $yaml.ReplaceOrAdd('on:/', 'schedule:', @("- cron: '$($repoSettings."$workflowScheduleKey".cron)'")) - } - if ($repoSettings.Keys -contains $workflowConcurrencyKey) { - # Replace or add the concurrency part - $yaml.ReplaceOrAdd('', 'concurrency:', $repoSettings."$workflowConcurrencyKey") - } - } - - if ($baseName -eq "CICD") { - ModifyCICDWorkflow -yaml $yaml -repoSettings $repoSettings - } - - if ( - $repoSettings.Keys -contains 'CodeReviewAgent' -and - $repoSettings.CodeReviewAgent -is [System.Collections.IDictionary] -and - $repoSettings.CodeReviewAgent.Keys -contains 'enabled' -and - $repoSettings.CodeReviewAgent.enabled - ) { - if ($baseName -eq 'CopilotPRReview') { - ModifyCopilotPRReviewWorkflow -yaml $yaml -repoSettings $repoSettings - } - elseif ($baseName -eq 'CopilotPRReviewRunner') { - $yaml.ReplaceOrAdd('on:/', 'workflow_run:', @( - 'workflows: [ Copilot PR Review ]' - 'types: [ completed ]' - )) - } - } - - $criticalWorkflows = @('UpdateGitHubGoSystemFiles', 'Troubleshooting', 'CopilotPRReviewRunner') - $allowedRunners = @('windows-latest', 'ubuntu-latest') - $modifyRunsOnAndShell = $true - - # Critical workflows may only run on allowed runners (must always be able to run) - if($criticalWorkflows -contains $baseName) { - if($allowedRunners -notcontains $repoSettings."runs-on") { - $modifyRunsOnAndShell = $false - } - } - - if ($modifyRunsOnAndShell) { - ModifyRunsOnAndShell -yaml $yaml -repoSettings $repoSettings - } - - # PullRequestHandler, CICD, Current, NextMinor and NextMajor workflows all include a build step. - # If the dependency depth is higher than 1, we need to add multiple dependent build jobs to the workflow - if ($baseName -eq 'PullRequestHandler' -or $baseName -eq 'CICD' -or $baseName -eq 'Current' -or $baseName -eq 'NextMinor' -or $baseName -eq 'NextMajor') { - $includeBuildPP = $repoSettings.type -eq 'PTE' -and $repoSettings.powerPlatformSolutionFolder -ne '' - ModifyBuildWorkflows -yaml $yaml -depth $depth -includeBuildPP $includeBuildPP - } - - if ($baseName -eq "PullRequestHandler") { - ModifyPullRequestHandlerWorkflow -yaml $yaml -repoSettings $repoSettings - } - - if($baseName -eq 'UpdateGitHubGoSystemFiles') { - ModifyUpdateALGoSystemFiles -yaml $yaml -repoSettings $repoSettings - } - - # Apply workflow input defaults from settings - if ($repoSettings.Keys -contains 'workflowDefaultInputs') { - ApplyWorkflowDefaultInputs -yaml $yaml -repoSettings $repoSettings -workflowName $workflowName - } - - # combine all the yaml file lines into a single string with LF line endings - $yaml.content -join "`n" -} - -# Using direct AL-Go repo, we need to change the owner to the templateOwner, the repo names to AL-Go and AL-Go/Actions and the branch to templateBranch - -function ReplaceOwnerRepoAndBranch { - Param( - [ref] $srcContent, - [string] $templateOwner, - [string] $templateBranch - ) - - $lines = $srcContent.Value.Split("`n") - - # The Original Owner and Repo in the AL-Go repository are microsoft/AL-Go-Actions, microsoft/AL-Go-PTE and microsoft/AL-Go-AppSource - $originalOwnerAndRepo = @{ - "actionsRepo" = "microsoft/AL-Go-Actions" - "perTenantExtensionRepo" = "microsoft/AL-Go-PTE" - "appSourceAppRepo" = "microsoft/AL-Go-AppSource" - } - # Original branch is always main - $originalBranch = "main" - - # Modify the file to use repository names based on whether or not we are using the direct AL-Go repo - $templateRepos = @{ - "actionsRepo" = "AL-Go/Actions" - "perTenantExtensionRepo" = "AL-Go" - "appSourceAppRepo" = "AL-Go" - } - - # Replace URL's to actions repository first - $regex = "^(.*)https:\/\/raw\.githubusercontent\.com\/microsoft\/AL-Go-Actions\/$originalBranch(.*)$" - $replace = "`${1}https://raw.githubusercontent.com/$($templateOwner)/AL-Go/$($templateBranch)/Actions`${2}" - $lines = $lines | ForEach-Object { $_ -replace $regex, $replace } - - # Replace the owner and repo names in the workflow - "actionsRepo","perTenantExtensionRepo","appSourceAppRepo" | ForEach-Object { - $regex = "^(.*)$($originalOwnerAndRepo."$_")(.*)$originalBranch(.*)$" - $replace = "`${1}$($templateOwner)/$($templateRepos."$_")`${2}$($templateBranch)`${3}" - $lines = $lines | ForEach-Object { $_ -replace $regex, $replace } - } - $srcContent.Value = $lines -join "`n" -} - -function IsDirectALGo { - param ( - [string] $templateUrl - ) - $directALGo = $templateUrl -like 'https://github.com/*/AL-Go@*' - if ($directALGo) { - if ($templateUrl -like 'https://github.com/microsoft/AL-Go@*' -and -not ($templateUrl -like 'https://github.com/microsoft/AL-Go@*/*')) { - throw "You cannot use microsoft/AL-Go as a template repository. Please use microsoft/AL-Go-PTE, microsoft/AL-Go-AppSource or a fork of AL-Go instead." - } - } - return $directALGo -} - -function GetSrcFolder { - Param( - [string] $repoType, - [string] $templateUrl, - [string] $templateFolder, - [string] $srcPath = '' - ) - - if (!$templateUrl) { - return '' - } - if (IsDirectALGo -templateUrl $templateUrl) { - switch ($repoType) { - "PTE" { - $typePath = "Per Tenant Extension" - } - "AppSource App" { - $typePath = "AppSource App" - } - default { - throw "Unknown repository type" - } - } - $path = Join-Path $templateFolder "*/Templates/$typePath/.github/workflows" - } - else { - $path = Join-Path $templateFolder "*/.github/workflows" - } - # Due to this PowerShell bug: https://github.com/PowerShell/PowerShell/issues/6473#issuecomment-375930843 - # We need to resolve the path of a non-hidden folder (.github/workflows) - # and then get the parent folder of the parent folder of that path - $path = Resolve-Path -Path $path -ErrorAction SilentlyContinue - if (!$path) { - throw "No workflows found in the template repository" - } - $path = Join-Path -Path (Split-Path -Path (Split-Path -Path $path -Parent) -Parent) -ChildPath $srcPath - return $path -} - -function GetModifiedSettingsContent { - Param( - [string] $srcSettingsFile, - [string] $dstSettingsFile - ) - - $srcSettings = Get-ContentLF -Path $srcSettingsFile | ConvertFrom-Json - - $dstSettings = $null - if(Test-Path -Path $dstSettingsFile -PathType Leaf) { - $dstSettings = Get-ContentLF -Path $dstSettingsFile | ConvertFrom-Json - } - - if(!$dstSettings) { - # If the destination settings file does not exist or it's empty, create an new settings object with default values from the source settings (which includes the $schema property already) - $dstSettings = $srcSettings - } - else { - # Change the $schema property to be the same as the source settings file (add it if it doesn't exist) - $schemaKey = '$schema' - if ($srcSettings.PSObject.Properties.Name -eq $schemaKey) { - $schemaValue = $srcSettings."$schemaKey" - - $dstSettings | Add-Member -MemberType NoteProperty -Name "$schemaKey" -Value $schemaValue -Force - - # Make sure the $schema property is the first property in the object - # PS5-safe: explicitly list properties instead of using wildcard to avoid literal '*' being added - $otherProperties = @($dstSettings.PSObject.Properties.Name | Where-Object { $_ -ne $schemaKey }) - $selectProperties = @($schemaKey) + $otherProperties - $dstSettings = $dstSettings | Select-Object -Property $selectProperties - } - } - - return $dstSettings | ConvertTo-JsonLF -} - -<# -.SYNOPSIS -Determines whether a system-files update has changes beyond advancing an existing template SHA. -.PARAMETER settingsFile -The repository settings file containing the last applied template URL and SHA. -.PARAMETER templateUrl -The template URL selected for this update. -.PARAMETER updateFiles -The files to add or update. -.PARAMETER removeFiles -The files to remove. -#> -function Test-HasSystemFileChanges { - Param( - [string] $settingsFile, - [string] $templateUrl, - [array] $updateFiles, - [array] $removeFiles - ) - - if (-not $updateFiles -and -not $removeFiles -and (Test-Path -Path $settingsFile -PathType Leaf)) { - $currentSettings = Get-Content $settingsFile -Encoding UTF8 | ConvertFrom-Json | ConvertTo-HashTable -recurse - if ($currentSettings['templateUrl'] -ceq $templateUrl -and $currentSettings['templateSha']) { - return $false - } - } - return $true -} - -function UpdateSettingsFile { - Param( - [string] $settingsFile, - [hashtable] $updateSettings - ) - - $modified = $false - # Update Repo Settings file with the template URL - if (Test-Path $settingsFile) { - $settings = Get-Content $settingsFile -Encoding UTF8 | ConvertFrom-Json - } - else { - $settings = [PSCustomObject]@{} - $modified = $true - } - foreach($key in $updateSettings.Keys) { - if ($settings.PSObject.Properties.Name -eq $key) { - if ($settings."$key" -ne $updateSettings."$key") { - $settings."$key" = $updateSettings."$key" - $modified = $true - } - } - else { - # Add the property if it doesn't exist - $settings | Add-Member -MemberType NoteProperty -Name "$key" -Value $updateSettings."$key" - $modified = $true - } - } - if ($modified) { - # Save the file with LF line endings and UTF8 encoding - $settings | Set-JsonContentLF -path $settingsFile - } - return $modified -} - -<# -.SYNOPSIS -Resolves file paths based on the provided source folder, destination folder, and file specifications. - -.DESCRIPTION -This function takes a source folder, an optional original source folder, a destination folder, and an array of file specifications. It resolves the full paths for each specified file, considering their origin (template or custom template), type, and whether they are per-project files. -The function returns an array of hashtables containing the resolved source and destination file paths. -The function is used to determine which files need to be copied from the template repository to the target repository during the AL-Go update process. -sourceFolder: The base folder of the template used to resolve the source file paths. -originalSourceFolder: The base folder of the original template used to check for original files (can be $null). This is in the case of custom templates, where if the file exists in the original template, it should be used instead of the custom template file. -destinationFolder: The base folder used to construct the destination file paths. This is typically the root folder of the target repository. - -.PARAMETER sourceFolder -The base folder where the source files are located. - -.PARAMETER originalSourceFolder -The original source folder to check for original files (can be $null). All files of origin 'custom template' are skipped if this parameter is $null. - -.PARAMETER destinationFolder -The base folder used to construct the destination file paths. - -.PARAMETER files -An array of hashtables specifying the files to resolve. Each hashtable can contain the following keys: -- sourceFolder: The subfolder within the source folder to search for files (default is current folder). -- filter: The file filter to apply when searching for files (default is all files). -- origin: The origin of the files, either 'template' or 'custom template' (default is 'template'). -- type: The type of the files (default is empty). -- destinationFolder: The subfolder within the destination folder where the files should be placed (default is the same as sourceFolder). -- perProject: A boolean indicating whether the files are per project (default is false). - -.PARAMETER projects -An array of project names used when resolving per-project file paths. - -.OUTPUTS -An array of hashtables, each containing: -- sourceFullPath: The full path to the source file. -- originalSourceFullPath: The full path to the original source file (if found, otherwise $null). -- type: The type of the file. -- destinationFullPath: The full path to the destination file. -#> -function ResolveFilePaths { - Param( - [Parameter(Mandatory=$true)] - [string] $sourceFolder, - [string] $originalSourceFolder = $null, - [Parameter(Mandatory=$true)] - [string] $destinationFolder, - [array] $files = @(), - [string[]] $projects = @() - ) - - if(-not $files) { - return @() - } - - $fullFilePaths = @() - foreach($file in $files) { - if($file.Keys -notcontains 'sourceFolder') { - $file.sourceFolder = '' # Default to current folder - } - - if($file.Keys -notcontains 'filter') { - $file.filter = '' # Default to all files - } - - if($file.Keys -notcontains 'origin') { - $file.origin = 'template' # Default to template - } - - if($file.Keys -notcontains 'type') { - $file.type = '' # Default to empty - } - - if($file.Keys -notcontains 'destinationFolder') { - # If destinationFolder is not specified, use the sourceFolder, so that the file structure is preserved - $file.destinationFolder = $file.sourceFolder - } - - if($file.Keys -notcontains 'perProject') { - $file.perProject = $false # Default to false - } - - # If originalSourceFolder is not specified, it means there is no custom template, so skip custom template files - if(!$originalSourceFolder -and $file.origin -eq 'custom template') { - OutputDebug "Skipping custom template file(s) with source folder '$($file.sourceFolder)' as there is no original source folder specified" - continue; - } - - # All files are relative to the template folder - OutputDebug "Resolving files for source folder '$($file.sourceFolder)' and filter '$($file.filter)'" - $sourceFiles = @(Get-ChildItem -Path (Join-Path $sourceFolder $file.sourceFolder) -Filter $file.filter -File -ErrorAction SilentlyContinue | Select-Object -ExpandProperty FullName) - - OutputDebug "Found $($sourceFiles.Count) files for filter '$($file.filter)' in folder '$($file.sourceFolder)' (relative to folder '$sourceFolder', origin '$($file.origin)')" - - if(-not $sourceFiles) { - OutputDebug "No files found for filter '$($file.filter)' in folder '$($file.sourceFolder)' (relative to folder '$sourceFolder')" - continue - } - - foreach($srcFile in $sourceFiles) { - $fullFilePath = @{ - 'sourceFullPath' = $srcFile - 'originalSourceFullPath' = $null - 'type' = $file.type - 'destinationFullPath' = $null - } - - # Check if the source file is under the source folder - if ($srcFile -notlike "$sourceFolder*") { - OutputDebug "Skipping source file '$($srcFile)' as it is not under the source folder '$($sourceFolder)'." - continue - } - - OutputDebug "Processing file '$($srcFile)'" - - # Try to find the same files in the original template folder if it is specified. Exclude custom template files - if ($originalSourceFolder -and ($file.origin -ne 'custom template')) { - Push-Location $sourceFolder - $relativePath = Resolve-Path -Path $srcFile -Relative # resolve the path relative to the current location (template folder) - Pop-Location - if (Test-Path (Join-Path $originalSourceFolder $relativePath) -PathType Leaf) { - # If the file exists in the original template folder, use that file instead - $fullFilePath.originalSourceFullPath = Join-Path $originalSourceFolder $relativePath -Resolve - } - } - - $destinationName = Split-Path -Path $srcFile -Leaf - if($file.Keys -contains 'destinationName' -and ($file.destinationName)) { - $destinationName = $file.destinationName - } - - if($file.Keys -contains 'perProject' -and $file.perProject -eq $true) { - # Multiple file entries, one for each project - # Destination full path is the destination base folder + project + destinationFolder + destinationName - - foreach($project in $projects) { - if($project -eq '.') { - $project = '' # If project is '.', it means the root folder, so we use an empty string - } - - $fullProjectFilePath = $fullFilePath.Clone() - - $fullProjectFilePath.destinationFullPath = Join-Path $destinationFolder $project - $fullProjectFilePath.destinationFullPath = Join-Path $fullProjectFilePath.destinationFullPath $file.destinationFolder - $fullProjectFilePath.destinationFullPath = Join-Path $fullProjectFilePath.destinationFullPath $destinationName - - if($fullFilePaths -and $fullFilePaths.destinationFullPath -contains $fullProjectFilePath.destinationFullPath) { - OutputDebug "Skipping duplicate per-project file for project '$project': destinationFullPath '$($fullProjectFilePath.destinationFullPath)' already exists" - continue - } - OutputDebug "Adding per-project file for project '$project': sourceFullPath '$($fullProjectFilePath.sourceFullPath)', originalSourceFullPath '$($fullProjectFilePath.originalSourceFullPath)', destinationFullPath '$($fullProjectFilePath.destinationFullPath)'" - $fullFilePaths += $fullProjectFilePath - } - } - else { - # Single file entry - # Destination full path is the destination base folder + destinationFolder + destinationName - - $fullFilePath.destinationFullPath = Join-Path $destinationFolder $file.destinationFolder - $fullFilePath.destinationFullPath = Join-Path $fullFilePath.destinationFullPath $destinationName - - if($fullFilePaths -and $fullFilePaths.destinationFullPath -contains $fullFilePath.destinationFullPath) { - OutputDebug "Skipping duplicate file: destinationFullPath '$($fullFilePath.destinationFullPath)' already exists" - continue - } - OutputDebug "Adding file: sourceFullPath '$($fullFilePath.sourceFullPath)', originalSourceFullPath '$($fullFilePath.originalSourceFullPath)', destinationFullPath '$($fullFilePath.destinationFullPath)'" - $fullFilePaths += $fullFilePath - } - } - } - - return @($fullFilePaths) -} - -function GetDefaultFilesToInclude { - Param( - [switch] $includeCustomTemplateFiles - ) - - $filesToInclude = @( - [ordered]@{ 'sourceFolder' = '.github/workflows'; 'filter' = '*.yaml'; 'type' = 'workflow' } - [ordered]@{ 'sourceFolder' = '.github/workflows'; 'filter' = '*.yml'; 'type' = 'workflow' } - [ordered]@{ 'sourceFolder' = '.github'; 'filter' = '*.copy.md' } - [ordered]@{ 'sourceFolder' = '.github'; 'filter' = '*.ps1' } - [ordered]@{ 'sourceFolder' = '.github'; 'filter' = "$RepoSettingsFileName"; 'type' = 'settings' } - [ordered]@{ 'sourceFolder' = '.github'; 'filter' = '*.settings.json'; 'type' = 'settings' } - [ordered]@{ 'sourceFolder' = '.github/.agents'; 'filter' = '*.agent.md' } - - [ordered]@{ 'sourceFolder' = '.AL-Go'; 'filter' = '*.ps1'; 'perProject' = $true }, - [ordered]@{ 'sourceFolder' = '.AL-Go'; 'filter' = "$ALGoSettingsFileName"; 'perProject' = $true; 'type' = 'settings' } - ) - - if($includeCustomTemplateFiles) { - # If there is an original template folder, we also need to include custom template files (RepoSettings and ProjectSettings) - $filesToInclude += @( - [ordered]@{ 'sourceFolder' = ".github"; 'filter' = "$RepoSettingsFileName"; 'destinationName' = "$CustomTemplateRepoSettingsFileName"; 'origin' = 'custom template' } - [ordered]@{ 'sourceFolder' = ".AL-Go"; 'filter' = "$ALGoSettingsFileName"; 'destinationFolder' = '.github'; 'destinationName' = "$CustomTemplateProjectSettingsFileName"; 'origin' = 'custom template' } - ) - } - - return $filesToInclude -} - -function GetDefaultFilesToExclude { - Param( - $settings - ) - $filesToExclude = @() - - $includeBuildPP = $settings.type -eq 'PTE' -and $settings.powerPlatformSolutionFolder -ne '' - if (!$includeBuildPP) { - # Remove PowerPlatform workflows if no PowerPlatformSolution exists - $filesToExclude += @( - [ordered]@{ 'sourceFolder' = '.github/workflows'; 'filter' = '_BuildPowerPlatformSolution.yaml' } - [ordered]@{ 'sourceFolder' = '.github/workflows'; 'filter' = 'PushPowerPlatformChanges.yaml' } - [ordered]@{ 'sourceFolder' = '.github/workflows'; 'filter' = 'PullPowerPlatformChanges.yaml' } - ) - } - - if ($settings.Keys -notcontains 'CodeReviewAgent' -or !$settings['CodeReviewAgent']['enabled']) { - $filesToExclude += @( - [ordered]@{ 'sourceFolder' = '.github/workflows'; 'filter' = 'CopilotPRReview.yaml' } - [ordered]@{ 'sourceFolder' = '.github/workflows'; 'filter' = 'CopilotPRReviewRunner.yaml' } - ) - } - - return @($filesToExclude) -} - -<# -.SYNOPSIS - Get the list of files from the template repository to include and exclude based on the provided settings. -.DESCRIPTION - This function gets the list of files to include and exclude based on the provided settings. - The unusedALGoSystemFiles setting is also applied to exclude files from the include list and add them to the exclude list. -.PARAMETER settings - The settings object containing the customALGoFiles configuration. -.PARAMETER baseFolder - The base folder of the repository. This is the target folder where the files will be updated. -.PARAMETER templateFolder - The folder where the template files are located. -.PARAMETER originalTemplateFolder - The folder where the original template files are located (if any). - If originalTemplateFolder is provided, it means that there is a custom template in use and custom template files should be included. -.PARAMETER projects - The list of projects in the repository. - The projects are used to resolve per-project files. -.OUTPUTS - An array containing two elements: the list of files to include and the list of files to exclude. - Files are represented as hashtables with the following keys: - - sourceFullPath: The full path to the source file in the template repository. - - originalSourceFullPath: The full path to the original source file in the original template repository (if any). - - type: The type of the file (e.g., workflow, settings). - - destinationFullPath: The full path to the destination file in the target repository. -#> -function GetFilesToUpdate { - Param( - [Parameter(Mandatory=$true)] - $settings, - [Parameter(Mandatory=$true)] - $baseFolder, - [Parameter(Mandatory=$true)] - $templateFolder, - $originalTemplateFolder = $null, - $projects = @() - ) - - Write-Host "Getting files to update from template folder '$templateFolder', original template folder '$originalTemplateFolder' and base folder '$baseFolder'" - - # Send telemetery about customALGoFiles usage - if ($settings.customALGoFiles.filesToInclude.Count -gt 0) { - Trace-Information -Message "Usage: Custom AL-Go Files (Include)" - } - if ($settings.customALGoFiles.filesToExclude.Count -gt 0) { - Trace-Information -Message "Usage: Custom AL-Go Files (Exclude)" - } - - $filesToInclude = GetDefaultFilesToInclude -includeCustomTemplateFiles:$($null -ne $originalTemplateFolder) - $filesToInclude += $settings.customALGoFiles.filesToInclude - $filesToInclude = @(ResolveFilePaths -sourceFolder $templateFolder -originalSourceFolder $originalTemplateFolder -destinationFolder $baseFolder -files $filesToInclude -projects $projects) - - $filesToExclude = GetDefaultFilesToExclude -settings $settings - $filesToExclude += $settings.customALGoFiles.filesToExclude - $filesToExclude = @(ResolveFilePaths -sourceFolder $templateFolder -originalSourceFolder $originalTemplateFolder -destinationFolder $baseFolder -files $filesToExclude -projects $projects) - - # Exclude files from filesToExclude that are not in filesToInclude - $filesToExclude = @($filesToExclude | Where-Object { - $fileToExclude = $_ - $include = $filesToInclude | Where-Object { $_.sourceFullPath -eq $fileToExclude.sourceFullPath } - if(-not $include) { - OutputDebug "Excluding file $($fileToExclude.sourceFullPath) from exclude list as it is not in the include list" - } - return $include - }) - - # Exclude files from filesToInclude that are in filesToExclude - $filesToInclude = @($filesToInclude | Where-Object { - $fileToInclude = $_ - $include = -not ($filesToExclude | Where-Object { $_.sourceFullPath -eq $fileToInclude.sourceFullPath }) - if(-not $include) { - OutputDebug "Excluding file $($fileToInclude.sourceFullPath) from include as it is in the exclude list" - } - return $include - }) - - # Apply unusedALGoSystemFiles logic - $unusedALGoSystemFiles = $settings.unusedALGoSystemFiles - - # Exclude unusedALGoSystemFiles from $filesToInclude and add them to $filesToExclude - $unusedFilesToExclude = $filesToInclude | Where-Object { $unusedALGoSystemFiles -contains (Split-Path -Path $_.sourceFullPath -Leaf) } - if ($unusedFilesToExclude) { - Trace-DeprecationWarning "The 'unusedALGoSystemFiles' setting is deprecated and will be removed in future versions." -DeprecationTag "unusedALGoSystemFiles" - - OutputDebug "The following files are marked as unused and will be removed if they exist:" - $unusedFilesToExclude | ForEach-Object { OutputDebug "- $($_.destinationFullPath)" } - - $filesToInclude = @($filesToInclude | Where-Object { $unusedALGoSystemFiles -notcontains (Split-Path -Path $_.sourceFullPath -Leaf) }) - $filesToExclude += @($unusedFilesToExclude) - } - - # List all files to be included and excluded with their source and destination paths, type and original source path (if any) - $fileFormatter = { param($file) " -Source: $($file.sourceFullPath), Destination: $($file.destinationFullPath), Type: $($file.type), Original Source: $($file.originalSourceFullPath)"} - OutputArray -Message "Files to include: $($filesToInclude.Count)" -Array $filesToInclude -Formatter $fileFormatter - OutputArray -Message "Files to exclude: $($filesToExclude.Count)" -Array $filesToExclude -Formatter $fileFormatter - - return @($filesToInclude), @($filesToExclude) -} +Import-Module (Join-Path $PSScriptRoot '../.Modules/ReadSettings.psm1') -DisableNameChecking +Import-Module (Join-Path $PSScriptRoot '../.Modules/DebugLogHelper.psm1') -DisableNameChecking + +<# +.SYNOPSIS +Downloads a template repository and returns the path to the downloaded folder +.PARAMETER token +The GitHub token / PAT to use for authentication (if the template repository is private/internal) +.PARAMETER templateUrl +The URL to the template repository +.PARAMETER templateSha +The SHA of the template repository (returned by reference if downloadLatest is true) +.PARAMETER downloadLatest +If true, the latest SHA of the template repository will be downloaded +#> +function DownloadTemplateRepository { + Param( + [string] $token, + [string] $templateUrl, + [ref] $templateSha, + [bool] $downloadLatest + ) + + # Construct API URL + if ($templateUrl -like 'https://github.com/*') { + # templateUrl is github.com - use the github.com API URL + $apiUrl = $templateUrl.Split('@')[0] -replace "^($([regex]::Escape('https://github.com') -replace '/', '\/'))/(.*)$", "https://api.github.com/repos/`$2" + } + else { + # templateUrl is not github.com (e.g. github enterprise) - use the GITHUB_SERVER_URL and GITHUB_API_URL environment variables + $apiUrl = $templateUrl.Split('@')[0] -replace "^($([regex]::Escape($env:GITHUB_SERVER_URL) -replace '/', '\/'))/(.*)$", "$ENV:GITHUB_API_URL/repos/`$2" + } + + Write-Host "TemplateUrl: $templateUrl" + Write-Host "ApiUrl: $apiUrl" + Write-Host "TemplateSha: $($templateSha.Value)" + Write-Host "DownloadLatest: $downloadLatest" + + $templateRepositoryUrl = $templateUrl.Split('@')[0] + $templateRepository = $templateRepositoryUrl.Split('/')[-2..-1] -join '/' + + # Use Authenticated API request if possible to avoid the 60 API calls per hour limit + if ($templateUrl -like "$env:GITHUB_SERVER_URL/*") { + # Use authenticated request if the templateUrl is on the same GitHub server as the current repository + Write-Host "Getting template repository ($templateRepository) with GITHUB_TOKEN" + $headers = GetHeaders -token $env:GITHUB_TOKEN -repository $templateRepository + } + else { + # Use unauthenticated request if the templateUrl is on a different GitHub server + Write-Host "Getting template repository ($templateRepository) anonymously" + $headers = GetHeaders -repository $templateRepository + } + try { + # This ONLY fails if the template repository is private/internal and the GITHUB_TOKEN does not have access to it + $response = Invoke-WebRequest -UseBasicParsing -Headers $headers -Method Head -Uri $templateRepositoryUrl + OutputDebug -message ($response | Format-List | Out-String) + } + catch { + # Ignore error + OutputDebug -message "Error getting template repository:" + OutputDebug -message $_ + $response = $null + } + if (-not $response -or $response.StatusCode -ne 200) { + # GITHUB_TOKEN doesn't have access to template repository, must be private/internal + # Get token with read permissions for the template repository + # NOTE that the GitHub app needs to be installed in the template repository for this to work + $headers = GetHeaders -token $token -repository $templateRepository + } + + if ($downloadLatest) { + # Get latest commit SHA from the template repository + $templateSha.Value = GetLatestTemplateSha -headers $headers -apiUrl $apiUrl -templateUrl $templateUrl + Write-Host "Latest SHA for $($templateUrl): $($templateSha.Value)" + } + $archiveUrl = "$apiUrl/zipball/$($templateSha.Value)" + Write-Host "Using ArchiveUrl: $archiveUrl" + + # Download template repository + $tempName = Join-Path (GetTemporaryPath) ([Guid]::NewGuid().ToString()) + InvokeWebRequest -Headers $headers -Uri $archiveUrl -OutFile "$tempName.zip" + Expand-7zipArchive -Path "$tempName.zip" -DestinationPath $tempName + Remove-Item -Path "$tempName.zip" + + return $tempName +} + +function GetLatestTemplateSha { + Param( + [hashtable] $headers, + [string] $apiUrl, + [string] $templateUrl + ) + + $branch = $templateUrl.Split('@')[1] + Write-Host "Get latest SHA for $templateUrl" + try { + $url = "$apiUrl/branches/$branch" + Write-Host "Api URL: $url" + $result = InvokeWebRequest -Headers $headers -Uri $url + $branchInfo = $result.Content | ConvertFrom-Json + } catch { + throw "Failed to update AL-Go System Files. Could not get the latest SHA from template ($templateUrl). (Error was $($_.Exception.Message))" + } + return $branchInfo.commit.sha +} + +function ModifyCICDWorkflow { + Param( + [Yaml] $yaml, + [hashtable] $repoSettings + ) + + # The CICD workflow can have a RepoSetting called CICDPushBranches, which will be used to set the branches for the workflow + # Setting the CICDSchedule will disable the push trigger for the CI/CD workflow (unless CICDPushBranches is set) + if ($repoSettings.Keys -contains 'CICDPushBranches') { + $CICDPushBranches = $repoSettings.CICDPushBranches + } + elseif ($repoSettings.Keys -contains $workflowScheduleKey) { + $CICDPushBranches = '' + } + else { + $CICDPushBranches = $defaultCICDPushBranches + } + # update the branches: line with the new branches + if ($CICDPushBranches) { + $yaml.Replace('on:/push:/branches:', "branches: [ '$($CICDPushBranches -join "', '")' ]") + } + else { + $yaml.Replace('on:/push:',@()) + } +} + +function ModifyPullRequestHandlerWorkflow { + Param( + [Yaml] $yaml, + [hashtable] $repoSettings + ) + # The PullRequestHandler workflow can have a RepoSetting called pullRequestTrigger which specifies the trigger to use for Pull Requests + $triggerSection = $yaml.Get('on:/pull') + $triggerSection.content = "$($repoSettings.pullRequestTrigger):" + $yaml.Replace('on:/pull', $triggerSection.Content) + + # The PullRequestHandler workflow can have a RepoSetting called CICDPullRequestBranches, which will be used to set the branches for the workflow + if ($repoSettings.Keys -contains 'CICDPullRequestBranches') { + $CICDPullRequestBranches = $repoSettings.CICDPullRequestBranches + } + else { + $CICDPullRequestBranches = $defaultCICDPullRequestBranches + } + + # update the branches: line with the new branches + $yaml.Replace("on:/$($repoSettings.pullRequestTrigger):/branches:", "branches: [ '$($CICDPullRequestBranches -join "', '")' ]") + + if ($repoSettings.ContainsKey('skipDraftPullRequests') -and $repoSettings.skipDraftPullRequests) { + $yaml.Add("on:/$($repoSettings.pullRequestTrigger):/", 'types: [ opened, reopened, synchronize, ready_for_review ]') + # Only AL-Go jobs are present here; custom jobs are appended afterwards and remain user-managed. + # Preserve fork validation even when draft build jobs are skipped. + foreach ($job in $yaml.GetNextLevel('jobs:/') | Where-Object { $_ -ne 'PregateCheck:' }) { + $condition = $yaml.GetProperty("jobs:/$job/if:") + $yaml.Replace("jobs:/$job/if:", "if: (github.event_name == 'merge_group' || github.event.pull_request.draft == false) && ($condition)") + } + } +} + +<# +.SYNOPSIS +Adds the pull request trigger and configured target branches to the enabled review intake workflow. +#> +function ModifyCopilotPRReviewWorkflow { + Param( + [Yaml] $yaml, + [hashtable] $repoSettings + ) + + $codeReviewBranches = @('main') + if ( + $repoSettings.Keys -contains 'CodeReviewAgent' -and + $repoSettings.CodeReviewAgent -is [System.Collections.IDictionary] -and + $repoSettings.CodeReviewAgent.Keys -contains 'branches' -and + @($repoSettings.CodeReviewAgent.branches).Count -gt 0 + ) { + $codeReviewBranches = @($repoSettings.CodeReviewAgent.branches) + } + + $branchesJson = ConvertTo-Json -InputObject $codeReviewBranches -Compress + $yaml.ReplaceOrAdd('on:/', 'pull_request:', @( + "branches: $branchesJson" + 'types: [ opened, reopened, synchronize, ready_for_review ]' + )) +} + +function ModifyRunsOnAndShell { + Param( + [Yaml] $yaml, + [hashtable] $repoSettings + ) + + # The default for runs-on is windows-latest and the default for shell is powershell + # The default for GitHubRunner/GitHubRunnerShell is runs-on/shell (unless Ubuntu-latest are selected here, as build jobs cannot run on Ubuntu) + # We do not change runs-on in Update AL-Go System Files and Pull Request Handler workflows + # These workflows will always run on windows-latest (or maybe Ubuntu-latest later) and not follow settings + # Reasons: + # - Update AL-Go System files is needed for changing runs-on - by having non-functioning runners, you might dead-lock yourself + # - Pull Request Handler workflow for security reasons + if ($repoSettings."runs-on" -ne "windows-latest") { + Write-Host "Setting runs-on to [ $($repoSettings."runs-on") ]" + $yaml.ReplaceAll('runs-on: [ windows-latest ]', "runs-on: [ $($repoSettings."runs-on") ]") + } + if ($repoSettings.shell -ne "powershell" -and $repoSettings.shell -ne "pwsh") { + throw "The shell can only be set to powershell or pwsh" + } + if ($repoSettings."runs-on" -eq "ubuntu-latest" -and $repoSettings.shell -eq "powershell") { + throw "The shell cannot be set to powershell when runs-on is ubuntu-latest. Use pwsh instead." + } + Write-Host "Setting shell to $($repoSettings.shell)" + $yaml.ReplaceAll('shell: powershell', "shell: $($repoSettings.shell)") +} + +function ModifyBuildWorkflows { + Param( + [Yaml] $yaml, + [int] $depth, + [bool] $includeBuildPP + ) + + $yaml.Replace('env:/workflowDepth:',"workflowDepth: $depth") + $build = $yaml.Get('jobs:/Build:/') + $buildPP = $yaml.Get('jobs:/BuildPP:/') + $deliver = $yaml.Get('jobs:/Deliver:/') + $deploy = $yaml.Get('jobs:/Deploy:/') + $deployALDoc = $yaml.Get('jobs:/DeployALDoc:/') + $codeAnalysisUpload = $yaml.Get('jobs:/CodeAnalysisUpload:/') + $postProcess = $yaml.Get('jobs:/PostProcess:/') + if (!$build) { + throw "No build job found in the workflow" + } + + # Duplicate the build job for each dependency depth + $newBuild = @() + for($index = 0; $index -lt $depth; $index++) { + # All build job needs to have a dependency on the Initialization job + $needs = @('Initialization') + if ($index -eq 0) { + # First build job needs to have a dependency on the Initialization job only + # Example (depth 1): + # needs: [ Initialization ] + # if: (!failure()) && (!cancelled()) && fromJson(needs.Initialization.outputs.buildOrderJson)[0].projectsCount > 0 + $if = "if: (!failure()) && (!cancelled()) && fromJson(needs.Initialization.outputs.buildOrderJson)[$index].projectsCount > 0" + } + else { + # Subsequent build jobs needs to have a dependency on all previous build jobs + # Example (depth 2): + # needs: [ Initialization, Build1 ] + # if: (!failure()) && (!cancelled()) && (needs.Build1.result == 'success' || needs.Build1.result == 'skipped') && fromJson(needs.Initialization.outputs.buildOrderJson)[0].projectsCount > 0 + # Another example (depth 3): + # needs: [ Initialization, Build2, Build1 ] + # if: (!failure()) && (!cancelled()) && (needs.Build2.result == 'success' || needs.Build2.result == 'skipped') && (needs.Build1.result == 'success' || needs.Build1.result == 'skipped') && fromJson(needs.Initialization.outputs.buildOrderJson)[0].projectsCount > 0 + $newBuild += @('') + $ifpart = "" + $index..1 | ForEach-Object { + $needs += @("Build$_") + $ifpart += " && (needs.Build$_.result == 'success' || needs.Build$_.result == 'skipped')" + } + $if = "if: (!failure()) && (!cancelled())$ifpart && fromJson(needs.Initialization.outputs.buildOrderJson)[$index].projectsCount > 0" + } + + # Replace the if:, the needs: and the strategy/matrix/project: in the build job with the correct values + $build.Replace('if:', $if) + $build.Replace('needs:', "needs: [ $($needs -join ', ') ]") + $build.Replace('strategy:/matrix:/include:',"include: `${{ fromJson(needs.Initialization.outputs.buildOrderJson)[$index].buildDimensions }}") + + # Last build job is called build, all other build jobs are called build1, build2, etc. + if ($depth -eq ($index + 1)) { + $newBuild += @("Build:") + } + else { + $newBuild += @("Build$($index + 1):") + } + + # Add the content of the calculated build job to the new build job list with an indentation of 2 spaces + $build.content | ForEach-Object { $newBuild += @(" $_") } + } + + # Replace the entire build: job with the new build job list + $yaml.Replace('jobs:/Build:', $newBuild) + + if (!$includeBuildPP -and $buildPP) { + # Remove the BuildPP job from the workflow + [int]$start = 0 + [int]$count = 0 + if ($yaml.Find('jobs:/BuildPP:', [ref] $start, [ref] $count)) { + $yaml.Remove($start, $count+1) + } + } + + $needs += @("Build") + $ifpart += " && (needs.Build.result == 'success' || needs.Build.result == 'skipped')" + if ($includeBuildPP -and $buildPP) { + $needs += @("BuildPP") + $ifpart += " && (needs.BuildPP.result == 'success' || needs.BuildPP.result == 'skipped')" + } + + $postProcessNeeds = $needs + # Modify Deliver and Deploy steps depending on build jobs + if ($deploy) { + $deploy.Replace('needs:', "needs: [ $($needs -join ', ') ]") + $deploy.Replace('if:', "if: (!cancelled())$ifpart && needs.Initialization.outputs.environmentCount > 0") + $yaml.Replace('jobs:/Deploy:/', $deploy.content) + $postProcessNeeds += @('Deploy') + } + if ($deliver) { + $deliver.Replace('needs:', "needs: [ $($needs -join ', ') ]") + $deliver.Replace('if:', "if: (!cancelled())$ifpart && needs.Initialization.outputs.deliveryTargetsJson != '[]'") + $yaml.Replace('jobs:/Deliver:/', $deliver.content) + $postProcessNeeds += @('Deliver') + } + if ($deployALDoc) { + $postProcessNeeds += @('DeployALDoc') + } + if ($codeAnalysisUpload) { + $postProcessNeeds += @('CodeAnalysisUpload') + } + if ($postProcess) { + $postProcess.Replace('needs:', "needs: [ $($postProcessNeeds -join ', ') ]") + $yaml.Replace('jobs:/PostProcess:/', $postProcess.content) + } +} + +function ModifyUpdateALGoSystemFiles { + Param( + [Yaml] $yaml, + [hashtable] $repoSettings + ) + + if($repoSettings.Keys -notcontains 'UpdateALGoSystemFilesEnvironment') { + # If UpdateALGoSystemFilesEnvironment is not set, we don't need to do anything + return + } + + $updateALGoSystemFilesEnvironment = $repoSettings.UpdateALGoSystemFilesEnvironment + Write-Host "Setting 'Update AL-Go System Files' environment to $updateALGoSystemFilesEnvironment" + + # Add or replace the environment: section in the UpdateALGoSystemFiles job + $updateALGoSystemFilesJob = $yaml.Get('jobs:/UpdateALGoSystemFiles:/') + + if(-not $updateALGoSystemFilesJob) { + # Defensively check that the UpdateALGoSystemFiles job exists + throw "No UpdateALGoSystemFiles job found in the workflow" + } + + $environmentSection = $updateALGoSystemFilesJob.Get('environment:') + if($environmentSection) { + # If the environment: section already exists, replace it with the new environment + $updateALGoSystemFilesJob.Replace($environmentSection, "environment: $updateALGoSystemFilesEnvironment") + } + else { + # If the environment: section does not exist, add it + $updateALGoSystemFilesJob.Insert(1, "environment: $updateALGoSystemFilesEnvironment") + } + + $yaml.Replace('jobs:/UpdateALGoSystemFiles:/', $updateALGoSystemFilesJob.content) +} + +function ApplyWorkflowDefaultInputs { + Param( + [Yaml] $yaml, + [hashtable] $repoSettings, + [string] $workflowName + ) + + # Check if workflow_dispatch inputs exist + $workflowDispatch = $yaml.Get('on:/workflow_dispatch:/') + if (-not $workflowDispatch) { + # No workflow_dispatch section, nothing to do + return + } + + $inputs = $workflowDispatch.Get('inputs:/') + if (-not $inputs) { + # No inputs section, nothing to do + return + } + + if ($repoSettings.workflowDefaultInputs.Count -eq 0) { + # No defaults for this workflow + return + } + + # Get workflow_call inputs + $workflowCallInputs = $yaml.Get('on:/workflow_call:/inputs:/') + + # Apply defaults to matching inputs + $workflowDispatchInputsModified = $false + $workflowCallInputsModified = $false + + foreach ($defaultInput in $repoSettings.workflowDefaultInputs) { + # Apply to workflow_dispatch inputs and only update workflow_call if dispatch was modified + if (ApplyWorkflowDefaultInput -workflowName $workflowName -inputs $inputs -defaultInput $defaultInput) { + $workflowDispatchInputsModified = $true + + # Only apply to workflow_call inputs if the workflow_dispatch input was modified + if ($workflowCallInputs) { + if (ApplyWorkflowDefaultInput -workflowName $workflowName -inputs $workflowCallInputs -defaultInput $defaultInput) { + $workflowCallInputsModified = $true + } + } + } + } + + # Update the workflow_dispatch section if modified + if ($workflowDispatchInputsModified) { + $workflowDispatch.Replace('inputs:/', $inputs.content) + $yaml.Replace('on:/workflow_dispatch:/', $workflowDispatch.content) + } + + # Update workflow_call inputs if modified + if ($workflowCallInputsModified) { + $yaml.Replace('on:/workflow_call:/inputs:/', $workflowCallInputs.content) + } +} + +function ApplyWorkflowDefaultInput { + Param( + [string] $workflowName, + [Yaml] $inputs, + [hashtable] $defaultInput + ) + + $inputName = $defaultInput.name + $defaultValue = $defaultInput.value + + # Check if this input exists in the inputs collection + $inputSection = $inputs.Get("$($inputName):/") + if (-not $inputSection) { + # Input is not present in the workflow + return $false + } + + # Get the input type from the YAML if specified + $inputType = $null + $typeStart = 0 + $typeCount = 0 + if ($inputSection.Find('type:', [ref] $typeStart, [ref] $typeCount)) { + $typeLine = $inputSection.content[$typeStart].Trim() + if ($typeLine -match 'type:\s*(.+)') { + $inputType = $matches[1].Trim() + } + } + + # Validate that the value type matches the input type + $validationError = $null + if ($inputType) { + switch ($inputType) { + 'boolean' { + if ($defaultValue -isnot [bool]) { + $validationError = "Workflow '$workflowName', input '$inputName': Expected boolean value, but got $($defaultValue.GetType().Name). Please use `$true or `$false." + } + } + 'number' { + if ($defaultValue -isnot [int] -and $defaultValue -isnot [long] -and $defaultValue -isnot [double]) { + $validationError = "Workflow '$workflowName', input '$inputName': Expected number value, but got $($defaultValue.GetType().Name)." + } + } + 'string' { + if ($defaultValue -isnot [string]) { + $validationError = "Workflow '$workflowName', input '$inputName': Expected string value, but got $($defaultValue.GetType().Name)." + } + } + 'choice' { + # Choice inputs accept strings and must match one of the available options (case-sensitive) + if ($defaultValue -isnot [string]) { + $validationError = "Workflow '$workflowName', input '$inputName': Expected string value for choice input, but got $($defaultValue.GetType().Name)." + } + else { + # Validate that the value is one of the available options + $optionsStart = 0 + $optionsCount = 0 + if ($inputSection.Find('options:', [ref] $optionsStart, [ref] $optionsCount)) { + $availableOptions = @() + # Parse the options from the YAML (they are indented list items starting with "- ") + for ($i = $optionsStart + 1; $i -lt ($optionsStart + $optionsCount); $i++) { + $optionLine = $inputSection.content[$i].Trim() + if ($optionLine -match '^-\s*(.+)$') { + $availableOptions += $matches[1].Trim() + } + } + + if ($availableOptions.Count -gt 0 -and $availableOptions -cnotcontains $defaultValue) { + $validationError = "Workflow '$workflowName', input '$inputName': Value '$defaultValue' is not a valid choice (case-sensitive match required). Available options: $($availableOptions -join ', ')." + } + } + } + } + } + } + else { + # If no type is specified in the workflow, it defaults to string + if ($defaultValue -isnot [string]) { + OutputWarning "Workflow '$workflowName', input '$inputName': No type specified in workflow (defaults to string), but configured value is $($defaultValue.GetType().Name). This may cause issues." + } + } + + if ($validationError) { + throw $validationError + } + + # Convert the default value to the appropriate YAML format + $yamlValue = $defaultValue + if ($defaultValue -is [bool]) { + $yamlValue = $defaultValue.ToString().ToLower() + } + elseif ($defaultValue -is [string]) { + # Quote strings and escape single quotes per YAML spec + $escapedValue = $defaultValue.Replace("'", "''") + $yamlValue = "'$escapedValue'" + } + + # Find and replace the default: line in the input section + $start = 0 + $count = 0 + + if ($inputSection.Find('default:', [ref] $start, [ref] $count)) { + # Replace existing default value + $inputSection.Replace('default:', "default: $yamlValue") + } + else { + # Add default value - find the best place to insert it + # Insert after type, required, or description (whichever comes last) + $insertAfter = -1 + $typeLine = 0 + $typeCount = 0 + $requiredLine = 0 + $requiredCount = 0 + $descLine = 0 + $descCount = 0 + + if ($inputSection.Find('type:', [ref] $typeLine, [ref] $typeCount)) { + $insertAfter = $typeLine + $typeCount + } + if ($inputSection.Find('required:', [ref] $requiredLine, [ref] $requiredCount)) { + if (($requiredLine + $requiredCount) -gt $insertAfter) { + $insertAfter = $requiredLine + $requiredCount + } + } + if ($inputSection.Find('description:', [ref] $descLine, [ref] $descCount)) { + if (($descLine + $descCount) -gt $insertAfter) { + $insertAfter = $descLine + $descCount + } + } + + if ($insertAfter -eq -1) { + # No other properties, insert at position 1 (after the input name) + $insertAfter = 1 + } + + $inputSection.Insert($insertAfter, "default: $yamlValue") + } + + # Update the inputs collection with the modified input section + $inputs.Replace("$($inputName):/", $inputSection.content) + + return $true +} + +function GetWorkflowContentWithChangesFromSettings { + Param( + [string] $srcFile, + [hashtable] $repoSettings, + [int] $depth + ) + + $baseName = [System.IO.Path]::GetFileNameWithoutExtension($srcFile) + $yaml = [Yaml]::Load($srcFile) + $yamlName = $yaml.get('name:') + if ($yamlName) { + $workflowName = $yamlName.content.SubString('name:'.Length).Trim().Trim('''"').Trim() + } + else { + $workflowName = $baseName + } + + $workflowScheduleKey = "WorkflowSchedule" + $workflowConcurrencyKey = "WorkflowConcurrency" + foreach($key in @($workflowScheduleKey,$workflowConcurrencyKey)) { + if ($repoSettings.Keys -contains $key -and ($repoSettings."$key")) { + throw "The $key setting is not allowed in the global repository settings. Please use the workflow specific settings file or conditional settings." + } + } + + # Re-read settings and this time include workflow specific settings + $repoSettings = ReadSettings -buildMode '' -project '' -workflowName $workflowName -userName '' -branchName '' -trigger '' | ConvertTo-HashTable -recurse + + # Old Schedule key is deprecated, but still supported + $oldWorkflowScheduleKey = "$($baseName)Schedule" + if ($repoSettings.Keys -contains $oldWorkflowScheduleKey) { + # DEPRECATION: REPLACE WITH ERROR AFTER October 1st 2025 ---> + if ($repoSettings.Keys -contains $workflowScheduleKey) { + OutputWarning "Both $oldWorkflowScheduleKey and $workflowScheduleKey are defined in the settings file. $oldWorkflowScheduleKey will be ignored. This warning will become an error in the future" + } + else { + Trace-DeprecationWarning -Message "$oldWorkflowScheduleKey is deprecated" -DeprecationTag "_workflow_Schedule" -WillBecomeError + # Convert the old Schedule setting to the new WorkflowSchedule setting + $repoSettings."$workflowScheduleKey" = @{ "cron" = $repoSettings."$oldWorkflowScheduleKey" } + } + # <--- REPLACE WITH ERROR AFTER October 1st 2025 + } + + # Any workflow (except for the PullRequestHandler and reusable workflows (_*)) can have concurrency and schedule defined + if ($baseName -ne "PullRequestHandler" -and $baseName -notlike '_*') { + # Add Schedule and Concurrency settings to the workflow + if ($repoSettings.Keys -contains $workflowScheduleKey) { + if ($repoSettings."$workflowScheduleKey" -isnot [hashtable] -or $repoSettings."$workflowScheduleKey".Keys -notcontains 'cron' -or $repoSettings."$workflowScheduleKey".cron -isnot [string]) { + throw "The $workflowScheduleKey setting must be a structure containing a cron property" + } + # Replace or add the schedule part under the on: key + $yaml.ReplaceOrAdd('on:/', 'schedule:', @("- cron: '$($repoSettings."$workflowScheduleKey".cron)'")) + } + if ($repoSettings.Keys -contains $workflowConcurrencyKey) { + # Replace or add the concurrency part + $yaml.ReplaceOrAdd('', 'concurrency:', $repoSettings."$workflowConcurrencyKey") + } + } + + if ($baseName -eq "CICD") { + ModifyCICDWorkflow -yaml $yaml -repoSettings $repoSettings + } + + if ( + $repoSettings.Keys -contains 'CodeReviewAgent' -and + $repoSettings.CodeReviewAgent -is [System.Collections.IDictionary] -and + $repoSettings.CodeReviewAgent.Keys -contains 'enabled' -and + $repoSettings.CodeReviewAgent.enabled + ) { + if ($baseName -eq 'CopilotPRReview') { + ModifyCopilotPRReviewWorkflow -yaml $yaml -repoSettings $repoSettings + } + elseif ($baseName -eq 'CopilotPRReviewRunner') { + $yaml.ReplaceOrAdd('on:/', 'workflow_run:', @( + 'workflows: [ Copilot PR Review ]' + 'types: [ completed ]' + )) + } + } + + $criticalWorkflows = @('UpdateGitHubGoSystemFiles', 'Troubleshooting', 'CopilotPRReviewRunner') + $allowedRunners = @('windows-latest', 'ubuntu-latest') + $modifyRunsOnAndShell = $true + + # Critical workflows may only run on allowed runners (must always be able to run) + if($criticalWorkflows -contains $baseName) { + if($allowedRunners -notcontains $repoSettings."runs-on") { + $modifyRunsOnAndShell = $false + } + } + + if ($modifyRunsOnAndShell) { + ModifyRunsOnAndShell -yaml $yaml -repoSettings $repoSettings + } + + # PullRequestHandler, CICD, Current, NextMinor and NextMajor workflows all include a build step. + # If the dependency depth is higher than 1, we need to add multiple dependent build jobs to the workflow + if ($baseName -eq 'PullRequestHandler' -or $baseName -eq 'CICD' -or $baseName -eq 'Current' -or $baseName -eq 'NextMinor' -or $baseName -eq 'NextMajor') { + $includeBuildPP = $repoSettings.type -eq 'PTE' -and $repoSettings.powerPlatformSolutionFolder -ne '' + ModifyBuildWorkflows -yaml $yaml -depth $depth -includeBuildPP $includeBuildPP + } + + if ($baseName -eq "PullRequestHandler") { + ModifyPullRequestHandlerWorkflow -yaml $yaml -repoSettings $repoSettings + } + + if($baseName -eq 'UpdateGitHubGoSystemFiles') { + ModifyUpdateALGoSystemFiles -yaml $yaml -repoSettings $repoSettings + } + + # Apply workflow input defaults from settings + if ($repoSettings.Keys -contains 'workflowDefaultInputs') { + ApplyWorkflowDefaultInputs -yaml $yaml -repoSettings $repoSettings -workflowName $workflowName + } + + # combine all the yaml file lines into a single string with LF line endings + $yaml.content -join "`n" +} + +# Using direct AL-Go repo, we need to change the owner to the templateOwner, the repo names to AL-Go and AL-Go/Actions and the branch to templateBranch + +function ReplaceOwnerRepoAndBranch { + Param( + [ref] $srcContent, + [string] $templateOwner, + [string] $templateBranch + ) + + $lines = $srcContent.Value.Split("`n") + + # The Original Owner and Repo in the AL-Go repository are microsoft/AL-Go-Actions, microsoft/AL-Go-PTE and microsoft/AL-Go-AppSource + $originalOwnerAndRepo = @{ + "actionsRepo" = "microsoft/AL-Go-Actions" + "perTenantExtensionRepo" = "microsoft/AL-Go-PTE" + "appSourceAppRepo" = "microsoft/AL-Go-AppSource" + } + # Original branch is always main + $originalBranch = "main" + + # Modify the file to use repository names based on whether or not we are using the direct AL-Go repo + $templateRepos = @{ + "actionsRepo" = "AL-Go/Actions" + "perTenantExtensionRepo" = "AL-Go" + "appSourceAppRepo" = "AL-Go" + } + + # Replace URL's to actions repository first + $regex = "^(.*)https:\/\/raw\.githubusercontent\.com\/microsoft\/AL-Go-Actions\/$originalBranch(.*)$" + $replace = "`${1}https://raw.githubusercontent.com/$($templateOwner)/AL-Go/$($templateBranch)/Actions`${2}" + $lines = $lines | ForEach-Object { $_ -replace $regex, $replace } + + # Replace the owner and repo names in the workflow + "actionsRepo","perTenantExtensionRepo","appSourceAppRepo" | ForEach-Object { + $regex = "^(.*)$($originalOwnerAndRepo."$_")(.*)$originalBranch(.*)$" + $replace = "`${1}$($templateOwner)/$($templateRepos."$_")`${2}$($templateBranch)`${3}" + $lines = $lines | ForEach-Object { $_ -replace $regex, $replace } + } + $srcContent.Value = $lines -join "`n" +} + +function IsDirectALGo { + param ( + [string] $templateUrl + ) + $directALGo = $templateUrl -like 'https://github.com/*/AL-Go@*' + if ($directALGo) { + if ($templateUrl -like 'https://github.com/microsoft/AL-Go@*' -and -not ($templateUrl -like 'https://github.com/microsoft/AL-Go@*/*')) { + throw "You cannot use microsoft/AL-Go as a template repository. Please use microsoft/AL-Go-PTE, microsoft/AL-Go-AppSource or a fork of AL-Go instead." + } + } + return $directALGo +} + +function GetSrcFolder { + Param( + [string] $repoType, + [string] $templateUrl, + [string] $templateFolder, + [string] $srcPath = '' + ) + + if (!$templateUrl) { + return '' + } + if (IsDirectALGo -templateUrl $templateUrl) { + switch ($repoType) { + "PTE" { + $typePath = "Per Tenant Extension" + } + "AppSource App" { + $typePath = "AppSource App" + } + default { + throw "Unknown repository type" + } + } + $path = Join-Path $templateFolder "*/Templates/$typePath/.github/workflows" + } + else { + $path = Join-Path $templateFolder "*/.github/workflows" + } + # Due to this PowerShell bug: https://github.com/PowerShell/PowerShell/issues/6473#issuecomment-375930843 + # We need to resolve the path of a non-hidden folder (.github/workflows) + # and then get the parent folder of the parent folder of that path + $path = Resolve-Path -Path $path -ErrorAction SilentlyContinue + if (!$path) { + throw "No workflows found in the template repository" + } + $path = Join-Path -Path (Split-Path -Path (Split-Path -Path $path -Parent) -Parent) -ChildPath $srcPath + return $path +} + +function GetModifiedSettingsContent { + Param( + [string] $srcSettingsFile, + [string] $dstSettingsFile + ) + + $srcSettings = Get-ContentLF -Path $srcSettingsFile | ConvertFrom-Json + + $dstSettings = $null + if(Test-Path -LiteralPath $dstSettingsFile -PathType Leaf) { + $dstSettings = Get-ContentLF -Path $dstSettingsFile | ConvertFrom-Json + } + + if(!$dstSettings) { + # If the destination settings file does not exist or it's empty, create an new settings object with default values from the source settings (which includes the $schema property already) + $dstSettings = $srcSettings + } + else { + # Change the $schema property to be the same as the source settings file (add it if it doesn't exist) + $schemaKey = '$schema' + if ($srcSettings.PSObject.Properties.Name -eq $schemaKey) { + $schemaValue = $srcSettings."$schemaKey" + + $dstSettings | Add-Member -MemberType NoteProperty -Name "$schemaKey" -Value $schemaValue -Force + + # Make sure the $schema property is the first property in the object + # PS5-safe: explicitly list properties instead of using wildcard to avoid literal '*' being added + $otherProperties = @($dstSettings.PSObject.Properties.Name | Where-Object { $_ -ne $schemaKey }) + $selectProperties = @($schemaKey) + $otherProperties + $dstSettings = $dstSettings | Select-Object -Property $selectProperties + } + } + + return $dstSettings | ConvertTo-JsonLF +} + +<# +.SYNOPSIS +Determines whether a system-files update has changes beyond advancing an existing template SHA. +.PARAMETER settingsFile +The repository settings file containing the last applied template URL and SHA. +.PARAMETER templateUrl +The template URL selected for this update. +.PARAMETER updateFiles +The files to add or update. +.PARAMETER removeFiles +The files to remove. +#> +function Test-HasSystemFileChanges { + Param( + [string] $settingsFile, + [string] $templateUrl, + [array] $updateFiles, + [array] $removeFiles + ) + + if (-not $updateFiles -and -not $removeFiles -and (Test-Path -LiteralPath $settingsFile -PathType Leaf)) { + $currentSettings = Get-Content -LiteralPath $settingsFile -Encoding UTF8 | ConvertFrom-Json | ConvertTo-HashTable -recurse + if ($currentSettings['templateUrl'] -ceq $templateUrl -and $currentSettings['templateSha']) { + return $false + } + } + return $true +} + +function UpdateSettingsFile { + Param( + [string] $settingsFile, + [hashtable] $updateSettings + ) + + $modified = $false + # Update Repo Settings file with the template URL + if (Test-Path -LiteralPath $settingsFile) { + $settings = Get-Content -LiteralPath $settingsFile -Encoding UTF8 | ConvertFrom-Json + } + else { + $settings = [PSCustomObject]@{} + $modified = $true + } + foreach($key in $updateSettings.Keys) { + if ($settings.PSObject.Properties.Name -eq $key) { + if ($settings."$key" -ne $updateSettings."$key") { + $settings."$key" = $updateSettings."$key" + $modified = $true + } + } + else { + # Add the property if it doesn't exist + $settings | Add-Member -MemberType NoteProperty -Name "$key" -Value $updateSettings."$key" + $modified = $true + } + } + if ($modified) { + # Save the file with LF line endings and UTF8 encoding + $settings | Set-JsonContentLF -path $settingsFile + } + return $modified +} + +<# +.SYNOPSIS +Returns the path string comparison: ordinal on Linux, ordinal-ignore-case otherwise. +#> +function GetPathStringComparison { + if ($PSVersionTable.PSVersion.Major -ge 6 -and $IsLinux) { + return [System.StringComparison]::Ordinal + } + else { + return [System.StringComparison]::OrdinalIgnoreCase + } +} + +<# +.SYNOPSIS +Returns the path string comparer: ordinal on Linux, ordinal-ignore-case otherwise. +#> +function GetPathStringComparer { + if ((GetPathStringComparison) -eq [System.StringComparison]::Ordinal) { + return [System.StringComparer]::Ordinal + } + else { + return [System.StringComparer]::OrdinalIgnoreCase + } +} + +<# +.SYNOPSIS +Resolves a path to an absolute, lexically-canonicalized path (resolving ".." and "." segments). +.DESCRIPTION +[System.IO.Path]::GetFullPath() resolves a relative path against [System.Environment]::CurrentDirectory, +which Set-Location does not reliably keep in sync with PowerShell's own current location - so a bare +GetFullPath() call can silently resolve against a stale directory after Set-Location. This function instead +joins a relative $Path against PowerShell's actual current location before canonicalizing, so behavior is +correct regardless of that .NET/PowerShell CWD desync. +.PARAMETER Path +The literal path to resolve. If not rooted, it is considered relative to the current location. +.PARAMETER AsDirectory +If set, ensures the returned path ends with a directory separator (e.g. for safe prefix/StartsWith checks). +.OUTPUTS +The absolute, lexically-canonicalized path. +#> +function Resolve-PathLexically { + Param( + [Parameter(Mandatory=$true)] + [string] $Path, + [switch] $AsDirectory + ) + + if (-not [System.IO.Path]::IsPathRooted($Path)) { + $Path = Join-Path (Get-Location).Path $Path # resolve relative to the current location + } + + $Path = [System.IO.Path]::GetFullPath($Path) # canonicalize the path to an absolute path + + if ($AsDirectory) { + $Path = Join-Path $Path '' # ensure the path ends with a directory separator + } + + return $Path +} + +<# +.SYNOPSIS +Checks whether a path is lexically contained within a root folder, resolving ".." and "." segments. +.DESCRIPTION +Verifies that $Path is located under $RootFolder purely by string/segment resolution (via Resolve-PathLexically) +.PARAMETER Path +The literal path to check. If not rooted, it is considered relative to the root folder. +.PARAMETER RootFolder +The literal root folder that $Path must be contained within. Defaults to the current location if not specified. +.OUTPUTS +$true if the path is lexically contained within the root folder, otherwise $false. +#> +function Test-PathLexicallyContained { + Param( + [Parameter(Mandatory=$true)] + [string] $Path, + [string] $RootFolder = (Get-Location).Path + ) + + $pathComparison = GetPathStringComparison + + $RootFolder = Resolve-PathLexically -Path $RootFolder -AsDirectory + + if (-not [System.IO.Path]::IsPathRooted($Path)) { + $Path = Join-Path $RootFolder $Path # resolve relative to the root folder + } + # AsDirectory here (not just for $RootFolder) makes $Path itself count as contained, not just its descendants + $Path = Resolve-PathLexically -Path $Path -AsDirectory + + return $Path.StartsWith($RootFolder, $pathComparison) +} + +<# +.SYNOPSIS +Resolves a path to its final physical location, following any symbolic links/junctions along the way. +.DESCRIPTION +Walks $Path segment by segment starting from the most specific trusted anchor that lexically contains it, +resolving any symbolic links or junctions encountered along the way. +.PARAMETER Path +The literal path to resolve. +.PARAMETER AnchorPaths +An array of trusted anchor paths (folders, or specific files/reparse points) to start resolution from; +reparse points within these paths are ignored (or they are otherwise known to be free of reparse points). +The function will start resolution from the most specific entry in this list that lexically contains $Path +(or that equals $Path exactly). +.OUTPUTS +The resolved path (including any nonexistent trailing segments), or $null if a path segment could not be +inspected or the reparse point chain exceeded the hop limit. The filesystem root is a fallback anchor. +#> +function Resolve-PathPhysically { + Param( + [Parameter(Mandatory=$true)] + [string] $Path, + [string[]] $AnchorPaths = @() + ) + + $realPath = Resolve-PathLexically -Path $Path # canonicalize the path to an absolute path + + $segments = [System.Collections.Generic.List[string]]::new() + $resolveReparsePoints = $true # once an ancestor doesn't exist, no deeper segment can be a reparse point either + $hopLimit = 40 # matches the classic OS/.NET max-followed-symlinks limit (guards against cyclic chains) + $hopCount = 0 + + # Start from the deepest trusted anchor that contains the target path. + $anchorPath = @($AnchorPaths) + @([System.IO.Path]::GetPathRoot($realPath)) | # combine user-provided anchor folders with the root of the target path + ForEach-Object { Resolve-PathLexically -Path $_ -AsDirectory } | # canonicalize each anchor folder to an absolute path as a directory + Sort-Object -Descending | # nested paths sort before their containing prefixes + Where-Object { Test-PathLexicallyContained -Path $realPath -RootFolder $_ } | # filter only those anchor folders that lexically contain the target path + Select-Object -First 1 + + if ($realPath.Length -gt $anchorPath.Length) { + $segments.AddRange([string[]] $realPath.Substring($anchorPath.Length).Split([System.IO.Path]::DirectorySeparatorChar, [System.IO.Path]::AltDirectorySeparatorChar)) + $realPath = $anchorPath + } + + while ($segments.Count -gt 0) { + $realPath = Join-Path $realPath $segments[0] + $segments.RemoveAt(0) + + if (-not $resolveReparsePoints) { + continue + } + + try { + $item = Get-Item -LiteralPath $realPath -Force -ErrorAction Stop + } + catch [System.Management.Automation.ItemNotFoundException] { + $resolveReparsePoints = $false + continue + } + catch { + OutputWarning "Path '$Path' could not be resolved: unable to inspect '$realPath'." + return $null + } + + if ($null -eq $item) { + # Required for PS5.1 as Get-Item may return $null instead of throwing when the item does not exist + $resolveReparsePoints = $false + continue + } + if ($item.LinkType -notin @('SymbolicLink', 'Junction') -or -not $item.Target) { + if ($item -is [System.IO.DirectoryInfo]) { + $AnchorPaths += $item.FullName # this segment itself is confirmed not a reparse point + } + continue + } + + if ($hopCount++ -ge $hopLimit) { + # Cyclic or pathologically deep chain - fail closed, like the OS would refuse to resolve it too + OutputWarning "Path '$Path' could not be resolved: reparse point chain exceeded $($hopLimit) hops (cyclic or too deep) at '$realPath'." + return $null + } + + $realPath = @($item.Target)[0] + if (-not [System.IO.Path]::IsPathRooted($realPath)) { + $realPath = Join-Path ([System.IO.Path]::GetDirectoryName($item.FullName)) $realPath + } + $realPath = Resolve-PathLexically -Path $realPath + + # Recheck from the deepest trusted anchor after following the link target. + $anchorPath = @($AnchorPaths) + @([System.IO.Path]::GetPathRoot($realPath)) | # combine user-provided anchor folders with the root of the target path + ForEach-Object { Resolve-PathLexically -Path $_ -AsDirectory } | # canonicalize each anchor folder to an absolute path as a directory + Sort-Object -Descending | # nested paths sort before their containing prefixes + Where-Object { Test-PathLexicallyContained -Path $realPath -RootFolder $_ } | # filter only those anchor folders that lexically contain the target path + Select-Object -First 1 + + if ($realPath.Length -gt $anchorPath.Length) { + # Re-inject every unverified segment of the resolved target so an embedded reparse point (e.g. link1 -> + # "link2/sub" where link2 itself escapes the root) gets its own resolve on a later iteration. + $segments.InsertRange(0, [string[]] $realPath.Substring($anchorPath.Length).Split([System.IO.Path]::DirectorySeparatorChar, [System.IO.Path]::AltDirectorySeparatorChar)) + $realPath = $anchorPath + } + } + + return $realPath +} + +<# +.SYNOPSIS +Checks whether a path physically resolves to itself, i.e. no reparse point along the way redirects it. +.DESCRIPTION +Resolves $Path (see Resolve-PathPhysically) and compares the result to $Path itself. +.PARAMETER Path +The literal path expected to be its own final physical location. +.PARAMETER AnchorPaths +An array of trusted anchor paths (folders, or specific files/reparse points) to start resolution from; +reparse points within these paths are ignored (or they are otherwise known to be free of reparse points). +.OUTPUTS +$true if $Path resolves to itself (including a nonexistent trailing path), otherwise $false. +$false also means physical resolution failed. +#> +function Test-PathPhysicallyEqual { + Param( + [Parameter(Mandatory=$true)] + [string] $Path, + [string[]] $AnchorPaths = @() + ) + + $pathComparer = GetPathStringComparer + + $Path = Resolve-PathLexically -Path $Path + + $realPath = Resolve-PathPhysically -Path $Path -AnchorPaths $AnchorPaths + if (-not $realPath) { + return $false + } + + return $pathComparer.Equals($realPath, $Path) +} + +<# +.SYNOPSIS +Blocks paths that do not physically resolve to themselves or cannot be verified. +.PARAMETER Path +The path to validate before accessing it. +.PARAMETER AnchorPaths +Trusted anchors passed to Test-PathPhysicallyEqual. +.PARAMETER Context +The role of the path, such as source file or repository settings. +#> +function Assert-PathPhysicallyEqual { + Param( + [Parameter(Mandatory=$true)] + [string] $Path, + [string[]] $AnchorPaths = @(), + [Parameter(Mandatory=$true)] + [string] $Context + ) + + if (-not (Test-PathPhysicallyEqual -Path $Path -AnchorPaths $AnchorPaths)) { + throw "Unsafe path blocked: $Context '$Path' does not physically resolve to itself, or its physical location could not be verified. This may indicate a symlink/junction redirect." + } +} + +<# +.SYNOPSIS +Resolves file paths based on the provided source folder, destination folder, and file specifications. + +.DESCRIPTION +This function takes a source folder, an optional original source folder, a destination folder, and an array of file specifications. It resolves the full paths for each specified file, considering their origin (template or custom template), type, and whether they are per-project files. +The function returns an array of hashtables containing the resolved source and destination file paths. +The function is used to determine which files need to be copied from the template repository to the target repository during the AL-Go update process. +Both source and destination boundary checks are lexical-only (see Test-PathLexicallyContained, resolving ".."/"." segments) - neither does a filesystem-aware symlink/junction walk here. Physical resolution (see Test-PathPhysicallyEqual/Resolve-PathPhysically) is instead re-checked immediately before each source file is actually read and each destination file is actually written/removed, in CheckForUpdates.ps1: for the destination this is required, since the destination folder is later relocated into a new clone (see CloneIntoNewFolder) before files are written, so a filesystem-based check here would validate the wrong location anyway; for the source there is no such relocation, but checking at the point of use keeps both sides symmetric and covers the file exactly as it will be read. +sourceFolder: The base folder of the template used to resolve the source file paths. +originalSourceFolder: The base folder of the original template used to check for original files (can be $null). This is in the case of custom templates, where if the file exists in the original template, it should be used instead of the custom template file. +destinationFolder: The base folder used to construct the destination file paths. This is typically the root folder of the target repository. + +.PARAMETER sourceFolder +The base folder where the source files are located. + +.PARAMETER originalSourceFolder +The original source folder to check for original files (can be $null). All files of origin 'custom template' are skipped if this parameter is $null. + +.PARAMETER destinationFolder +The base folder used to construct the destination file paths. + +.PARAMETER files +An array of hashtables specifying the files to resolve. Each hashtable can contain the following keys: +- sourceFolder: The subfolder within the source folder to search for files (default is current folder). +- filter: The file filter to apply when searching for files (default is all files). +- origin: The origin of the files, either 'template' or 'custom template' (default is 'template'). +- type: The type of the files (default is empty). +- destinationFolder: The subfolder within the destination folder where the files should be placed (default is the same as sourceFolder). +- destinationName: The destination filename to use instead of the source filename (default is the source filename). +- perProject: A boolean indicating whether the files are per project (default is false). + +.PARAMETER projects +An array of project names used when resolving per-project file paths. + +.OUTPUTS +An array of hashtables, each containing: +- sourceFullPath: The full path to the source file. +- originalSourceFullPath: The full path to the original source file (if found, otherwise $null). +- type: The type of the file. +- destinationFullPath: The full path to the destination file. +#> +function ResolveFilePaths { + Param( + [Parameter(Mandatory=$true)] + [string] $sourceFolder, + [string] $originalSourceFolder = $null, + [Parameter(Mandatory=$true)] + [string] $destinationFolder, + [array] $files = @(), + [string[]] $projects = @() + ) + + if(-not $files) { + return @() + } + + $sourceFolder = Resolve-PathLexically -Path $sourceFolder -AsDirectory + $destinationFolder = Resolve-PathLexically -Path $destinationFolder -AsDirectory + + $fullFilePaths = @() + foreach($file in $files) { + if($file.Keys -notcontains 'sourceFolder') { + $file.sourceFolder = '' # Default to current folder + } + + if($file.Keys -notcontains 'filter') { + $file.filter = '' # Default to all files + } + + if($file.Keys -notcontains 'origin') { + $file.origin = 'template' # Default to template + } + + if($file.Keys -notcontains 'type') { + $file.type = '' # Default to empty + } + + if($file.Keys -notcontains 'destinationFolder') { + # If destinationFolder is not specified, use the sourceFolder, so that the file structure is preserved + $file.destinationFolder = $file.sourceFolder + } + + if($file.Keys -notcontains 'perProject') { + $file.perProject = $false # Default to false + } + + # If originalSourceFolder is not specified, it means there is no custom template, so skip custom template files + if(!$originalSourceFolder -and $file.origin -eq 'custom template') { + OutputDebug "Skipping custom template file(s) with source folder '$($file.sourceFolder)' as there is no original source folder specified" + continue; + } + + # All files are relative to the template folder + OutputDebug "Resolving files for source folder '$($file.sourceFolder)' and filter '$($file.filter)'" + $fileSourceFolder = Join-Path $sourceFolder $file.sourceFolder + if (-not (Test-PathLexicallyContained -Path $fileSourceFolder -RootFolder $sourceFolder)) { + OutputDebug "Skipping source folder '$fileSourceFolder' as it is not under the source folder '$sourceFolder'." + continue + } + $sourceFiles = @(Get-ChildItem -LiteralPath $fileSourceFolder -Filter $file.filter -File -ErrorAction SilentlyContinue | Select-Object -ExpandProperty FullName) + + OutputDebug "Found $($sourceFiles.Count) files for filter '$($file.filter)' in folder '$($file.sourceFolder)' (relative to folder '$sourceFolder', origin '$($file.origin)')" + + if(-not $sourceFiles) { + OutputDebug "No files found for filter '$($file.filter)' in folder '$($file.sourceFolder)' (relative to folder '$sourceFolder')" + continue + } + + foreach($srcFile in $sourceFiles) { + $fullFilePath = @{ + 'sourceFullPath' = $srcFile + 'originalSourceFullPath' = $null + 'type' = $file.type + 'destinationFullPath' = $null + } + + # Check if the source file is under the source folder (lexical, resolves ".."/".") + if (-not (Test-PathLexicallyContained -Path $srcFile -RootFolder $sourceFolder)) { + OutputDebug "Skipping source file '$($srcFile)' as it is not under the source folder '$($sourceFolder)'." + continue + } + + OutputDebug "Processing file '$($srcFile)'" + + # Try to find the same files in the original template folder if it is specified. Exclude custom template files + if ($originalSourceFolder -and ($file.origin -ne 'custom template')) { + $relativeSourceFile = $srcFile.Substring($sourceFolder.Length) + $originalSourceFile = Join-Path $originalSourceFolder $relativeSourceFile + $originalSourceFile = Resolve-PathLexically -Path $originalSourceFile + if (Test-Path -LiteralPath $originalSourceFile -PathType Leaf) { + if (Test-PathLexicallyContained -Path $originalSourceFile -RootFolder $originalSourceFolder) { + # If the file exists in the original template folder, use that file instead + $fullFilePath.originalSourceFullPath = $originalSourceFile + } + else { + OutputWarning "Skipping source file '$srcFile' as the original source file '$originalSourceFile' is not under the original source folder '$originalSourceFolder'." + continue + } + } + } + + $destinationName = Split-Path -Path $srcFile -Leaf + if($file.Keys -contains 'destinationName' -and ($file.destinationName)) { + $destinationName = $file.destinationName + } + + if($file.Keys -contains 'perProject' -and $file.perProject -eq $true) { + # Multiple file entries, one for each project + # Destination full path is the destination base folder + project + destinationFolder + destinationName + + foreach($project in $projects) { + if($project -eq '.') { + $project = '' # If project is '.', it means the root folder, so we use an empty string + } + + if ($project.Split([System.IO.Path]::DirectorySeparatorChar, [System.IO.Path]::AltDirectorySeparatorChar) -contains '..') { + OutputWarning "Skipping file '$srcFile' for project '$project': project path contains parent-directory traversal." + continue + } + + $projectDestinationFolder = Join-Path $destinationFolder $project + $projectDestinationFolder = Resolve-PathLexically -Path $projectDestinationFolder -AsDirectory + + # Check if the project destination folder is under the base destination folder (lexical, resolves ".."/".") + if (-not (Test-PathLexicallyContained -Path $projectDestinationFolder -RootFolder $destinationFolder)) { + OutputWarning "Skipping file '$srcFile' for project '$project': project destination folder '$projectDestinationFolder' is outside the base destination folder '$destinationFolder'." + continue + } + + $fileDestinationFolder = Join-Path $projectDestinationFolder $file.destinationFolder + $fileDestinationFolder = Resolve-PathLexically -Path $fileDestinationFolder -AsDirectory + + # Check if the destination folder is under the project destination folder (lexical, resolves ".."/".") + if (-not (Test-PathLexicallyContained -Path $fileDestinationFolder -RootFolder $projectDestinationFolder)) { + OutputWarning "Skipping file '$srcFile' for project '$project': destination folder '$fileDestinationFolder' is outside the project destination folder '$projectDestinationFolder'." + continue + } + + $fullProjectFilePath = $fullFilePath.Clone() + $fullProjectFilePath.destinationFullPath = Join-Path $fileDestinationFolder $destinationName + $fullProjectFilePath.destinationFullPath = Resolve-PathLexically -Path $fullProjectFilePath.destinationFullPath + + # Check if the destination file is under the file destination folder (lexical, resolves ".."/".") + if (-not (Test-PathLexicallyContained -Path $fullProjectFilePath.destinationFullPath -RootFolder $fileDestinationFolder)) { + OutputWarning "Skipping file '$srcFile' for project '$project': destination file '$($fullProjectFilePath.destinationFullPath)' is outside the file destination folder '$fileDestinationFolder'." + continue + } + + OutputDebug "Adding per-project file for project '$project': sourceFullPath '$($fullProjectFilePath.sourceFullPath)', originalSourceFullPath '$($fullProjectFilePath.originalSourceFullPath)', destinationFullPath '$($fullProjectFilePath.destinationFullPath)'" + $fullFilePaths += $fullProjectFilePath + } + } + else { + # Single file entry + # Destination full path is the destination base folder + destinationFolder + destinationName + + $fileDestinationFolder = Join-Path $destinationFolder $file.destinationFolder + $fileDestinationFolder = Resolve-PathLexically -Path $fileDestinationFolder -AsDirectory + + # Check if the destination folder is under the base destination folder (lexical, resolves ".."/".") + if (-not (Test-PathLexicallyContained -Path $fileDestinationFolder -RootFolder $destinationFolder)) { + OutputWarning "Skipping file '$srcFile': destination folder '$fileDestinationFolder' is outside the base destination folder '$destinationFolder'." + continue + } + + $fullFilePath.destinationFullPath = Join-Path $fileDestinationFolder $destinationName + $fullFilePath.destinationFullPath = Resolve-PathLexically -Path $fullFilePath.destinationFullPath + + # Check if the destination file is under the file destination folder (lexical, resolves ".."/".") + if (-not (Test-PathLexicallyContained -Path $fullFilePath.destinationFullPath -RootFolder $fileDestinationFolder)) { + OutputWarning "Skipping file '$srcFile': destination file '$($fullFilePath.destinationFullPath)' is outside the file destination folder '$fileDestinationFolder'." + continue + } + + OutputDebug "Adding file: sourceFullPath '$($fullFilePath.sourceFullPath)', originalSourceFullPath '$($fullFilePath.originalSourceFullPath)', destinationFullPath '$($fullFilePath.destinationFullPath)'" + $fullFilePaths += $fullFilePath + } + } + } + + return @($fullFilePaths) +} + +function GetDefaultFilesToInclude { + Param( + [switch] $includeCustomTemplateFiles + ) + + $filesToInclude = @( + [ordered]@{ 'sourceFolder' = '.github/workflows'; 'filter' = '*.yaml'; 'type' = 'workflow' } + [ordered]@{ 'sourceFolder' = '.github/workflows'; 'filter' = '*.yml'; 'type' = 'workflow' } + [ordered]@{ 'sourceFolder' = '.github'; 'filter' = '*.copy.md' } + [ordered]@{ 'sourceFolder' = '.github'; 'filter' = '*.ps1' } + [ordered]@{ 'sourceFolder' = '.github'; 'filter' = "$RepoSettingsFileName"; 'type' = 'settings' } + [ordered]@{ 'sourceFolder' = '.github'; 'filter' = '*.settings.json'; 'type' = 'settings' } + [ordered]@{ 'sourceFolder' = '.github/.agents'; 'filter' = '*.agent.md' } + + [ordered]@{ 'sourceFolder' = '.AL-Go'; 'filter' = '*.ps1'; 'perProject' = $true }, + [ordered]@{ 'sourceFolder' = '.AL-Go'; 'filter' = "$ALGoSettingsFileName"; 'perProject' = $true; 'type' = 'settings' } + ) + + if($includeCustomTemplateFiles) { + # If there is an original template folder, we also need to include custom template files (RepoSettings and ProjectSettings) + $filesToInclude += @( + [ordered]@{ 'sourceFolder' = ".github"; 'filter' = "$RepoSettingsFileName"; 'destinationName' = "$CustomTemplateRepoSettingsFileName"; 'origin' = 'custom template' } + [ordered]@{ 'sourceFolder' = ".AL-Go"; 'filter' = "$ALGoSettingsFileName"; 'destinationFolder' = '.github'; 'destinationName' = "$CustomTemplateProjectSettingsFileName"; 'origin' = 'custom template' } + ) + } + + return $filesToInclude +} + +function GetDefaultFilesToExclude { + Param( + $settings + ) + $filesToExclude = @() + + $includeBuildPP = $settings.type -eq 'PTE' -and $settings.powerPlatformSolutionFolder -ne '' + if (!$includeBuildPP) { + # Remove PowerPlatform workflows if no PowerPlatformSolution exists + $filesToExclude += @( + [ordered]@{ 'sourceFolder' = '.github/workflows'; 'filter' = '_BuildPowerPlatformSolution.yaml' } + [ordered]@{ 'sourceFolder' = '.github/workflows'; 'filter' = 'PushPowerPlatformChanges.yaml' } + [ordered]@{ 'sourceFolder' = '.github/workflows'; 'filter' = 'PullPowerPlatformChanges.yaml' } + ) + } + + if ($settings.Keys -notcontains 'CodeReviewAgent' -or !$settings['CodeReviewAgent']['enabled']) { + $filesToExclude += @( + [ordered]@{ 'sourceFolder' = '.github/workflows'; 'filter' = 'CopilotPRReview.yaml' } + [ordered]@{ 'sourceFolder' = '.github/workflows'; 'filter' = 'CopilotPRReviewRunner.yaml' } + ) + } + + return @($filesToExclude) +} + +<# +.SYNOPSIS + Get the list of files from the template repository to include and exclude based on the provided settings. +.DESCRIPTION + Builds two lists by merging defaults, repository settings, and the original AL-Go template (if given): + + 1. filesToInclude: Files to copy from the template or original template to the destination. + Built from default files to include and customALGoFiles.filesToInclude in settings, resolved against the template folder and original template folder (if any). + 2. filesToExclude: Files to skip from copying; if they already exist in the destination they should be deleted. + Built from default files to exclude and customALGoFiles.filesToExclude in settings, resolved against the template folder and original template folder (if any). + + Note: when a custom template is in use, the caller must refresh the custom template settings + snapshot files and re-read settings with ReadSettings before calling this function, so that the + template's customALGoFiles/unusedALGoSystemFiles are already merged into settings. + + The deprecated unusedALGoSystemFiles setting is also applied: matching files are moved from filesToInclude to + filesToExclude with a deprecation warning. +.PARAMETER settings + The settings object containing the customALGoFiles configuration. +.PARAMETER baseFolder + The base folder of the repository. This is the target folder where the files will be updated. +.PARAMETER templateFolder + The folder where the template files are located. +.PARAMETER originalTemplateFolder + The folder where the original AL-Go template files are located (if any). + When provided, it signals that a custom template is in use. Both filesToInclude and filesToExclude specs are + resolved against this folder in addition to templateFolder, and all original-template matches are appended. + Exclusion rules are applied before keeping the first eligible match per destination, with templateFolder + matches preceding originalTemplateFolder matches. +.PARAMETER projects + The list of projects in the repository. + The projects are used to resolve per-project files. +.OUTPUTS + An array containing two elements: the list of files to include and the list of files to exclude. + Files are represented as hashtables with the following keys: + - sourceFullPath: The full path to the source file. + - originalSourceFullPath: The full path to the original source file in the original template repository (if any). + - type: The type of the file (e.g., workflow, settings). + - destinationFullPath: The full path to the destination file in the target repository. +#> +function GetFilesToUpdate { + Param( + [Parameter(Mandatory=$true)] + $settings, + [Parameter(Mandatory=$true)] + $baseFolder, + [Parameter(Mandatory=$true)] + $templateFolder, + $originalTemplateFolder = $null, + $projects = @() + ) + + $hasOriginalTemplate = $null -ne $originalTemplateFolder + Write-Host "Getting files to update from template folder '$templateFolder', original template folder '$originalTemplateFolder' and base folder '$baseFolder'" + + # Send telemetery about customALGoFiles usage + if ($settings.customALGoFiles.filesToInclude.Count -gt 0) { + Trace-Information -Message "Usage: Custom AL-Go Files (Include)" + } + if ($settings.customALGoFiles.filesToExclude.Count -gt 0) { + Trace-Information -Message "Usage: Custom AL-Go Files (Exclude)" + } + + $pathComparer = GetPathStringComparer + + # Determine files to include + $filesToIncludeUnresolved = GetDefaultFilesToInclude -includeCustomTemplateFiles:$hasOriginalTemplate + $filesToIncludeUnresolved += $settings.customALGoFiles.filesToInclude + $filesToInclude = @(ResolveFilePaths -sourceFolder $templateFolder -originalSourceFolder $originalTemplateFolder -destinationFolder $baseFolder -files $filesToIncludeUnresolved -projects $projects) + if ($hasOriginalTemplate) { + $filesToInclude += @(ResolveFilePaths -sourceFolder $originalTemplateFolder -destinationFolder $baseFolder -files $filesToIncludeUnresolved -projects $projects) + } + + # Determine files to exclude + $filesToExcludeUnresolved = GetDefaultFilesToExclude -settings $settings + $filesToExcludeUnresolved += $settings.customALGoFiles.filesToExclude + $filesToExclude = @(ResolveFilePaths -sourceFolder $templateFolder -originalSourceFolder $originalTemplateFolder -destinationFolder $baseFolder -files $filesToExcludeUnresolved -projects $projects) + if ($hasOriginalTemplate) { + $filesToExclude += @(ResolveFilePaths -sourceFolder $originalTemplateFolder -destinationFolder $baseFolder -files $filesToExcludeUnresolved -projects $projects) + } + + # Map files from filesToExclude to files that are in filesToInclude (based on source) + # Settings for filesToExclude only define the sources (sourceFolder and filter) but not the destinations (destinationFolder, destinationName and perProject) + $filesToExclude = @($filesToInclude | Where-Object { + $fileToInclude = $_ + return $filesToExclude | Where-Object { $pathComparer.Equals($_.sourceFullPath, $fileToInclude.sourceFullPath) } + }) + + # Exclude files from filesToInclude that are in filesToExclude (based on source) + $filesToInclude = @($filesToInclude | Where-Object { + $file = $_ + $include = -not ($filesToExclude | Where-Object { $pathComparer.Equals($_.sourceFullPath, $file.sourceFullPath) }) + if (-not $include) { OutputDebug "Excluding source file '$($file.sourceFullPath)' from include list as it is in the exclude list" } + return $include + }) + + # Apply unusedALGoSystemFiles logic + $unusedALGoSystemFiles = $settings.unusedALGoSystemFiles + + # Exclude unusedALGoSystemFiles from $filesToInclude and add them to $filesToExclude + $unusedFilesToExclude = $filesToInclude | Where-Object { $unusedALGoSystemFiles -contains (Split-Path -Path $_.sourceFullPath -Leaf) } + if ($unusedFilesToExclude) { + Trace-DeprecationWarning "The 'unusedALGoSystemFiles' setting is deprecated and will be removed in future versions." -DeprecationTag "unusedALGoSystemFiles" + + OutputDebug "The following files are marked as unused and will be removed if they exist:" + $unusedFilesToExclude | ForEach-Object { OutputDebug "- $($_.destinationFullPath)" } + + $filesToInclude = @($filesToInclude | Where-Object { $unusedALGoSystemFiles -notcontains (Split-Path -Path $_.sourceFullPath -Leaf) }) + $filesToExclude += @($unusedFilesToExclude) + } + + # Deduplicate files to include based on destinationFullPath, keeping the first one (default > settings; template folder > original template folder) + $filesToIncludeDestinationFullPaths = [System.Collections.Generic.HashSet[string]]::new($pathComparer) + $filesToInclude = @($filesToInclude | Where-Object { + $include = $filesToIncludeDestinationFullPaths.Add($_.destinationFullPath) + if (-not $include) { OutputDebug "Skipping duplicate file to include '$($_.sourceFullPath)': destinationFullPath '$($_.destinationFullPath)' already included" } + return $include + }) + + # Exclude files from filesToExclude that are still included in filesToInclude based on destinationFullPath + $filesToExclude = @($filesToExclude | Where-Object { + $exclude = -not $filesToIncludeDestinationFullPaths.Contains($_.destinationFullPath) + if (-not $exclude) { OutputDebug "Skipping file to exclude '$($_.sourceFullPath)': destinationFullPath '$($_.destinationFullPath)' included with different source" } + return $exclude + }) + # Deduplicate files to exclude based on destinationFullPath, keeping the first one (default > settings; template folder > original template folder) + $filesToExcludeDestinationFullPaths = [System.Collections.Generic.HashSet[string]]::new($pathComparer) + $filesToExclude = @($filesToExclude | Where-Object { + $exclude = $filesToExcludeDestinationFullPaths.Add($_.destinationFullPath) + if (-not $exclude) { OutputDebug "Skipping duplicate file to exclude '$($_.sourceFullPath)': destinationFullPath '$($_.destinationFullPath)' already excluded" } + return $exclude + }) + + # List all files to be included and excluded with their source and destination paths, type and original source path (if any) + $fileFormatter = { param($file) " -Source: $($file.sourceFullPath), Destination: $($file.destinationFullPath), Type: $($file.type), Original Source: $($file.originalSourceFullPath)"} + OutputArray -Message "Files to include: $($filesToInclude.Count)" -Array $filesToInclude -Formatter $fileFormatter + OutputArray -Message "Files to exclude: $($filesToExclude.Count)" -Array $filesToExclude -Formatter $fileFormatter + + return @($filesToInclude), @($filesToExclude) +} diff --git a/Actions/CheckForUpdates/CheckForUpdates.ps1 b/Actions/CheckForUpdates/CheckForUpdates.ps1 index df4fc1db14..574f54ebf5 100644 --- a/Actions/CheckForUpdates/CheckForUpdates.ps1 +++ b/Actions/CheckForUpdates/CheckForUpdates.ps1 @@ -1,4 +1,4 @@ -Param( +Param( [Parameter(HelpMessage = "The GitHub actor running the action", Mandatory = $false)] [string] $actor, [Parameter(HelpMessage = "Base64 encoded GhTokenWorkflow secret", Mandatory = $false)] @@ -51,8 +51,9 @@ if ($token) { # if $update is set to N, CheckForUpdates will only check for updates and output a warning if there are updates available # if $downloadLatest is set to true, CheckForUpdates will download the latest version of the template repository, else it will use the templateSha setting in the .github/AL-Go-Settings file -# Get Repo settings as a hashtable (do NOT read any specific project settings, nor any specific workflow, user or branch settings) -$repoSettings = ReadSettings -buildMode '' -project '' -workflowName '' -userName '' -branchName '' | ConvertTo-HashTable -recurse +# Get repo settings independent of the build, project, workflow, user, branch, and trigger running this update. +# Repository-scoped and unconditional settings still apply. +$repoSettings = ReadSettings -buildMode '' -project '' -workflowName '' -userName '' -branchName '' -trigger '' | ConvertTo-HashTable -recurse $templateSha = $repoSettings.templateSha # If templateUrl has changed, download latest version of the template repository (ignore templateSha) @@ -61,17 +62,23 @@ if ($repoSettings.templateUrl -ne $templateUrl -or $templateSha -eq '') { } $originalTemplateFolder = $null -$templateFolder = DownloadTemplateRepository -token $token -templateUrl $templateUrl -templateSha ([ref]$templateSha) -downloadLatest $downloadLatest -$templateFolder = GetSrcFolder -repoType $repoSettings.type -templateUrl $templateUrl -templateFolder $templateFolder +$templateDownloadFolder = DownloadTemplateRepository -token $token -templateUrl $templateUrl -templateSha ([ref]$templateSha) -downloadLatest $downloadLatest +$templateFolder = GetSrcFolder -repoType $repoSettings.type -templateUrl $templateUrl -templateFolder $templateDownloadFolder Write-Host "Template Folder: $templateFolder" +Assert-PathPhysicallyEqual -Path $templateFolder -AnchorPaths @($templateDownloadFolder) -Context 'template folder' $templateBranch = $templateUrl.Split('@')[1] $templateOwner = $templateUrl.Split('/')[3] $templateInfo = "$templateOwner/$($templateUrl.Split('/')[4])" +$baseFolder = $ENV:GITHUB_WORKSPACE + +$customTemplateSnapshots = @() + $isDirectALGo = IsDirectALGo -templateUrl $templateUrl if (-not $isDirectALGo) { $templateRepoSettingsFile = Join-Path $templateFolder $RepoSettingsFile + Assert-PathPhysicallyEqual -Path $templateRepoSettingsFile -AnchorPaths @($templateFolder) -Context 'template repository settings' if (Test-Path -Path $templateRepoSettingsFile -PathType Leaf) { $templateRepoSettings = Get-Content $templateRepoSettingsFile -Encoding UTF8 | ConvertFrom-Json | ConvertTo-HashTable -Recurse if ($templateRepoSettings.Keys -contains "templateUrl" -and $templateRepoSettings.templateUrl -ne $templateUrl) { @@ -93,10 +100,11 @@ if (-not $isDirectALGo) { } # Download the "original" template repository - use downloadLatest if no TemplateSha is specified in the custom template repository - $originalTemplateFolder = DownloadTemplateRepository -token $token -templateUrl $originalTemplateUrl -templateSha ([ref]$originalTemplateSha) -downloadLatest ($originalTemplateSha -eq '') - $originalTemplateFolder = GetSrcFolder -repoType $repoSettings.type -templateUrl $originalTemplateUrl -templateFolder $originalTemplateFolder + $originalTemplateDownloadFolder = DownloadTemplateRepository -token $token -templateUrl $originalTemplateUrl -templateSha ([ref]$originalTemplateSha) -downloadLatest ($originalTemplateSha -eq '') + $originalTemplateFolder = GetSrcFolder -repoType $repoSettings.type -templateUrl $originalTemplateUrl -templateFolder $originalTemplateDownloadFolder Write-Host "Original Template Folder: $originalTemplateFolder" + Assert-PathPhysicallyEqual -Path $originalTemplateFolder -AnchorPaths @($originalTemplateDownloadFolder) -Context 'original template folder' # Set TemplateBranch and TemplateOwner # Keep TemplateUrl and TemplateSha pointing to the custom template repository @@ -107,109 +115,191 @@ if (-not $isDirectALGo) { if ($isDirectALGo) { Trace-Information -Message "Original template repository is direct AL-Go" } + + # Collect custom template snapshot files + $templateALGoSettingsFile = Join-Path $templateFolder $ALGoSettingsFile + $customTemplateSnapshots = @( + @{ src = $templateRepoSettingsFile; dst = Join-Path $baseFolder $CustomTemplateRepoSettingsFile; context = 'repository settings' }, + @{ src = $templateALGoSettingsFile; dst = Join-Path $baseFolder $CustomTemplateProjectSettingsFile; context = 'project settings' } + ) } } } -# Get the list of projects in the current repository -$baseFolder = $ENV:GITHUB_WORKSPACE -$projects = @(GetProjectsFromRepository -baseFolder $baseFolder -projectsFromSettings $repoSettings.projects) +$pathComparer = GetPathStringComparer +$backupFolder = NewTemporaryFolder +$backupFiles = [System.Collections.Generic.Dictionary[string, object]]::new($pathComparer) -$filesToInclude, $filesToExclude = GetFilesToUpdate -settings $repoSettings -projects $projects -baseFolder $baseFolder -templateFolder $templateFolder -originalTemplateFolder $originalTemplateFolder +try { + if ($customTemplateSnapshots) { + # Update custom template snapshot files + foreach ($customTemplateSnapshot in $customTemplateSnapshots) { + OutputDebug -Message "Updating custom template $($customTemplateSnapshot.context) snapshot file $($customTemplateSnapshot.dst) from $($customTemplateSnapshot.src)" -# $updateFiles will hold an array of files, which needs to be updated -$updateFiles = @() + $dst = Resolve-PathLexically -Path $customTemplateSnapshot.dst + $src = Resolve-PathLexically -Path $customTemplateSnapshot.src -# $removeFiles will hold an array of files, which needs to be removed -$removeFiles = @() + Assert-PathPhysicallyEqual -Path $src -AnchorPaths @($templateFolder) -Context "custom template $($customTemplateSnapshot.context) snapshot source file" + Assert-PathPhysicallyEqual -Path $dst -AnchorPaths @($baseFolder) -Context "custom template $($customTemplateSnapshot.context) snapshot destination file" -# Dependency depth determines how many build jobs we need to run sequentially -# Every build job might spin up multiple jobs in parallel to build the projects without unresolved deependencies -$depth = 1 -if ($projects.Count -gt 1) { - Import-Module (Join-Path -Path $PSScriptRoot -ChildPath "..\DetermineProjectsToBuild\DetermineProjectsToBuild.psm1" -Resolve) -DisableNameChecking - $allProjects, $modifiedProjects, $projectsToBuild, $projectDependencies, $buildOrder = Get-ProjectsToBuild -baseFolder $baseFolder -buildAllProjects $true -maxBuildDepth 100 - $depth = $buildOrder.Count - Write-Host "Calculated dependency depth to be $depth" -} + if (-not $backupFiles.ContainsKey($dst)) { + $dstBackupFile = $null + if (Test-Path -LiteralPath $dst -PathType Leaf) { + $dstBackupFile = Join-Path $backupFolder ([System.IO.Path]::GetRandomFileName()) + Copy-Item -LiteralPath $dst -Destination $dstBackupFile -Force + } + $backupFiles[$dst] = $dstBackupFile + } + + if (Test-Path -LiteralPath $src -PathType Leaf) { + Copy-Item -LiteralPath $src -Destination $dst -Force + } + } -# Loop through all folders in CheckFiles and check if there are any files that needs to be updated -foreach($fileToInclude in $filesToInclude) { - $type = $fileToInclude.type - $srcPath = $fileToInclude.sourceFullPath - $originalSrcPath = $fileToInclude.originalSourceFullPath - if(-not $originalSrcPath) { - $originalSrcPath = $srcPath + # Re-read repository settings after updating custom template snapshot files + $repoSettings = ReadSettings -buildMode '' -project '' -workflowName '' -userName '' -branchName '' -trigger '' | ConvertTo-HashTable -recurse } - $dstPath = $fileToInclude.destinationFullPath + # Get the list of projects in the current repository + $projects = @(GetProjectsFromRepository -baseFolder $baseFolder -projectsFromSettings $repoSettings.projects) + + $filesToInclude, $filesToExclude = GetFilesToUpdate -settings $repoSettings -projects $projects -baseFolder $baseFolder -templateFolder $templateFolder -originalTemplateFolder $originalTemplateFolder - $dstFileExists = Test-Path -Path $dstPath -PathType Leaf + # $updateFiles will hold an array of files, which needs to be updated + $updateFiles = @() - Write-Host "Processing file: $srcPath -> $dstPath (type: $type)" + # $removeFiles will hold an array of files, which needs to be removed + $removeFiles = @() - switch ($type) { - "workflow" { - # For workflow files, we might need to modify the file based on the settings - $srcContent = GetWorkflowContentWithChangesFromSettings -srcFile $originalSrcPath -repoSettings $repoSettings -depth $depth - # Replace static placeholders - $srcContent = $srcContent.Replace('{TEMPLATEURL}', $templateUrl) + # Dependency depth determines how many build jobs we need to run sequentially + # Every build job might spin up multiple jobs in parallel to build the projects without unresolved deependencies + $depth = 1 + if ($projects.Count -gt 1) { + Import-Module (Join-Path -Path $PSScriptRoot -ChildPath "..\DetermineProjectsToBuild\DetermineProjectsToBuild.psm1" -Resolve) -DisableNameChecking + $allProjects, $modifiedProjects, $projectsToBuild, $projectDependencies, $buildOrder = Get-ProjectsToBuild -baseFolder $baseFolder -buildAllProjects $true -maxBuildDepth 100 -settings $repoSettings + $depth = $buildOrder.Count + Write-Host "Calculated dependency depth to be $depth" + } + + # Prepare the list of template folders to be used for verification + $templateFolders = @($templateFolder) + if ($originalTemplateFolder) { + $templateFolders += $originalTemplateFolder + } + + # Loop through all folders in CheckFiles and check if there are any files that needs to be updated + foreach($fileToInclude in $filesToInclude) { + $type = $fileToInclude.type + $srcPath = $fileToInclude.sourceFullPath + $originalSrcPath = $fileToInclude.originalSourceFullPath + if(-not $originalSrcPath) { + $originalSrcPath = $srcPath } - "settings" { - # For settings files, we need to modify the file based on the settings - $srcContent = GetModifiedSettingsContent -srcSettingsFile $originalSrcPath -dstSettingsFile $dstPath + $hasDistinctOriginalSource = -not $pathComparer.Equals($originalSrcPath, $srcPath) + + Assert-PathPhysicallyEqual -Path $srcPath -AnchorPaths $templateFolders -Context 'source file' + if ($hasDistinctOriginalSource) { + Assert-PathPhysicallyEqual -Path $originalSrcPath -AnchorPaths $templateFolders -Context 'original source file' } - Default { - # For non-workflow files, just read the file content - $srcContent = Get-ContentLF -Path $originalSrcPath + + $dstPath = $fileToInclude.destinationFullPath + + Assert-PathPhysicallyEqual -Path $dstPath -AnchorPaths @($baseFolder) -Context 'destination file' + + if ($backupFiles.ContainsKey($dstPath)) { + $dstFileExists = $null -ne $backupFiles[$dstPath] + } else { + $dstFileExists = Test-Path -LiteralPath $dstPath -PathType Leaf } - } - if ($isDirectALGo) { - # If we are using direct AL-Go repo, we need to change the owner to the templateOwner, the repo names to AL-Go and AL-Go/Actions and the branch to templateBranch - ReplaceOwnerRepoAndBranch -srcContent ([ref]$srcContent) -templateOwner $templateOwner -templateBranch $templateBranch - } + Write-Host "Processing file: $srcPath -> $dstPath (type: $type)" - if ($type -eq 'workflow' -and $originalSrcPath -ne $srcPath) { - # Apply customizations from custom template repository - Write-Host "Apply customizations from custom template repository, file: $srcPath" - [Yaml]::ApplyTemplateCustomizations([ref] $srcContent, $srcPath) - } + switch ($type) { + "workflow" { + # For workflow files, we might need to modify the file based on the settings + $srcContent = GetWorkflowContentWithChangesFromSettings -srcFile $originalSrcPath -repoSettings $repoSettings -depth $depth + # Replace static placeholders + $srcContent = $srcContent.Replace('{TEMPLATEURL}', $templateUrl) + } + "settings" { + # For settings files, we need to modify the file based on the settings + $srcContent = GetModifiedSettingsContent -srcSettingsFile $originalSrcPath -dstSettingsFile $dstPath + } + Default { + # For non-workflow files, just read the file content + $srcContent = Get-ContentLF -Path $originalSrcPath + } + } - # Get the relative path for the dstPath from the base folder. Don't use Resolve-Path as it will fail if the destination file doesn't exist - $relativeDstPath = $dstPath.Substring($baseFolder.Length + 1) + if ($isDirectALGo) { + # If we are using direct AL-Go repo, we need to change the owner to the templateOwner, the repo names to AL-Go and AL-Go/Actions and the branch to templateBranch + ReplaceOwnerRepoAndBranch -srcContent ([ref]$srcContent) -templateOwner $templateOwner -templateBranch $templateBranch + } - if ($dstFileExists) { - if ($type -eq 'workflow') { - Write-Host "Apply customizations from current repository, file: $relativeDstPath" - [Yaml]::ApplyFinalCustomizations([ref] $srcContent, $dstPath) + if ($type -eq 'workflow' -and $hasDistinctOriginalSource) { + # Apply customizations from custom template repository + Write-Host "Apply customizations from custom template repository, file: $srcPath" + [Yaml]::ApplyTemplateCustomizations([ref] $srcContent, $srcPath) } - # file exists, compare and add to $updateFiles if different - $dstContent = Get-ContentLF -Path $dstPath - if ($dstContent -cne $srcContent) { - Write-Host "Available updates for file $relativeDstPath" - $updateFiles += @{ "DstFile" = $relativeDstPath; "content" = $srcContent } + # Get the relative path for the dstPath from the base folder. Don't use Resolve-Path as it will fail if the destination file doesn't exist + $relativeDstPath = $dstPath.Substring($baseFolder.Length + 1) + + if ($dstFileExists) { + if ($type -eq 'workflow') { + Write-Host "Apply customizations from current repository, file: $relativeDstPath" + [Yaml]::ApplyFinalCustomizations([ref] $srcContent, $dstPath) + } + + # file exists, compare and add to $updateFiles if different + if ($backupFiles.ContainsKey($dstPath)) { + $dstContent = Get-ContentLF -Path $backupFiles[$dstPath] + } else { + $dstContent = Get-ContentLF -Path $dstPath + } + if ($dstContent -cne $srcContent) { + Write-Host "Available updates for file $relativeDstPath" + $updateFiles += @{ "DstFile" = $relativeDstPath; "content" = $srcContent } + } + else { + Write-Host "No updates for file $relativeDstPath" + } } else { - Write-Host "No updates for file $relativeDstPath" + # new file, add to $updateFiles + Write-Host "New file available: $relativeDstPath" + $updateFiles += @{ "DstFile" = $relativeDstPath; "content" = $srcContent } } } - else { - # new file, add to $updateFiles - Write-Host "New file available: $relativeDstPath" - $updateFiles += @{ "DstFile" = $relativeDstPath; "content" = $srcContent } + + Push-Location -Path $baseFolder + # Remove files that are in $filesToExclude and exist in the repository + $removeFiles = $filesToExclude | Where-Object { $_ } | Where-Object { + $dstPath = $_.destinationFullPath + Assert-PathPhysicallyEqual -Path $dstPath -AnchorPaths @($baseFolder) -Context 'destination file' + if ($backupFiles.ContainsKey($dstPath)) { + return $null -ne $backupFiles[$dstPath] + } + return Test-Path -LiteralPath $dstPath -PathType Leaf + } | ForEach-Object { + $relativePath = Resolve-Path -LiteralPath $_.destinationFullPath -Relative + Write-Host "File marked for removal: $relativePath" + $relativePath } -} + Pop-Location -Push-Location -Path $baseFolder -# Remove files that are in $filesToExclude and exist in the repository -$removeFiles = $filesToExclude | Where-Object { $_ -and (Test-Path -Path $_.destinationFullPath -PathType Leaf) } | ForEach-Object { - $relativePath = Resolve-Path -Path $_.destinationFullPath -Relative - Write-Host "File marked for removal: $relativePath" - $relativePath } -Pop-Location +finally { + foreach ($backupFileEntry in $backupFiles.GetEnumerator()) { + if ($null -ne $backupFileEntry.Value) { + Copy-Item -LiteralPath $backupFileEntry.Value -Destination $backupFileEntry.Key -Force + } + elseif (Test-Path -LiteralPath $backupFileEntry.Key -PathType Leaf) { + Remove-Item -LiteralPath $backupFileEntry.Key -Force + } + } + Remove-Item -LiteralPath $backupFolder -Recurse -Force +} if ($update -ne 'Y') { # $update not set, just issue a warning in the CI/CD workflow that updates are available @@ -256,16 +346,22 @@ else { invoke-git status + $dstRoot = (Get-Location).Path + $dstRepoSettingsFile = Join-Path $dstRoot $RepoSettingsFile + Assert-PathPhysicallyEqual -Path $dstRepoSettingsFile -AnchorPaths @($dstRoot) -Context 'repository settings' + # Update the files # Calculate the release notes, while updating $releaseNotes = "" $updateFiles | ForEach-Object { + Assert-PathPhysicallyEqual -Path (Join-Path $dstRoot $_.DstFile) -AnchorPaths @($dstRoot) -Context 'destination file' + # Create the destination folder if it doesn't exist $path = [System.IO.Path]::GetDirectoryName($_.DstFile) - if ($path -and -not (Test-Path -path $path -PathType Container)) { + if ($path -and -not (Test-Path -LiteralPath $path -PathType Container)) { New-Item -Path $path -ItemType Directory | Out-Null } - if (([System.IO.Path]::GetFileName($_.DstFile) -eq "RELEASENOTES.copy.md") -and (Test-Path $_.DstFile)) { + if (([System.IO.Path]::GetFileName($_.DstFile) -eq "RELEASENOTES.copy.md") -and (Test-Path -LiteralPath $_.DstFile)) { # Read the release notes of the version currently installed $oldReleaseNotes = Get-ContentLF -Path $_.DstFile # Get the release notes of the new version (for the PR body) @@ -287,12 +383,14 @@ else { $releaseNotes = "No release notes available!" } $removeFiles | ForEach-Object { + Assert-PathPhysicallyEqual -Path (Join-Path $dstRoot $_) -AnchorPaths @($dstRoot) -Context 'destination file' + Write-Host "Remove $_" - Remove-Item (Join-Path (Get-Location).Path $_) -Force + Remove-Item -LiteralPath $_ -Force } # Update the templateUrl and templateSha in the repo settings file - UpdateSettingsFile -settingsFile (Join-Path ".github" "AL-Go-Settings.json") -updateSettings @{ "templateUrl" = $templateUrl; "templateSha" = $templateSha } + UpdateSettingsFile -settingsFile $dstRepoSettingsFile -updateSettings @{ "templateUrl" = $templateUrl; "templateSha" = $templateSha } Write-Host "ReleaseNotes:" Write-Host $releaseNotes diff --git a/Actions/CheckForUpdates/yamlclass.ps1 b/Actions/CheckForUpdates/yamlclass.ps1 index 68ee7683f3..1a03a3464a 100644 --- a/Actions/CheckForUpdates/yamlclass.ps1 +++ b/Actions/CheckForUpdates/yamlclass.ps1 @@ -19,7 +19,7 @@ class Yaml { # Static load function to load a Yaml file into a Yaml class static [Yaml] Load([string] $filename) { - $fileContent = Get-Content -Path $filename -Encoding UTF8 + $fileContent = Get-Content -LiteralPath $filename -Encoding UTF8 return [Yaml]::new($fileContent) } diff --git a/Actions/DetermineProjectsToBuild/DetermineProjectsToBuild.psm1 b/Actions/DetermineProjectsToBuild/DetermineProjectsToBuild.psm1 index 6fadd85c18..f514036112 100644 --- a/Actions/DetermineProjectsToBuild/DetermineProjectsToBuild.psm1 +++ b/Actions/DetermineProjectsToBuild/DetermineProjectsToBuild.psm1 @@ -143,6 +143,9 @@ function CreateBuildDimensions { Analyzes a folder for AL-Go projects and determines the build order of these projects. The build order is determined by the project dependencies and the projects that have been modified. +.Parameter settings + Settings used to select projects. Defaults to the deserialized Settings environment variable. + .Outputs The function returns the following values: - projects: An array of all projects found in the folder @@ -165,7 +168,9 @@ function Get-ProjectsToBuild { [Parameter(HelpMessage = "An array of changed files paths, used to filter the projects to build", Mandatory = $false)] [string[]] $modifiedFiles = @(), [Parameter(HelpMessage = "The maximum depth to build the dependency tree", Mandatory = $false)] - [int] $maxBuildDepth = 0 + [int] $maxBuildDepth = 0, + [Parameter(HelpMessage = "Settings used to select projects", Mandatory = $false)] + [hashtable] $settings = ($env:Settings | ConvertFrom-Json | ConvertTo-HashTable -recurse) ) . (Join-Path -Path $PSScriptRoot -ChildPath "..\AL-Go-Helper.ps1" -Resolve) @@ -174,7 +179,6 @@ function Get-ProjectsToBuild { Push-Location $baseFolder try { - $settings = $env:Settings | ConvertFrom-Json $projects = @(GetProjectsFromRepository -baseFolder $baseFolder -projectsFromSettings $settings.projects) Write-Host "Found AL-Go Projects: $($projects -join ', ')" diff --git a/Actions/Github-Helper.psm1 b/Actions/Github-Helper.psm1 index 5bbb50f232..d68f72e404 100644 --- a/Actions/Github-Helper.psm1 +++ b/Actions/Github-Helper.psm1 @@ -857,7 +857,7 @@ function Get-ContentLF { ) Process { - (Get-Content -Path $path -Encoding UTF8 -Raw).Replace("`r", "").TrimEnd("`n") + (Get-Content -LiteralPath $path -Encoding UTF8 -Raw).Replace("`r", "").TrimEnd("`n") } } diff --git a/RELEASENOTES.md b/RELEASENOTES.md index df0c250311..9135a2fec8 100644 --- a/RELEASENOTES.md +++ b/RELEASENOTES.md @@ -1,3 +1,16 @@ +### Improved file handling in Update AL-Go System Files + +- Update AL-Go System Files now uses the latest repository settings from a custom template, such as `customALGoFiles`, in the same update rather than applying them on the next run. + - Workflow dependency depth is also determined using these refreshed settings, ensuring enough sequential build jobs are generated for the configured projects. +- Default AL-Go file rules and `customALGoFiles.filesToInclude` now also resolve files from the original AL-Go template when they are absent from the custom template; `filesToExclude` applies to these files too. + - **Breaking change:** standard workflows or scripts intentionally deleted from a custom template can be recreated in consumer repositories. To keep them absent, add matching `customALGoFiles.filesToExclude` entries to the custom template's `.github/AL-Go-Settings.json` before updating consumers. +- `filesToExclude` now respects destination mappings from `filesToInclude`, including renamed files and per-project destinations. Existing files are removed unless another included source targets the same destination. +- Use `destinationName` in `filesToInclude` to rename included files at the destination. +- Update AL-Go System Files now ignores trigger-based conditional settings when selecting files and generating workflows, including during CI/CD update checks. +- For safety, the update validates selected source paths before reading file contents and destination paths before writing or removing files. These operations are blocked when a path redirects through a symbolic link or junction, or its physical location cannot be verified. + +See [Customizing AL-Go for GitHub](Scenarios/CustomizingALGoForGitHub.md#using-custom-template-files) for details. + ### Optional draft PR build skipping The new `skipDraftPullRequests` setting (default `false`) lets PTE and AppSource repositories skip AL-Go's built-in PR build jobs while a pull request is draft and build when it is marked ready for review. Custom jobs remain user-managed and are not modified. Default behavior and merge-queue builds are unchanged. Run **Update AL-Go System Files** after changing the setting. See [skipDraftPullRequests](Scenarios/settings.md#skipDraftPullRequests). diff --git a/Scenarios/CustomizingALGoForGitHub.md b/Scenarios/CustomizingALGoForGitHub.md index f5d80b24ad..6f20c86bea 100644 --- a/Scenarios/CustomizingALGoForGitHub.md +++ b/Scenarios/CustomizingALGoForGitHub.md @@ -235,13 +235,31 @@ In order to instruct AL-Go which files to look for at the template repository, y `filesToInclude`, as the name suggests, is an array of file configurations that will instruct AL-Go which files to include (create/update). Every item in the array may contain the following properties: -- `sourceFolder`: A path to a folder, relative to the template, where to look for files. If not specified the root folder is implied. `*` characters are not supported. _Example_: `src/scripts`. +- `sourceFolder`: A literal path to a folder, relative to the template, where to look for files. If not specified the root folder is implied. Wildcards are not supported; characters such as `[` and `]` are treated literally. _Example_: `src/scripts`. - `filter`: A string to use for filtering in the specified source path. It can contain `*` and `?` wildcards. _Example_: `*.ps1` or `fileToUpdate.ps1`. - `destinationFolder`: A path to a folder, relative to repository that is being updated, where the files should be placed. If not specified, defaults to the same as the source file folder. _Example_: `src/templateScripts`. - `perProject`: A boolean that indicates whether the matched files should be propagated for all available AL-Go projects. In that case, `destinationFolder` is relative to the project folder. _Example_: `.AL-Go/scripts`. +- `destinationName`: The filename to use at the destination. If specified, overrides the source filename, allowing the file to be renamed when copied. Should be used together with a `filter` that matches a single file. _Example_: `customScript.ps1`. > [!NOTE] -> `filesToInclude` is used to define all the template files that will be used by AL-Go for GitHub. If a template file is not matched, it will be ignored. Please pay attention, when changing the file configurations: there might be template files that were previously propagated to your repositories. In case these files are no longer matched via `filesToInclude`, AL-Go for GitHub will ignore them and you might have to remove them manually. +> `filesToInclude` is used to define all the template files that will be used by AL-Go for GitHub. If a template file is not matched, it will be ignored. Files propagated by an earlier configuration are not automatically removed when they are no longer matched. For example, changing `destinationName` creates or updates the new filename but leaves the old filename in the consumer repository; remove the old file manually if it is no longer needed. + +If multiple include rules target the same destination file, only the first eligible source is used. Custom template matches are considered before original template matches; within each template, default AL-Go file rules precede `customALGoFiles.filesToInclude` rules. A later rule with the same destination does not override the earlier one, including when `destinationName` creates the collision. + +When using a custom template repository, `filesToInclude` also resolves files from the **original** AL-Go template (i.e. the official [AL-Go-PTE](https://github.com/microsoft/AL-Go-PTE) or [AL-Go-AppSource](https://github.com/microsoft/AL-Go-AppSource) template). This means files present in the official AL-Go template that are not overridden by your custom template are still propagated to consumer repositories. When a file exists in both the original template and your custom template, how the file's **content** is resolved depends on the file's type: + +- **Workflow files** (`.github/workflows/*.yaml`/`*.yml`): the content is based on the original template's file, with customizations from your custom template's copy (see [Adding custom jobs](#adding-custom-jobs)) re-applied on top. +- **Settings files**: if the destination file already exists, its settings are preserved and only its `$schema` is updated from the original template. If it does not exist, the original template's settings are used. Current custom template repository settings are also read when updating workflows. +- **All other files** (e.g. PowerShell scripts, `.copy.md`, `.agent.md`): the original template's file content is used as-is; changes made to that same file in your custom template are not applied in this case. + +The following table summarizes how `filesToInclude` resolves files when a custom template is in use: + +| File is present in original template | File is present in custom template | File is matched by `filesToInclude` | Result | +|---|---|---|---| +| Yes | No | Yes | File from **original template** is propagated | +| No | Yes | Yes | File from **custom template** is propagated | +| Yes | Yes | Yes | File from **original template** is propagated; for Workflow files, customizations from the **custom template** are also applied | +| Yes/No | Yes/No | No | File is **ignored** | `filesToExclude` is an array of file configurations that will instruct AL-Go which files to exclude (remove) from `filesToInclude`. Every item in the array may contain the following properties: @@ -249,17 +267,22 @@ In order to instruct AL-Go which files to look for at the template repository, y - `filter`: A string to use for filtering in the specified source path. It can contain `*` and `?` wildcards. _Example_: `notRelevantScript.ps1` or `*-internal.ps1` > [!NOTE] `filesToExclude` is an array of file configurations already included in `filesToInclude`. These files are specifically marked to be excluded from the update process. -> This mechanism allows for fine-grained control over which files are propagated to the end repository and which should be explicitly removed, ensuring that unwanted files are not carried forward during updates. +> Exclusions match source files, not destination filenames. If another included source targets the same destination, it is updated from that source instead of being removed. Exclusion rules can only match files still present in the custom or original template; removing a file from both templates does not make an existing consumer copy eligible for automatic removal. + +> [!TIP] +> When using a custom template repository, you can use `filesToExclude` in the custom template's settings to prevent files from the original AL-Go template from being propagated to consumer repos. For example, if the original template includes a workflow you don't want in your consumer repos, adding it to `filesToExclude` in your custom template's settings will remove it during the next update, provided no other included source targets the same destination. The following table summarizes how AL-Go for GitHub manages file updates and exclusions when using custom template files. Say, there is a file (e.g. `file.ps1`) in the template repository. | File is present in end repo | File is matched by `filesToInclude` | File is matched by `filesToExclude` | Result | |---|---|---|---| | Yes/No | Yes | No | The file is **updated/created** in the end repo | -| Yes | Yes | Yes | The file is **removed** from the end repo, as it's matched for exclusion | -| Yes | No | Yes | The files is **_not_** removed as it was not matched as update | +| Yes | Yes | Yes | The file is **removed** from the end repo if no other included source targets the same destination; otherwise that source updates it | +| Yes | No | Yes | The file is **_not_** removed as it was not matched as update | | No | Yes/No | Yes | The file is **_not_ created** in the end repo, as it's matched for exclusion | +For safety, files managed by Update AL-Go System Files must not use paths redirected through symlinks or junctions. Such paths cause update checks and updates to fail with an error. + ### Examples of using custom template files Below are examples of how to use the `filesToInclude` and `filesToExclude` settings in your AL-Go configuration. diff --git a/Scenarios/settings.md b/Scenarios/settings.md index f3b5fe7629..89180d7ee7 100644 --- a/Scenarios/settings.md +++ b/Scenarios/settings.md @@ -195,6 +195,8 @@ to your [project settings file](#where-are-the-settings-located) will ensure tha - **users** settings will be applied for users matching the patterns - **triggers** settings will be applied when `GITHUB_EVENT_NAME` matches values (for example `push`, `pull_request`, `schedule`, `workflow_dispatch`) +When updating AL-Go System Files, settings for selecting files are read without a build mode, project, workflow, user, branch, or trigger context. When generating each workflow, settings are read again with that workflow's name, so workflow-specific settings and conditions on that workflow apply. Neither read uses the event that triggered the update. Unconditional settings and conditions matching the repository still apply; conditions on other execution contexts do not apply. + **Note:** You can use `workflowDefaultInputs` within conditional settings to apply workflow input defaults only when certain conditions are met. For example, you could set different default values for specific workflows or branches. You could imagine that you could have an organizational settings variable containing: @@ -258,7 +260,7 @@ Please read the release notes carefully when installing new versions of AL-Go fo | BcContainerHelperVersion | This setting can be set to a specific version (ex. 3.0.8) of BcContainerHelper to force AL-Go to use this version. **latest** means that AL-Go will use the latest released version. **preview** means that AL-Go will use the latest preview version. **dev** means that AL-Go will use the dev branch of containerhelper. | latest (or preview for AL-Go preview) | | unusedALGoSystemFiles (**deprecated**) | An array of AL-Go System Files, which won't be updated during Update AL-Go System Files. They will instead be removed.
Use this setting with care, as this can break the AL-Go for GitHub functionality and potentially leave your repo no longer functional. | [ ] | | reportSuppressedDiagnostics | If this setting is set to true, the AL compiler will report diagnostics which are suppressed in the code using the pragma `#pragma warning disable `. This can be useful if you want to ensure that no warnings are suppressed in your code. | false | -| customALGoFiles | An object to configure custom AL-Go files, that will be updated during "Update AL-Go System Files" workflow. The object can contain properties `filesToInclude` and `filesToExclude`. Read more at [Customizing AL-Go](CustomizingALGoForGitHub.md#Using-custom-template-files). | `{ "filesToInclude": [], "filesToExclude": [] }` +| customALGoFiles | An object to configure custom AL-Go files, that will be updated during "Update AL-Go System Files" workflow. Read more at [Customizing AL-Go](CustomizingALGoForGitHub.md#Using-custom-template-files).
**filesToInclude** = an array of file specifications to include (create/update). Each item can contain **sourceFolder** (folder relative to the template root to look for files, default root folder), **filter** (filter string supporting `*` and `?` wildcards, default all files), **destinationFolder** (folder relative to the repository to place the files, default same as sourceFolder), **destinationName** (filename to use at the destination, overriding the source filename to rename the file when copied; should be used together with a filter matching a single file, default source filename), and **perProject** (boolean indicating whether the files should be propagated to all AL-Go projects, in which case destinationFolder is relative to the project folder, default false).
**filesToExclude** = an array of file specifications to exclude (remove) from `filesToInclude`. Each item can contain **sourceFolder** and **filter** (same meaning as above). | `{ "filesToInclude": [], "filesToExclude": [] }` ## Settings sources in workflow logs diff --git a/Tests/CheckForUpdates.Action.Test.ps1 b/Tests/CheckForUpdates.Action.Test.ps1 index ab57f70384..1c5e4497f6 100644 --- a/Tests/CheckForUpdates.Action.Test.ps1 +++ b/Tests/CheckForUpdates.Action.Test.ps1 @@ -4,6 +4,28 @@ Import-Module (Join-Path $PSScriptRoot "../Actions/TelemetryHelper.psm1") Import-Module (Join-Path $PSScriptRoot '../Actions/.Modules/ReadSettings.psm1') $errorActionPreference = "Stop"; $ProgressPreference = "SilentlyContinue"; Set-StrictMode -Version 2.0 +# Computed here (not in BeforeAll) because -Skip: expressions are evaluated at discovery time, and +# these variables are used by -Skip: expressions in Describe blocks throughout this file. +# $IsWindows doesn't exist in Windows PowerShell 5.1, which only ever runs on Windows anyway. +$script:isWindowsPlatform = ($PSVersionTable.PSVersion.Major -lt 6) -or $IsWindows +$script:isLinuxPlatform = ($PSVersionTable.PSVersion.Major -ge 6) -and $IsLinux + +# Determine if the runner has the capability to create symlinks +$script:hasSymlinkCapability = $true +if ($script:isWindowsPlatform) { + # Probe once whether this runner can create symlinks; Junctions never need this privilege, SymbolicLinks do + $probeLinkPath = Join-Path ([System.IO.Path]::GetTempPath()) ([Guid]::NewGuid().ToString()) + try { + New-Item -ItemType SymbolicLink -Path $probeLinkPath -Target $PSScriptRoot -ErrorAction Stop | Out-Null + } + catch { + $script:hasSymlinkCapability = $false + } + finally { + Remove-Item -Path $probeLinkPath -Recurse -Force -ErrorAction SilentlyContinue + } +} + Describe "CheckForUpdates Action Tests" { BeforeAll { $actionName = "CheckForUpdates" @@ -49,2579 +71,5261 @@ Describe "CheckForUpdates Action Tests" { } } -Describe "Test-HasSystemFileChanges" { +Describe "CheckForUpdates Action: runtime behavior" { BeforeAll { - $scriptRoot = Join-Path (Join-Path $PSScriptRoot '..') 'Actions' - . (Join-Path $scriptRoot 'AL-Go-Helper.ps1') - $scriptRoot = Join-Path $scriptRoot 'CheckForUpdates' - . (Join-Path $scriptRoot 'CheckForUpdates.HelperFunctions.ps1') + $actionName = "CheckForUpdates" + $scriptRoot = Join-Path $PSScriptRoot "..\Actions\$actionName" -Resolve + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'scriptPath', Justification = 'False positive.')] + $scriptPath = Join-Path $scriptRoot "$actionName.ps1" + . (Join-Path -Path $scriptRoot -ChildPath "..\AL-Go-Helper.ps1" -Resolve) + . (Join-Path -Path $scriptRoot -ChildPath "CheckForUpdates.HelperFunctions.ps1") + + $rootFolder = Join-Path $PSScriptRoot "checkForUpdatesRuntimeTests" + New-Item -Path $rootFolder -ItemType Directory -Force | Out-Null + } + + AfterAll { + Remove-Item -Path $rootFolder -Recurse -Force -ErrorAction SilentlyContinue } BeforeEach { - $settingsFile = Join-Path $TestDrive 'AL-Go-Settings.json' - $templateUrl = 'https://github.com/contoso/AL-Go@main' - $settings = @{ - templateUrl = $templateUrl - templateSha = 'old-sha' + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'originalGitHubWorkspace', Justification = 'False positive.')] + $originalGitHubWorkspace = $env:GITHUB_WORKSPACE + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'originalGitHubRepository', Justification = 'False positive.')] + $originalGitHubRepository = $env:GITHUB_REPOSITORY + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'originalGitHubServerUrl', Justification = 'False positive.')] + $originalGitHubServerUrl = $env:GITHUB_SERVER_URL + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'originalLocation', Justification = 'False positive.')] + $originalLocation = Get-Location + + $originalSettingsEnvironment = @{} + foreach ($variableName in @('ALGoOrgSettings', 'ALGoRepoSettings', 'ALGoEnvSettings')) { + $originalSettingsEnvironment[$variableName] = [Environment]::GetEnvironmentVariable($variableName) + [Environment]::SetEnvironmentVariable($variableName, $null) } - $settings | ConvertTo-Json | Set-Content $settingsFile -Encoding UTF8 - [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'parameters', Justification = 'Splatted into Test-HasSystemFileChanges in the It blocks.')] - $parameters = @{ - settingsFile = $settingsFile - templateUrl = $templateUrl - updateFiles = @() - removeFiles = @() + + $testRepoName = 'contoso/check-for-updates-runtime-tests' + + $testTemplateFolder = Join-Path $rootFolder 'template' + $testWorkspaceFolder = Join-Path $rootFolder 'workspace' + $testCloneRoot = Join-Path $rootFolder 'clone' + + $testSettings = @{ + templateSha = 'sha123456789' + templateUrl = 'https://github.com/microsoft/AL-Go-PTE@main' + type = 'PTE' + projects = @() + 'runs-on' = 'windows-latest' + shell = 'powershell' } + + $fakeToken = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes('fake-pat')) + + Mock DownloadAndImportBcContainerHelper {} + Mock DownloadTemplateRepository { return $testTemplateFolder } + Mock GetSrcFolder { return $testTemplateFolder } + Mock IsDirectALGo { return $true } + Mock GetProjectsFromRepository { return @('.') } + Mock OutputWarning {} + Mock OutputNotice {} + Mock RunAndCheck { return 'sha123456789' } + Mock invoke-git {} + Mock GetAccessToken { return $fakeToken } + Mock gh { '[]' } + Mock CloneIntoNewFolder { Set-Location -Path $testCloneRoot; "https://fake.example.com/$testRepoName.git"; 'update-al-go-system-files/branch' } + Mock CommitFromNewFolder { return $true } + Mock UpdateSettingsFile {} + + New-Item -Path $testTemplateFolder -ItemType Directory -Force | Out-Null + New-Item -Path $testWorkspaceFolder -ItemType Directory -Force | Out-Null + New-Item -Path $testCloneRoot -ItemType Directory -Force | Out-Null + + New-Item -Path (Join-Path $testWorkspaceFolder '.github') -ItemType Directory -Force | Out-Null + Set-Content -LiteralPath (Join-Path $testWorkspaceFolder $RepoSettingsFile) -Value ($testSettings | ConvertTo-Json -Depth 10 -Compress) -Encoding UTF8 + + Set-Location $testWorkspaceFolder + $env:GITHUB_WORKSPACE = $testWorkspaceFolder + $env:GITHUB_REPOSITORY = $testRepoName + $env:GITHUB_SERVER_URL = 'https://github.com' } - It 'Identifies a SHA-only update without modifying the settings file' { - $originalContent = [System.IO.File]::ReadAllBytes($settingsFile) - Test-HasSystemFileChanges @parameters | Should -BeFalse + AfterEach { + Set-Location $originalLocation + $env:GITHUB_WORKSPACE = $originalGitHubWorkspace + $env:GITHUB_REPOSITORY = $originalGitHubRepository + $env:GITHUB_SERVER_URL = $originalGitHubServerUrl - [System.Convert]::ToBase64String([System.IO.File]::ReadAllBytes($settingsFile)) | Should -Be ([System.Convert]::ToBase64String($originalContent)) + foreach ($variableName in $originalSettingsEnvironment.Keys) { + [Environment]::SetEnvironmentVariable($variableName, $originalSettingsEnvironment[$variableName]) + } + + if (Test-Path -LiteralPath $testTemplateFolder) { + Remove-Item -Path $testTemplateFolder -Recurse -Force + } + if (Test-Path -LiteralPath $testWorkspaceFolder) { + Remove-Item -Path $testWorkspaceFolder -Recurse -Force + } + if (Test-Path -LiteralPath $testCloneRoot) { + Remove-Item -Path $testCloneRoot -Recurse -Force + } } - It 'Does not skip updates when are pending' -TestCases @( - @{ change = 'file updates'; updateFiles = @(@{ DstFile = 'script.ps1'; content = 'new content' }); removeFiles = @() } - @{ change = 'file removals'; updateFiles = @(); removeFiles = @('obsolete.ps1') } - @{ change = 'settings updates'; updateFiles = @(@{ DstFile = '.github/AL-Go-Settings.json'; content = '{"doNotPerformUpgrade":true}' }); removeFiles = @() } - ) { - Param($change, $updateFiles, $removeFiles) + It 'Reads initial settings without execution-specific contexts' { + Mock ReadSettings { [PSCustomObject]$testSettings } + Mock GetFilesToUpdate { Write-Output @() -NoEnumerate; Write-Output @() -NoEnumerate } - $parameters.updateFiles = $updateFiles - $parameters.removeFiles = $removeFiles - Test-HasSystemFileChanges @parameters | Should -BeTrue -Because "$change must still be applied" + . $scriptPath -templateUrl $testSettings.templateUrl -downloadLatest $true -update N + + Should -Invoke ReadSettings -Exactly 1 -ParameterFilter { + $buildMode -ceq '' -and $project -ceq '' -and $workflowName -ceq '' -and + $userName -ceq '' -and $branchName -ceq '' -and $trigger -ceq '' -and + ($null -eq $repoName -or $repoName -ceq $env:GITHUB_REPOSITORY) + } } - It 'Does not skip a template URL or branch change' -TestCases @( - @{ newTemplateUrl = 'https://github.com/other/AL-Go@main' } - @{ newTemplateUrl = 'https://github.com/contoso/AL-Go@preview' } - ) { - Param($newTemplateUrl) + It 'Reads, updates and removes with literal bracketed paths' { + Mock GetFilesToUpdate { Write-Output $testFilesToInclude -NoEnumerate; Write-Output $testFilesToExclude -NoEnumerate } + $newSource = Join-Path $testTemplateFolder 'New[1].txt' + $newDestination = Join-Path $testWorkspaceFolder 'New[1].txt' + Set-Content -LiteralPath $newSource -Value 'new content' + Set-Content -LiteralPath (Join-Path $testTemplateFolder 'New1.txt') -Value 'wrong source' + Set-Content -LiteralPath (Join-Path $testWorkspaceFolder 'New1.txt') -Value 'wrong destination' + Set-Content -LiteralPath (Join-Path $testCloneRoot 'New1.txt') -Value 'keep me' + + $changedSource = Join-Path $testTemplateFolder 'Changed[1].txt' + $changedDestination = Join-Path $testWorkspaceFolder 'Changed[1].txt' + Set-Content -LiteralPath $changedSource -Value 'new content' + Set-Content -LiteralPath $changedDestination -Value 'old content' + Set-Content -LiteralPath (Join-Path $testTemplateFolder 'Changed1.txt') -Value 'wrong source' + Set-Content -LiteralPath (Join-Path $testWorkspaceFolder 'Changed1.txt') -Value 'wrong destination' + Set-Content -LiteralPath (Join-Path $testCloneRoot 'Changed[1].txt') -Value 'old content' + Set-Content -LiteralPath (Join-Path $testCloneRoot 'Changed1.txt') -Value 'keep me' + + $unchangedSource = Join-Path $testTemplateFolder 'Same[1].txt' + $unchangedDestination = Join-Path $testWorkspaceFolder 'Same[1].txt' + Set-Content -LiteralPath $unchangedSource -Value 'same content' + Set-Content -LiteralPath $unchangedDestination -Value 'same content' + Set-Content -LiteralPath (Join-Path $testTemplateFolder 'Same1.txt') -Value 'wrong source' + Set-Content -LiteralPath (Join-Path $testWorkspaceFolder 'Same1.txt') -Value 'wrong destination' + Set-Content -LiteralPath (Join-Path $testCloneRoot 'Same[1].txt') -Value 'same content' + Set-Content -LiteralPath (Join-Path $testCloneRoot 'Same1.txt') -Value 'keep me' + + $workflowSource = Join-Path $testTemplateFolder 'Workflow[1].yaml' + $workflowOriginalSource = Join-Path $testTemplateFolder 'WorkflowOriginal[1].yaml' + $workflowDestination = Join-Path $testWorkspaceFolder 'Workflow[1].yaml' + $workflowLines = @('jobs:', ' Build:', ' runs-on: [ windows-latest ]') + $workflowTemplateCustomJobLines = @(' CustomJob-Template:', ' runs-on: [ windows-latest ]') + $workflowDestinationCustomJobLines = @(' CustomJob-Destination:', ' runs-on: [ windows-latest ]') + Set-Content -LiteralPath $workflowSource -Value (@('name: Custom') + $workflowLines + $workflowTemplateCustomJobLines) + Set-Content -LiteralPath $workflowOriginalSource -Value (@('name: Original') + $workflowLines) + Set-Content -LiteralPath $workflowDestination -Value (@('name: Destination') + $workflowLines + $workflowDestinationCustomJobLines) + Set-Content -LiteralPath (Join-Path $testTemplateFolder 'Workflow1.yaml') -Value (@('name: Wrong custom') + $workflowLines) + Set-Content -LiteralPath (Join-Path $testTemplateFolder 'WorkflowOriginal1.yaml') -Value (@('name: Wrong original') + $workflowLines) + Set-Content -LiteralPath (Join-Path $testWorkspaceFolder 'Workflow1.yaml') -Value (@('name: Wrong destination') + $workflowLines) + Set-Content -LiteralPath (Join-Path $testCloneRoot 'Workflow[1].yaml') -Value (@('name: Old content') + $workflowLines) + Set-Content -LiteralPath (Join-Path $testCloneRoot 'Workflow1.yaml') -Value (@('name: Keep me') + $workflowLines) + + $excludedDestination = Join-Path $testWorkspaceFolder 'Old[1].txt' + Set-Content -LiteralPath $excludedDestination -Value 'remove me' + Set-Content -LiteralPath (Join-Path $testWorkspaceFolder 'Old1.txt') -Value 'keep me' + Set-Content -LiteralPath (Join-Path $testCloneRoot 'Old[1].txt') -Value 'remove me' + Set-Content -LiteralPath (Join-Path $testCloneRoot 'Old1.txt') -Value 'keep me' + + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'testFilesToInclude', Justification = 'False positive.')] + $testFilesToInclude = @( + @{ sourceFullPath = $newSource; originalSourceFullPath = $null; type = ''; destinationFullPath = $newDestination } + @{ sourceFullPath = $changedSource; originalSourceFullPath = $null; type = ''; destinationFullPath = $changedDestination } + @{ sourceFullPath = $unchangedSource; originalSourceFullPath = $null; type = ''; destinationFullPath = $unchangedDestination } + @{ sourceFullPath = $workflowSource; originalSourceFullPath = $workflowOriginalSource; type = 'workflow'; destinationFullPath = (Join-Path $testWorkspaceFolder 'Workflow[1].yaml') } + ) + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'testFilesToExclude', Justification = 'False positive.')] + $testFilesToExclude = @( + @{ destinationFullPath = $excludedDestination } + ) - $parameters.templateUrl = $newTemplateUrl - Test-HasSystemFileChanges @parameters | Should -BeTrue - } + . $scriptPath -templateUrl 'https://github.com/contoso/template@main' -downloadLatest $true -update Y -updateBranch 'update-al-go-system-files' -token $fakeToken -directCommit $true -actor 'test-actor' - It 'Does not skip initialization when is missing' -TestCases @( - @{ missingMetadata = 'templateUrl' } - @{ missingMetadata = 'templateSha' } - ) { - Param($missingMetadata) + $updateFiles.Count | Should -Be 3 + $updateFiles[0].DstFile | Should -Be 'New[1].txt' + $updateFiles[0].content | Should -Be 'new content' + $updateFiles[1].DstFile | Should -Be 'Changed[1].txt' + $updateFiles[1].content | Should -Be 'new content' + $updateFiles[2].DstFile | Should -Be 'Workflow[1].yaml' + $updateFiles[2].content | Should -Match '(?s)^name: Original.*CustomJob-Template:.*CustomJob-Destination:' + @($removeFiles).Count | Should -Be 1 + @($removeFiles)[0] | Should -Be (Join-Path '.' 'Old[1].txt') - $settings.Remove($missingMetadata) - $settings | ConvertTo-Json | Set-Content $settingsFile -Encoding UTF8 + Get-Content -LiteralPath (Join-Path $testCloneRoot 'New[1].txt') | Should -Be 'new content' + Get-Content -LiteralPath (Join-Path $testCloneRoot 'New1.txt') | Should -Be 'keep me' - Test-HasSystemFileChanges @parameters | Should -BeTrue - } + Get-Content -LiteralPath (Join-Path $testCloneRoot 'Changed[1].txt') | Should -Be 'new content' + Get-Content -LiteralPath (Join-Path $testCloneRoot 'Changed1.txt') | Should -Be 'keep me' - It 'Does not skip initialization when the repository settings file is missing' { - Remove-Item $settingsFile + Get-Content -LiteralPath (Join-Path $testCloneRoot 'Same[1].txt') | Should -Be 'same content' + Get-Content -LiteralPath (Join-Path $testCloneRoot 'Same1.txt') | Should -Be 'keep me' - Test-HasSystemFileChanges @parameters | Should -BeTrue + Get-Content -LiteralPath (Join-Path $testCloneRoot 'Workflow[1].yaml') -Raw | Should -Match '(?s)^name: Original.*CustomJob-Template:.*CustomJob-Destination:' + Get-Content -LiteralPath (Join-Path $testCloneRoot 'Workflow1.yaml') -Raw | Should -Match '^name: Keep me' + + Test-Path -LiteralPath (Join-Path $testCloneRoot 'Old[1].txt') | Should -BeFalse + Get-Content -LiteralPath (Join-Path $testCloneRoot 'Old1.txt') | Should -Be 'keep me' } - It 'Does not skip initialization when the recorded SHA is empty' { - $settings.templateSha = '' - $settings | ConvertTo-Json | Set-Content $settingsFile -Encoding UTF8 + It 'Applies workflow customizations from case-distinct original sources on Linux' -Skip:(-not $script:isLinuxPlatform) { + Mock GetFilesToUpdate { Write-Output $testFilesToInclude -NoEnumerate; Write-Output @() -NoEnumerate } + $workflowSource = Join-Path $testTemplateFolder 'Workflow.yaml' + $workflowOriginalSource = Join-Path $testTemplateFolder 'WORKFLOW.yaml' + Copy-Item -LiteralPath (Join-Path $PSScriptRoot 'CustomizedYamlSnippet-TemplateRepository.txt') -Destination $workflowSource + Copy-Item -LiteralPath (Join-Path $PSScriptRoot 'YamlSnippet.txt') -Destination $workflowOriginalSource - Test-HasSystemFileChanges @parameters | Should -BeTrue - } + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'testFilesToInclude', Justification = 'False positive.')] + $testFilesToInclude = @( + @{ sourceFullPath = $workflowSource; originalSourceFullPath = $workflowOriginalSource; type = 'workflow'; destinationFullPath = (Join-Path $testWorkspaceFolder 'Workflow.yaml') } + ) - It 'Reports invalid settings instead of treating them as a no-op' { - Set-Content $settingsFile -Value '{invalid json' -Encoding UTF8 + . $scriptPath -templateUrl 'https://github.com/contoso/template@main' -downloadLatest $true -update N - { Test-HasSystemFileChanges @parameters } | Should -Throw + Should -Invoke OutputWarning -Exactly 1 + Should -Invoke OutputWarning -Exactly 1 -ParameterFilter { $message -like '*There are updates for your AL-Go system*' } + $updateFiles.Count | Should -Be 1 + $updateFiles[0].DstFile | Should -Be 'Workflow.yaml' + $updateFiles[0].content | Should -Match 'CustomJob-MyCustomTemplateJob:' } -} -Describe "YamlClass Tests" { - BeforeAll { - $actionName = "CheckForUpdates" - [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'scriptRoot', Justification = 'False positive.')] - $scriptRoot = Join-Path $PSScriptRoot "..\Actions\$actionName" -Resolve + It 'Applies no workflow customizations from case-distinct original sources on Windows' -Skip:(-not $script:isWindowsPlatform) { + Mock GetFilesToUpdate { Write-Output $testFilesToInclude -NoEnumerate; Write-Output @() -NoEnumerate } + $workflowSource = Join-Path $testTemplateFolder 'Workflow.yaml' + $workflowOriginalSource = Join-Path $testTemplateFolder 'WORKFLOW.yaml' + Copy-Item -LiteralPath (Join-Path $PSScriptRoot 'CustomizedYamlSnippet-TemplateRepository.txt') -Destination $workflowSource + Copy-Item -LiteralPath (Join-Path $PSScriptRoot 'YamlSnippet.txt') -Destination $workflowOriginalSource - Mock Trace-Information {} + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'testFilesToInclude', Justification = 'False positive.')] + $testFilesToInclude = @( + @{ sourceFullPath = $workflowSource; originalSourceFullPath = $workflowOriginalSource; type = 'workflow'; destinationFullPath = (Join-Path $testWorkspaceFolder 'Workflow.yaml') } + ) + + . $scriptPath -templateUrl 'https://github.com/contoso/template@main' -downloadLatest $true -update N + + Should -Invoke OutputWarning -Exactly 1 + Should -Invoke OutputWarning -Exactly 1 -ParameterFilter { $message -like '*There are updates for your AL-Go system*' } + $updateFiles.Count | Should -Be 1 + $updateFiles[0].DstFile | Should -Be 'Workflow.yaml' + $updateFiles[0].content | Should -Not -Match 'CustomJob-MyCustomTemplateJob:' } - It 'Test YamlClass' { - . (Join-Path $scriptRoot "yamlclass.ps1") - $yaml = [Yaml]::load((Join-Path $PSScriptRoot 'YamlSnippet.txt')) + Context 'Physical path safety' { + BeforeEach { + $testFilesToInclude = @() + $testFilesToExclude = @() + Mock GetFilesToUpdate { Write-Output $testFilesToInclude -NoEnumerate; Write-Output $testFilesToExclude -NoEnumerate } + } - # Yaml file should have 77 entries - $yaml.content.Count | Should -be 74 + AfterEach { + $testLinkPaths = @( + (Join-Path $testTemplateFolder 'redirected') + (Join-Path $testTemplateFolder 'FOLDER') + (Join-Path $testTemplateFolder 'file.txt') + (Join-Path $testWorkspaceFolder 'redirectedInWorkspace') + (Join-Path $testCloneRoot 'redirectedInClone') + ) + foreach ($linkPath in $testLinkPaths) { + $linkItem = Get-Item -LiteralPath $linkPath -Force -ErrorAction SilentlyContinue + if ($linkItem -and $linkItem.LinkType -in @('Junction', 'SymbolicLink')) { + if ($linkItem.PSIsContainer) { + [System.IO.Directory]::Delete($linkPath) + } + else { + Remove-Item -LiteralPath $linkPath -Force + } + } + } + } - $start = 0; $count = 0 - # Locate lines for permissions section (including permissions: line) - $yaml.Find('permissions:', [ref] $start, [ref] $count) | Should -be $true - $start | Should -be 17 - $count | Should -be 5 + Context 'Template source folder redirects' { + BeforeAll { + $realGetSrcFolder = (Get-Item function:GetSrcFolder).ScriptBlock + } - # Locate lines for permissions section (excluding permissions: line) - $yaml.Find('permissions:/', [ref] $start, [ref] $count) | Should -be $true - $start | Should -be 18 - $count | Should -be 4 + BeforeEach { + $primaryDownloadFolder = Join-Path $TestDrive 'primaryDownload' + $primarySourceFolder = Join-Path $primaryDownloadFolder 'repo' + $originalDownloadFolder = Join-Path $TestDrive 'originalDownload' + $originalSourceFolder = Join-Path $originalDownloadFolder 'repo/Templates/Per Tenant Extension' + $externalTemplateFolder = Join-Path $TestDrive 'externalTemplate' + $rootLinkPath = '' + $workspaceSettingsHash = (Get-FileHash -LiteralPath (Join-Path $testWorkspaceFolder $RepoSettingsFile)).Hash + + New-Item -ItemType Directory -Path (Join-Path $primarySourceFolder '.github/workflows') -Force | Out-Null + New-Item -ItemType Directory -Path (Join-Path $originalSourceFolder '.github/workflows') -Force | Out-Null + + Mock GetSrcFolder { & $realGetSrcFolder -repoType $repoType -templateUrl $templateUrl -templateFolder $templateFolder -srcPath $srcPath } + Mock IsDirectALGo { return $templateUrl -like 'https://github.com/*/AL-Go@*' } + Mock DownloadTemplateRepository { return $primaryDownloadFolder } -ParameterFilter { $templateUrl -eq 'https://github.com/contoso/template@main' } + Mock DownloadTemplateRepository { return $originalDownloadFolder } -ParameterFilter { $templateUrl -eq 'https://github.com/contoso/AL-Go@main' } + } - # Get Yaml class for permissions section (excluding permissions: line) - $yaml.Get('permissions:/').content | ForEach-Object { $_ | Should -not -belike ' *' } + AfterEach { + if ($rootLinkPath) { + [System.IO.Directory]::Delete($rootLinkPath) + } + Remove-Item -LiteralPath $primaryDownloadFolder, $originalDownloadFolder, $externalTemplateFolder -Recurse -Force -ErrorAction SilentlyContinue + } - # Locate section called permissionos (should return false) - $yaml.Find('permissionos:', [ref] $start, [ref] $count) | Should -Not -be $true + It 'Rejects a primary template source folder redirected through a junction before selecting files' -Skip:(-not $script:isWindowsPlatform) { + Move-Item -LiteralPath $primarySourceFolder -Destination $externalTemplateFolder + New-Item -ItemType Junction -Path $primarySourceFolder -Target $externalTemplateFolder | Out-Null + $rootLinkPath = $primarySourceFolder - # Check checkout step - ($yaml.Get('jobs:/Initialization:/steps:/- name: Checkout').content -join '') | Should -be "- name: Checkout uses: actions/checkout@v4 with: lfs: true" + { . $scriptPath -templateUrl 'https://github.com/contoso/template@main' -downloadLatest $true -update N } | + Should -Throw -ExpectedMessage 'Unsafe path blocked: template folder *' - # Get Shell line in read Settings step - ($yaml.Get('jobs:/Initialization:/steps:/- name: Read settings/with:/shell:').content -join '') | Should -be "shell: powershell" + (Get-FileHash -LiteralPath (Join-Path $testWorkspaceFolder $RepoSettingsFile)).Hash | Should -Be $workspaceSettingsHash + Should -Invoke GetFilesToUpdate -Exactly 0 + Should -Invoke CloneIntoNewFolder -Exactly 0 + } - # Get Jobs section (without the jobs: line) - $jobsYaml = $yaml.Get('jobs:/') + It 'Rejects a primary template source folder redirected through a symlink before selecting files' -Skip:(-not $script:hasSymlinkCapability) { + Move-Item -LiteralPath $primarySourceFolder -Destination $externalTemplateFolder + New-Item -ItemType SymbolicLink -Path $primarySourceFolder -Target $externalTemplateFolder | Out-Null + $rootLinkPath = $primarySourceFolder - # Locate CheckForUpdates - $jobsYaml.Find('CheckForUpdates:', [ref] $start, [ref] $count) | Should -be $true - $start | Should -be 24 - $count | Should -be 19 + { . $scriptPath -templateUrl 'https://github.com/contoso/template@main' -downloadLatest $true -update N } | + Should -Throw -ExpectedMessage 'Unsafe path blocked: template folder *' - # Replace all occurances of 'shell: powershell' with 'shell: pwsh' - $yaml.ReplaceAll('shell: powershell', 'shell: pwsh') - $yaml.content[46].Trim() | Should -be 'shell: pwsh' + (Get-FileHash -LiteralPath (Join-Path $testWorkspaceFolder $RepoSettingsFile)).Hash | Should -Be $workspaceSettingsHash + Should -Invoke GetFilesToUpdate -Exactly 0 + Should -Invoke CloneIntoNewFolder -Exactly 0 + } - # Replace Permissions - $yaml.Replace('Permissions:/', @('contents: write', 'actions: read')) - $yaml.content[44].Trim() | Should -be 'shell: pwsh' - $yaml.content.Count | Should -be 72 + It 'Rejects an original template source folder redirected through a junction when using a custom template' -Skip:(-not $script:isWindowsPlatform) { + Set-Content -LiteralPath (Join-Path $primarySourceFolder $RepoSettingsFile) -Value '{"templateUrl":"https://github.com/contoso/AL-Go@main"}' -Encoding UTF8 + Move-Item -LiteralPath $originalSourceFolder -Destination $externalTemplateFolder + New-Item -ItemType Junction -Path $originalSourceFolder -Target $externalTemplateFolder | Out-Null + $rootLinkPath = $originalSourceFolder + + { . $scriptPath -templateUrl 'https://github.com/contoso/template@main' -downloadLatest $true -update N } | + Should -Throw -ExpectedMessage 'Unsafe path blocked: original template folder *' + + Should -Invoke DownloadTemplateRepository -Exactly 1 -ParameterFilter { $templateUrl -eq 'https://github.com/contoso/AL-Go@main' } + (Get-FileHash -LiteralPath (Join-Path $testWorkspaceFolder $RepoSettingsFile)).Hash | Should -Be $workspaceSettingsHash + Test-Path -LiteralPath (Join-Path $testWorkspaceFolder $CustomTemplateRepoSettingsFile) | Should -BeFalse + Test-Path -LiteralPath (Join-Path $testWorkspaceFolder $CustomTemplateProjectSettingsFile) | Should -BeFalse + Should -Invoke GetFilesToUpdate -Exactly 0 + Should -Invoke CloneIntoNewFolder -Exactly 0 + } - # Get Jobs section (without the jobs: line) - $jobsYaml = $yaml.Get('jobs:/') - ($jobsYaml.Get('Initialization:/steps:/- name: Read settings/with:/shell:').content -join '') | Should -be "shell: pwsh" - } + It 'Rejects an original template source folder redirected through a symlink when using a custom template' -Skip:(-not $script:hasSymlinkCapability) { + Set-Content -LiteralPath (Join-Path $primarySourceFolder $RepoSettingsFile) -Value '{"templateUrl":"https://github.com/contoso/AL-Go@main"}' -Encoding UTF8 + Move-Item -LiteralPath $originalSourceFolder -Destination $externalTemplateFolder + New-Item -ItemType SymbolicLink -Path $originalSourceFolder -Target $externalTemplateFolder | Out-Null + $rootLinkPath = $originalSourceFolder + + { . $scriptPath -templateUrl 'https://github.com/contoso/template@main' -downloadLatest $true -update N } | + Should -Throw -ExpectedMessage 'Unsafe path blocked: original template folder *' + + Should -Invoke DownloadTemplateRepository -Exactly 1 -ParameterFilter { $templateUrl -eq 'https://github.com/contoso/AL-Go@main' } + (Get-FileHash -LiteralPath (Join-Path $testWorkspaceFolder $RepoSettingsFile)).Hash | Should -Be $workspaceSettingsHash + Test-Path -LiteralPath (Join-Path $testWorkspaceFolder $CustomTemplateRepoSettingsFile) | Should -BeFalse + Test-Path -LiteralPath (Join-Path $testWorkspaceFolder $CustomTemplateProjectSettingsFile) | Should -BeFalse + Should -Invoke GetFilesToUpdate -Exactly 0 + Should -Invoke CloneIntoNewFolder -Exactly 0 + } + } - It 'Test YamlClass Remove' { - . (Join-Path $scriptRoot "yamlclass.ps1") + Context 'Template repository settings redirects' { + BeforeEach { + Mock IsDirectALGo { return $false } + $externalFolder = Join-Path $TestDrive 'externalTemplateSettings' + New-Item -ItemType Directory -Path $externalFolder -Force | Out-Null + $externalSettingsFile = Join-Path $externalFolder $RepoSettingsFileName + Set-Content -LiteralPath $externalSettingsFile -Value '{"external":"untouched"}' -Encoding UTF8 + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'externalSettingsHash', Justification = 'False positive.')] + $externalSettingsHash = (Get-FileHash -LiteralPath $externalSettingsFile).Hash + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'templateSettingsFile', Justification = 'False positive.')] + $templateSettingsFile = Join-Path $testTemplateFolder $RepoSettingsFile + } - $yamlSnippet = @( - "permissions:", - " contents: read", - " actions: read", - " pull-requests: write", - " checks: write" - ) + AfterEach { + $settingsItem = Get-Item -LiteralPath $templateSettingsFile -Force -ErrorAction SilentlyContinue + if ($settingsItem -and $settingsItem.LinkType) { + Remove-Item -LiteralPath $templateSettingsFile -Force + } - $permissionsYaml = [Yaml]::new($yamlSnippet) + $githubFolder = Join-Path $testTemplateFolder '.github' + $githubItem = Get-Item -LiteralPath $githubFolder -Force -ErrorAction SilentlyContinue + if ($githubItem -and $githubItem.LinkType -in @('Junction', 'SymbolicLink')) { + [System.IO.Directory]::Delete($githubFolder) + } + } - $permissionsContent = $permissionsYaml.Get('permissions:/') - $permissionsContent.content.Count | Should -be 4 - $permissionsContent.Remove(1, 0) # Remove nothing - $permissionsContent.content.Count | Should -be 4 - $permissionsContent.content[0].Trim() | Should -be 'contents: read' - $permissionsContent.content[1].Trim() | Should -be 'actions: read' - $permissionsContent.content[2].Trim() | Should -be 'pull-requests: write' - $permissionsContent.content[3].Trim() | Should -be 'checks: write' + It 'Rejects template repository settings redirected through a junction' -Skip:(-not $script:isWindowsPlatform) { + $githubFolder = Join-Path $testTemplateFolder '.github' + New-Item -ItemType Junction -Path $githubFolder -Target $externalFolder -Force | Out-Null - $permissionsContent = $permissionsYaml.Get('permissions:/') - $permissionsContent.content.Count | Should -be 4 - $permissionsContent.Remove(0, 3) # Remove first 3 lines - $permissionsContent.content.Count | Should -be 1 - $permissionsContent.content[0].Trim() | Should -be 'checks: write' + { . $scriptPath -templateUrl 'https://github.com/contoso/template@main' -downloadLatest $true -update N } | + Should -Throw -ExpectedMessage "Unsafe path blocked: template repository settings '$templateSettingsFile' does not physically resolve to itself*" - $permissionsContent = $permissionsYaml.Get('permissions:/') - $permissionsContent.content.Count | Should -be 4 - $permissionsContent.Remove(2, 1) # Remove only the 3rd line - $permissionsContent.content.Count | Should -be 3 - $permissionsContent.content[0].Trim() | Should -be 'contents: read' - $permissionsContent.content[1].Trim() | Should -be 'actions: read' - $permissionsContent.content[2].Trim() | Should -be 'checks: write' + (Get-FileHash -LiteralPath $externalSettingsFile).Hash | Should -Be $externalSettingsHash + Should -Invoke GetFilesToUpdate -Exactly 0 + Should -Invoke CloneIntoNewFolder -Exactly 0 + } - $permissionsContent = $permissionsYaml.Get('permissions:/') - $permissionsContent.content.Count | Should -be 4 - $permissionsContent.Remove(2, 4) # Remove more than the number of lines - $permissionsContent.content.Count | Should -be 2 # Only the first two lines should remain - $permissionsContent.content[0].Trim() | Should -be 'contents: read' - $permissionsContent.content[1].Trim() | Should -be 'actions: read' - } + It 'Rejects template repository settings redirected through a folder symlink' -Skip:(-not $script:hasSymlinkCapability) { + $githubFolder = Join-Path $testTemplateFolder '.github' + New-Item -ItemType SymbolicLink -Path $githubFolder -Target $externalFolder -Force | Out-Null - It 'Test YamlClass GetCustomJobsFromYaml' { - . (Join-Path $scriptRoot "yamlclass.ps1") + { . $scriptPath -templateUrl 'https://github.com/contoso/template@main' -downloadLatest $true -update N } | + Should -Throw -ExpectedMessage "Unsafe path blocked: template repository settings '$templateSettingsFile' does not physically resolve to itself*" - $customizedYaml = [Yaml]::load((Join-Path $PSScriptRoot 'CustomizedYamlSnippet-All.txt')) - $nonCustomizedYaml = [Yaml]::load((Join-Path $PSScriptRoot 'YamlSnippet.txt')) + (Get-FileHash -LiteralPath $externalSettingsFile).Hash | Should -Be $externalSettingsHash + Should -Invoke GetFilesToUpdate -Exactly 0 + Should -Invoke CloneIntoNewFolder -Exactly 0 + } - # Get Custom jobs from yaml - $customJobs = $customizedYaml.GetCustomJobsFromYaml('CustomJob*') - $customJobs | Should -Not -BeNullOrEmpty - $customJobs.Count | Should -be 2 + It 'Rejects template repository settings redirected through a file symlink' -Skip:(-not $script:hasSymlinkCapability) { + New-Item -ItemType Directory -Path (Join-Path $testTemplateFolder '.github') -Force | Out-Null + New-Item -ItemType SymbolicLink -Path $templateSettingsFile -Target $externalSettingsFile -Force | Out-Null - $customJobs[0].Name | Should -Be 'CustomJob-MyFinalJob' - $customJobs[0].Origin | Should -Be 'FinalRepository' + { . $scriptPath -templateUrl 'https://github.com/contoso/template@main' -downloadLatest $true -update N } | + Should -Throw -ExpectedMessage "Unsafe path blocked: template repository settings '$templateSettingsFile' does not physically resolve to itself*" - $customJobs[1].Name | Should -Be 'CustomJob-MyCustomTemplateJob' - $customJobs[1].Origin | Should -Be 'TemplateRepository' + (Get-FileHash -LiteralPath $externalSettingsFile).Hash | Should -Be $externalSettingsHash + Should -Invoke GetFilesToUpdate -Exactly 0 + Should -Invoke CloneIntoNewFolder -Exactly 0 + } + } - $emptyCustomJobs = $nonCustomizedYaml.GetCustomJobsFromYaml('CustomJob*') - $emptyCustomJobs | Should -BeNullOrEmpty - } + Context 'Clone repository settings redirects' { + BeforeEach { + Mock Test-HasSystemFileChanges { return $true } + $templateFile = Join-Path $testTemplateFolder 'pendingUpdate.txt' + $workspaceFile = Join-Path $testWorkspaceFolder 'pendingUpdate.txt' + $cloneFile = Join-Path $testCloneRoot 'pendingUpdate.txt' + $workspaceRemovalFile = Join-Path $testWorkspaceFolder 'pendingRemoval.txt' + $cloneRemovalFile = Join-Path $testCloneRoot 'pendingRemoval.txt' + Set-Content -LiteralPath $templateFile -Value 'new content' -Encoding UTF8 + Set-Content -LiteralPath $workspaceFile -Value 'old content' -Encoding UTF8 + Set-Content -LiteralPath $cloneFile -Value 'old content' -Encoding UTF8 + Set-Content -LiteralPath $workspaceRemovalFile -Value 'keep me' -Encoding UTF8 + Set-Content -LiteralPath $cloneRemovalFile -Value 'keep me' -Encoding UTF8 + + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'testFilesToInclude', Justification = 'False positive.')] + $testFilesToInclude = @( + @{ sourceFullPath = $templateFile; originalSourceFullPath = $null; type = ''; destinationFullPath = $workspaceFile } + ) + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'testFilesToExclude', Justification = 'False positive.')] + $testFilesToExclude = @(@{ destinationFullPath = $workspaceRemovalFile }) + + $externalFolder = Join-Path $TestDrive 'externalCloneSettings' + New-Item -ItemType Directory -Path $externalFolder -Force | Out-Null + $externalSettingsFile = Join-Path $externalFolder $RepoSettingsFileName + Set-Content -LiteralPath $externalSettingsFile -Value '{"external":"untouched"}' -Encoding UTF8 + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'externalSettingsHash', Justification = 'False positive.')] + $externalSettingsHash = (Get-FileHash -LiteralPath $externalSettingsFile).Hash + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'cloneSettingsFile', Justification = 'False positive.')] + $cloneSettingsFile = Join-Path $testCloneRoot $RepoSettingsFile + } - It 'Test YamlClass AddCustomJobsToYaml' { - . (Join-Path $scriptRoot "yamlclass.ps1") + AfterEach { + $settingsItem = Get-Item -LiteralPath $cloneSettingsFile -Force -ErrorAction SilentlyContinue + if ($settingsItem -and $settingsItem.LinkType) { + Remove-Item -LiteralPath $cloneSettingsFile -Force + } - $customTemplateYaml = [Yaml]::load((Join-Path $PSScriptRoot 'CustomizedYamlSnippet-TemplateRepository.txt')) - $finalRepositoryYaml = [Yaml]::load((Join-Path $PSScriptRoot 'CustomizedYamlSnippet-FinalRepository.txt')) - $nonCustomizedYaml = [Yaml]::load((Join-Path $PSScriptRoot 'YamlSnippet.txt')) + $githubFolder = Join-Path $testCloneRoot '.github' + $githubItem = Get-Item -LiteralPath $githubFolder -Force -ErrorAction SilentlyContinue + if ($githubItem -and $githubItem.LinkType -in @('Junction', 'SymbolicLink')) { + [System.IO.Directory]::Delete($githubFolder) + } + } - $customTemplateJobs = $customTemplateYaml.GetCustomJobsFromYaml('CustomJob*') - $customTemplateJobs | Should -Not -BeNullOrEmpty - $customTemplateJobs.Count | Should -be 1 - $customTemplateJobs[0].Name | Should -Be 'CustomJob-MyCustomTemplateJob' - $customTemplateJobs[0].Origin | Should -Be 'FinalRepository' # Custom template job has FinalRepository as origin when in the template itself + It 'Rejects clone repository settings redirected through a junction before applying changes' -Skip:(-not $script:isWindowsPlatform) { + $githubFolder = Join-Path $testCloneRoot '.github' + New-Item -ItemType Junction -Path $githubFolder -Target $externalFolder -Force | Out-Null - # Add the custom job to the non-customized yaml - $nonCustomizedYaml.AddCustomJobsToYaml($customTemplateJobs, [CustomizationOrigin]::TemplateRepository) + { . $scriptPath -templateUrl $testSettings.templateUrl -downloadLatest $true -update Y -updateBranch 'update-al-go-system-files' -token $fakeToken -directCommit $true -actor 'test-actor' } | + Should -Throw -ExpectedMessage "*Unsafe path blocked: repository settings '$cloneSettingsFile' does not physically resolve to itself*" - $nonCustomizedYaml.content -join "`r`n" | Should -Be ($finalRepositoryYaml.content -join "`r`n") + (Get-FileHash -LiteralPath $externalSettingsFile).Hash | Should -Be $externalSettingsHash + Get-Content -LiteralPath $cloneFile | Should -Be 'old content' + Get-Content -LiteralPath $cloneRemovalFile | Should -Be 'keep me' + Should -Invoke CloneIntoNewFolder -Exactly 1 + Should -Invoke UpdateSettingsFile -Exactly 0 + Should -Invoke CommitFromNewFolder -Exactly 0 + } - # Adding the jobs again doesn't have an effect - $nonCustomizedYaml.AddCustomJobsToYaml($customTemplateJobs, [CustomizationOrigin]::TemplateRepository) + It 'Rejects clone repository settings redirected through a folder symlink before applying changes' -Skip:(-not $script:hasSymlinkCapability) { + $githubFolder = Join-Path $testCloneRoot '.github' + New-Item -ItemType SymbolicLink -Path $githubFolder -Target $externalFolder -Force | Out-Null - $nonCustomizedYaml.content -join "`r`n" | Should -Be ($finalRepositoryYaml.content -join "`r`n") - } + { . $scriptPath -templateUrl $testSettings.templateUrl -downloadLatest $true -update Y -updateBranch 'update-al-go-system-files' -token $fakeToken -directCommit $true -actor 'test-actor' } | + Should -Throw -ExpectedMessage "*Unsafe path blocked: repository settings '$cloneSettingsFile' does not physically resolve to itself*" - It('Test YamlClass ApplyTemplateCustomizations') { - . (Join-Path $scriptRoot "yamlclass.ps1") + (Get-FileHash -LiteralPath $externalSettingsFile).Hash | Should -Be $externalSettingsHash + Get-Content -LiteralPath $cloneFile | Should -Be 'old content' + Get-Content -LiteralPath $cloneRemovalFile | Should -Be 'keep me' + Should -Invoke CloneIntoNewFolder -Exactly 1 + Should -Invoke UpdateSettingsFile -Exactly 0 + Should -Invoke CommitFromNewFolder -Exactly 0 + } - $srcContent = Get-Content (Join-Path $PSScriptRoot 'YamlSnippet.txt') - $resultContent = Get-Content (Join-Path $PSScriptRoot 'CustomizedYamlSnippet-FinalRepository.txt') + It 'Rejects clone repository settings redirected through a file symlink before applying changes' -Skip:(-not $script:hasSymlinkCapability) { + New-Item -ItemType Directory -Path (Join-Path $testCloneRoot '.github') -Force | Out-Null + New-Item -ItemType SymbolicLink -Path $cloneSettingsFile -Target $externalSettingsFile -Force | Out-Null - [Yaml]::ApplyTemplateCustomizations([ref] $srcContent, (Join-Path $PSScriptRoot 'CustomizedYamlSnippet-TemplateRepository.txt')) + { . $scriptPath -templateUrl $testSettings.templateUrl -downloadLatest $true -update Y -updateBranch 'update-al-go-system-files' -token $fakeToken -directCommit $true -actor 'test-actor' } | + Should -Throw -ExpectedMessage "*Unsafe path blocked: repository settings '$cloneSettingsFile' does not physically resolve to itself*" - $srcContent | Should -Be ($resultContent -join "`n") - } + (Get-FileHash -LiteralPath $externalSettingsFile).Hash | Should -Be $externalSettingsHash + Get-Content -LiteralPath $cloneFile | Should -Be 'old content' + Get-Content -LiteralPath $cloneRemovalFile | Should -Be 'keep me' + Should -Invoke CloneIntoNewFolder -Exactly 1 + Should -Invoke UpdateSettingsFile -Exactly 0 + Should -Invoke CommitFromNewFolder -Exactly 0 + } + } - It('Test YamlClass ApplyFinalCustomizations') { - . (Join-Path $scriptRoot "yamlclass.ps1") + It 'Rejects an external original source on Linux' -Skip:(-not $script:isLinuxPlatform) { + $invalidSource = Join-Path $testTemplateFolder 'File.txt' + $invalidOriginalSource = Join-Path $testTemplateFolder 'file.txt' + Set-Content -LiteralPath $invalidSource -Value 'safe content' + $external = Join-Path $TestDrive 'file.txt' + Set-Content -LiteralPath $external -Value 'external content' + New-Item -ItemType SymbolicLink -Path $invalidOriginalSource -Target $external | Out-Null + + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'testFilesToInclude', Justification = 'False positive.')] + $testFilesToInclude = @( + @{ sourceFullPath = $invalidSource; originalSourceFullPath = $invalidOriginalSource; type = ''; destinationFullPath = (Join-Path $testWorkspaceFolder 'File.txt') } + ) - $srcContent = Get-Content (Join-Path $PSScriptRoot 'YamlSnippet.txt') - $resultContent = Get-Content (Join-Path $PSScriptRoot 'CustomizedYamlSnippet-TemplateRepository.txt') + { . $scriptPath -templateUrl 'https://github.com/contoso/template@main' -downloadLatest $true -update N } | + Should -Throw -ExpectedMessage 'Unsafe path blocked: original source file *does not physically resolve*' + } - [Yaml]::ApplyFinalCustomizations([ref] $srcContent, (Join-Path $PSScriptRoot 'CustomizedYamlSnippet-TemplateRepository.txt')) # Threat the template repo as a final repo + It 'CheckForUpdates rejects source files that do not physically resolve to themselves using junctions' -Skip:(-not $script:isWindowsPlatform) { + # A legitimate file directly in the template folder + $legitTemplateFile = Join-Path $testTemplateFolder "legit.txt" + Set-Content -LiteralPath $legitTemplateFile -Value "legit content" - $srcContent | Should -Be ($resultContent -join "`n") - } -} + # Create a redirection folder and a junction pointing back to the template folder + $redirectedTemplateFolder = Join-Path $testTemplateFolder "redirected" + $redirectedTemplateFile = Join-Path $redirectedTemplateFolder "redirected.txt" + New-Item -ItemType Junction -Path $redirectedTemplateFolder -Target $testTemplateFolder -Force | Out-Null -Describe "CheckForUpdates Action: CheckForUpdates.HelperFunctions.ps1" { - BeforeAll { - $actionName = "CheckForUpdates" - $scriptRoot = Join-Path $PSScriptRoot "..\Actions\$actionName" -Resolve - . (Join-Path -Path $scriptRoot -ChildPath "yamlclass.ps1") - Import-Module (Join-Path $scriptRoot "..\Github-Helper.psm1") -DisableNameChecking -Force - . (Join-Path -Path $scriptRoot -ChildPath "CheckForUpdates.HelperFunctions.ps1") - [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'tmpSrcFile', Justification = 'False positive.')] - $tmpSrcFile = Join-Path $PSScriptRoot "tempSrcFile.json" - [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'tmpDstFile', Justification = 'False positive.')] - $tmpDstFile = Join-Path $PSScriptRoot "tempDestFile.json" - } + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'testFilesToInclude', Justification = 'False positive.')] + $testFilesToInclude = @( + @{ sourceFullPath = $legitTemplateFile; originalSourceFullPath = $null; type = ''; destinationFullPath = (Join-Path $testWorkspaceFolder "legit.txt") } + @{ sourceFullPath = $redirectedTemplateFile; originalSourceFullPath = $null; type = ''; destinationFullPath = (Join-Path $testWorkspaceFolder "redirected.txt") } + ) - AfterEach { - # Clean up temporary files - if (Test-Path $tmpSrcFile) { - Remove-Item -Path $tmpSrcFile -Force - } - if (Test-Path $tmpDstFile) { - Remove-Item -Path $tmpDstFile -Force + { . $scriptPath -templateUrl "https://github.com/contoso/template@main" -downloadLatest $true -update N } | + Should -Throw -ExpectedMessage "Unsafe path blocked: source file '*redirected.txt' does not physically resolve*" } - } - It 'ModifyRunsOnAndShell updates runs-on and shell in all workflow jobs' { - $yaml = [Yaml]::new(@( - "jobs:", - " CheckForUpdates:", - " runs-on: [ windows-latest ]", - " steps:", - " - name: Read settings", - " with:", - " shell: powershell", - " CreateRelease:", - " runs-on: [ windows-latest ]", - " steps:", - " - name: Create release", - " with:", - " shell: powershell" - )) - $repoSettings = @{ - "runs-on" = "self-hosted, custom-label" - "shell" = "pwsh" + It 'CheckForUpdates rejects original source files that do not physically resolve to themselves using junctions' -Skip:(-not $script:isWindowsPlatform) { + $legitTemplateFile = Join-Path $testTemplateFolder "legit.txt" + Set-Content -LiteralPath $legitTemplateFile -Value "legit content" + $redirectedTemplateFolder = Join-Path $testTemplateFolder "redirected" + $redirectedTemplateFile = Join-Path $redirectedTemplateFolder "redirected.txt" + New-Item -ItemType Junction -Path $redirectedTemplateFolder -Target $testTemplateFolder -Force | Out-Null + + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'testFilesToInclude', Justification = 'False positive.')] + $testFilesToInclude = @( + @{ sourceFullPath = $legitTemplateFile; originalSourceFullPath = $null; type = ''; destinationFullPath = (Join-Path $testWorkspaceFolder "legit.txt") } + @{ sourceFullPath = $legitTemplateFile; originalSourceFullPath = $redirectedTemplateFile; type = ''; destinationFullPath = (Join-Path $testWorkspaceFolder "redirected.txt") } + ) + + { . $scriptPath -templateUrl "https://github.com/contoso/template@main" -downloadLatest $true -update N } | + Should -Throw -ExpectedMessage "Unsafe path blocked: original source file '*redirected.txt' does not physically resolve*" } - ModifyRunsOnAndShell -yaml $yaml -repoSettings $repoSettings + It 'CheckForUpdates rejects source files that do not physically resolve to themselves using symlinks' -Skip:(-not $script:hasSymlinkCapability) { + # A legitimate file directly in the template folder + $legitTemplateFile = Join-Path $testTemplateFolder "legit.txt" + Set-Content -LiteralPath $legitTemplateFile -Value "legit content" - ($yaml.Get('jobs:/CheckForUpdates:/runs-on').content -join '') | Should -Be 'runs-on: [ self-hosted, custom-label ]' - ($yaml.Get('jobs:/CheckForUpdates:/steps:/- name: Read settings/with:/shell:').content -join '') | Should -Be 'shell: pwsh' - ($yaml.Get('jobs:/CreateRelease:/runs-on').content -join '') | Should -Be 'runs-on: [ self-hosted, custom-label ]' - ($yaml.Get('jobs:/CreateRelease:/steps:/- name: Create release/with:/shell:').content -join '') | Should -Be 'shell: pwsh' - } + # Create a redirection folder and a symbolic link pointing back to the template folder + $redirectedTemplateFolder = Join-Path $testTemplateFolder "redirected" + $redirectedTemplateFile = Join-Path $redirectedTemplateFolder "redirected.txt" + New-Item -ItemType SymbolicLink -Path $redirectedTemplateFolder -Target $testTemplateFolder -Force | Out-Null - It 'Applies draft skipping after generating dependency builds when enabled is ' -TestCases @( - @{ Enabled = $false } - @{ Enabled = $true } - ) { - param($Enabled) - . (Join-Path $scriptRoot '..\AL-Go-Helper.ps1' -Resolve) - $source = Join-Path $PSScriptRoot '..\Templates\Per Tenant Extension\.github\workflows\PullRequestHandler.yaml' - Mock ReadSettings { - @{ - 'runs-on' = 'windows-latest' - shell = 'powershell' - type = 'PTE' - powerPlatformSolutionFolder = '' - pullRequestTrigger = 'pull_request_target' - CICDPullRequestBranches = @('main') - skipDraftPullRequests = $Enabled - } - } + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'testFilesToInclude', Justification = 'False positive.')] + $testFilesToInclude = @( + @{ sourceFullPath = $legitTemplateFile; originalSourceFullPath = $null; type = ''; destinationFullPath = (Join-Path $testWorkspaceFolder "legit.txt") } + @{ sourceFullPath = $redirectedTemplateFile; originalSourceFullPath = $null; type = ''; destinationFullPath = (Join-Path $testWorkspaceFolder "redirected.txt") } + ) - $modified = GetWorkflowContentWithChangesFromSettings -srcFile $source -repoSettings @{} -depth 3 - $yaml = [Yaml]::new($modified.Split("`n")) - $yaml.GetNextLevel('jobs:/') | Should -Contain 'Build1:' - $yaml.GetNextLevel('jobs:/') | Should -Contain 'Build2:' - foreach ($job in $yaml.GetNextLevel('jobs:/')) { - if ($Enabled -and $job -ne 'PregateCheck:') { - $yaml.GetProperty("jobs:/$job/if:") | Should -Match '^\(github.event_name == ''merge_group'' \|\| github.event.pull_request.draft == false\) && ' - } - else { - $yaml.GetProperty("jobs:/$job/if:") | Should -Not -Match 'pull_request\.draft' - } - } - if ($Enabled) { - $yaml.GetPropertyArray('on:/pull_request_target:/types:') | Should -Contain 'ready_for_review' + { . $scriptPath -templateUrl "https://github.com/contoso/template@main" -downloadLatest $true -update N } | + Should -Throw -ExpectedMessage "Unsafe path blocked: source file '*redirected.txt' does not physically resolve*" } - else { - $yaml.Get('on:/pull_request_target:/types:') | Should -BeNullOrEmpty + + It 'CheckForUpdates rejects original source files that do not physically resolve to themselves using symlinks' -Skip:(-not $script:hasSymlinkCapability) { + $legitTemplateFile = Join-Path $testTemplateFolder "legit.txt" + Set-Content -LiteralPath $legitTemplateFile -Value "legit content" + $redirectedTemplateFolder = Join-Path $testTemplateFolder "redirected" + $redirectedTemplateFile = Join-Path $redirectedTemplateFolder "redirected.txt" + New-Item -ItemType SymbolicLink -Path $redirectedTemplateFolder -Target $testTemplateFolder -Force | Out-Null + + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'testFilesToInclude', Justification = 'False positive.')] + $testFilesToInclude = @( + @{ sourceFullPath = $legitTemplateFile; originalSourceFullPath = $null; type = ''; destinationFullPath = (Join-Path $testWorkspaceFolder "legit.txt") } + @{ sourceFullPath = $legitTemplateFile; originalSourceFullPath = $redirectedTemplateFile; type = ''; destinationFullPath = (Join-Path $testWorkspaceFolder "redirected.txt") } + ) + + { . $scriptPath -templateUrl "https://github.com/contoso/template@main" -downloadLatest $true -update N } | + Should -Throw -ExpectedMessage "Unsafe path blocked: original source file '*redirected.txt' does not physically resolve*" } - Mock Trace-Information {} - $customFile = Join-Path $TestDrive 'custom.yaml' - @( - 'jobs:' - ' CustomJobStandalone:' - ' runs-on: ubuntu-latest' - ' steps: []' - ' CustomJobAlways:' - ' if: ${{ always() }}' - ' runs-on: ubuntu-latest' - ' steps: []' - ) | Set-Content $customFile -Encoding UTF8 - $customYaml = [Yaml]::Load($customFile) - [Yaml]::ApplyTemplateCustomizations([ref] $modified, $customFile) - (Get-Content $customFile -Raw -Encoding UTF8).Replace('CustomJob', 'CustomJobRepo') | Set-Content $customFile -Encoding UTF8 - [Yaml]::ApplyFinalCustomizations([ref] $modified, $customFile) - $yaml = [Yaml]::new($modified.Split("`n")) - foreach ($name in @('Standalone', 'Always')) { - $expected = ($customYaml.Get("jobs:/CustomJob${name}:/").content -join "`n").TrimEnd() - ($yaml.Get("jobs:/CustomJob${name}:/").content -join "`n").TrimEnd() | Should -Be $expected - ($yaml.Get("jobs:/CustomJobRepo${name}:/").content -join "`n").TrimEnd() | Should -Be $expected + It 'CheckForUpdates rejects source files with case-distinct original sources that do not physically resolve to themselves using symlinks on Linux' -Skip:(-not $script:isLinuxPlatform) { + $directTemplateFolder = Join-Path $testTemplateFolder "folder" + $directTemplateFile = Join-Path $directTemplateFolder "file.txt" + New-Item -ItemType Directory -Path $directTemplateFolder -Force | Out-Null + Set-Content -LiteralPath $directTemplateFile -Value "direct content" + + $redirectedTemplateFolder = Join-Path $testTemplateFolder "FOLDER" + $redirectedTemplateFile = Join-Path $redirectedTemplateFolder "file.txt" + New-Item -ItemType SymbolicLink -Path $redirectedTemplateFolder -Target $testTemplateFolder -Force | Out-Null + Set-Content -LiteralPath $redirectedTemplateFile -Value "redirected content" + + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'testFilesToInclude', Justification = 'False positive.')] + $testFilesToInclude = @( + @{ sourceFullPath = $directTemplateFile; originalSourceFullPath = $redirectedTemplateFile; type = ''; destinationFullPath = (Join-Path $testWorkspaceFolder "file.txt") } + ) + + { . $scriptPath -templateUrl "https://github.com/contoso/template@main" -downloadLatest $true -update N } | + Should -Throw -ExpectedMessage "Unsafe path blocked: original source file '*FOLDER*' does not physically resolve*" } - } - It 'Keeps Copilot review jobs hosted with self-hosted build settings in