Enhance customALGoFiles feature

Actions/.Modules/settings.schema.json

@@ -743,6 +743,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",
@@ -759,6 +760,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."
@@ -767,6 +772,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. When used in a custom template's settings, exclusions 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",

Actions/CheckForUpdates/CheckForUpdates.ps1

@@ -52,7 +52,7 @@ if ($token) {
 # 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
+$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)
@@ -113,6 +113,12 @@ if (-not $isDirectALGo) {
 
 # Get the list of projects in the current repository
 $baseFolder = $ENV:GITHUB_WORKSPACE
+
+if ($originalTemplateFolder) {
+    # Use current custom template settings for this run without changing the workspace before comparison.
+    $repoSettings = ReadSettingsWithCurrentCustomTemplateRepoSettings -baseFolder $baseFolder -templateFolder $templateFolder
+}
+
 $projects = @(GetProjectsFromRepository -baseFolder $baseFolder -projectsFromSettings $repoSettings.projects)
 
 $filesToInclude, $filesToExclude = GetFilesToUpdate -settings $repoSettings -projects $projects -baseFolder $baseFolder -templateFolder $templateFolder -originalTemplateFolder $originalTemplateFolder

RELEASENOTES.md

@@ -1,3 +1,13 @@
+### Enhanced `customALGoFiles` setting
+
+The `customALGoFiles` setting of a custom template was only applied on the next Update (from `AL-Go-TemplateRepoSettings.doNotEdit.json`). Now the up-to-date settings of the custom template are used directly during "Update AL-Go System Files". The template's `filesToInclude` and `filesToExclude` settings are merged with the consumer repo's settings before resolution.
+
+- **`filesToInclude`** now also resolves files from the original AL-Go template. Files present in the official template are propagated even when they are absent from your custom template. When a file exists in both, the official template supplies the base content; for workflow files, customizations from the custom template are reapplied.
+- **`filesToExclude`** now also resolves files from the original AL-Go template (same dual-resolution as `filesToInclude`). Files resolved by `filesToInclude` whose source matches a `filesToExclude` entry are not copied to consumer repos, and existing copies are removed.
+- **`destinationName`** (new property on `filesToInclude`): Allows renaming a file at the destination. When set, the file is written to `<destinationFolder>/<destinationName>` instead of keeping the source filename.
+
+Read more at [Customizing AL-Go for GitHub](Scenarios/CustomizingALGoForGitHub.md#Using-custom-template-files).
+
 ### Expanded AL-Go telemetry dashboard
 
 The starter Azure Data Explorer dashboard now includes dedicated views for workflow reliability, run exploration, test quality, workflow duration, runner efficiency, and AL-Go maintenance. It also provides repository, workflow, branch, and repository-type filtering, clearer empty states, and repository-level runtime supportability information.

Scenarios/CustomizingALGoForGitHub.md

@@ -239,10 +239,25 @@ 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_: `*.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.
 
+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** and **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:
 
 - `sourceFolder`: A path to a folder, relative to the template, where to look for files. If not specified the root folder is implied. _Example_: `src/scripts`.
@@ -251,13 +266,16 @@ In order to instruct AL-Go which files to look for at the template repository, y
 > [!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.
 
+> [!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.
+
 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 | 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 |
 
 ### Examples of using custom template files

Scenarios/settings.md

@@ -248,7 +248,7 @@ Please read the release notes carefully when installing new versions of AL-Go fo
 | <a id="BcContainerHelperVersion"></a>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) |
 | <a id="unusedALGoSystemFiles"></a>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.<br />Use this setting with care, as this can break the AL-Go for GitHub functionality and potentially leave your repo no longer functional. | [ ] |
 | <a id="reportsuppresseddiagnostics"></a>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 <id>`. This can be useful if you want to ensure that no warnings are suppressed in your code. | false |
-| <a id="customALGoFiles"></a>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": [] }`
+| <a id="customALGoFiles"></a>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).<br />**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).<br />**filesToExclude** = an array of file specifications to exclude (remove) from `filesToInclude`. Each item can contain **sourceFolder** and **filter** (same meaning as above). | `{ "filesToInclude": [], "filesToExclude": [] }`
 
 ## Overwrite settings <a id="overwriteSettings"></a>