microsoft · freddydk · Jan 22, 2024 · Jan 22, 2024
diff --git a/.AL-Go/cloudDevEnv.ps1 b/.AL-Go/cloudDevEnv.ps1
@@ -27,11 +27,11 @@ Write-Host -ForegroundColor Yellow @'
 $webClient = New-Object System.Net.WebClient
 $webClient.CachePolicy = New-Object System.Net.Cache.RequestCachePolicy -argumentList ([System.Net.Cache.RequestCacheLevel]::NoCacheNoStore)
 $webClient.Encoding = [System.Text.Encoding]::UTF8
-$GitHubHelperUrl = 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v4.0/Github-Helper.psm1'
+$GitHubHelperUrl = 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v4.1/Github-Helper.psm1'
 Write-Host "Downloading GitHub Helper module from $GitHubHelperUrl"
 $GitHubHelperPath = "$([System.IO.Path]::GetTempFileName()).psm1"
 $webClient.DownloadFile($GitHubHelperUrl, $GitHubHelperPath)
-$ALGoHelperUrl = 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v4.0/AL-Go-Helper.ps1'
+$ALGoHelperUrl = 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v4.1/AL-Go-Helper.ps1'
 Write-Host "Downloading AL-Go Helper script from $ALGoHelperUrl"
 $ALGoHelperPath = "$([System.IO.Path]::GetTempFileName()).ps1"
 $webClient.DownloadFile($ALGoHelperUrl, $ALGoHelperPath)

diff --git a/.AL-Go/localDevEnv.ps1 b/.AL-Go/localDevEnv.ps1
@@ -30,11 +30,11 @@ Write-Host -ForegroundColor Yellow @'
 $webClient = New-Object System.Net.WebClient
 $webClient.CachePolicy = New-Object System.Net.Cache.RequestCachePolicy -argumentList ([System.Net.Cache.RequestCacheLevel]::NoCacheNoStore)
 $webClient.Encoding = [System.Text.Encoding]::UTF8
-$GitHubHelperUrl = 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v4.0/Github-Helper.psm1'
+$GitHubHelperUrl = 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v4.1/Github-Helper.psm1'
 Write-Host "Downloading GitHub Helper module from $GitHubHelperUrl"
 $GitHubHelperPath = "$([System.IO.Path]::GetTempFileName()).psm1"
 $webClient.DownloadFile($GitHubHelperUrl, $GitHubHelperPath)
-$ALGoHelperUrl = 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v4.0/AL-Go-Helper.ps1'
+$ALGoHelperUrl = 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v4.1/AL-Go-Helper.ps1'
 Write-Host "Downloading AL-Go Helper script from $ALGoHelperUrl"
 $ALGoHelperPath = "$([System.IO.Path]::GetTempFileName()).ps1"
 $webClient.DownloadFile($ALGoHelperUrl, $ALGoHelperPath)

diff --git a/.github/RELEASENOTES.copy.md b/.github/RELEASENOTES.copy.md
@@ -1,3 +1,45 @@
+## v4.1
+
+### New Settings
+- `templateSha`: The SHA of the version of AL-Go currently used
+
+### New Actions
+- `DumpWorkflowInfo`: Dump information about running workflow
+- `Troubleshooting` : Run troubleshooting for repository
+
+### Update AL-Go System Files
+Add another parameter when running Update AL-Go System Files, called downloadLatest, used to indicate whether to download latest version from template repository. Default value is true.
+If false, the templateSha repository setting is used to download specific AL-Go System Files when calculating new files.
+
+### Issues
+- Issue 782 Exclude '.altestrunner/' from template .gitignore
+- Issue 823 Dependencies from prior build jobs are not included when using useProjectDependencies
+- App artifacts for version 'latest' are now fetched from the latest CICD run that completed and successfully built all the projects for the corresponding branch.
+- Issue 824 Utilize `useCompilerFolder` setting when creating an development environment for an AL-Go project.
+- Issue 828 and 825 display warnings for secrets, which might cause AL-Go for GitHub to malfunction
+
+### New Settings
+
+- `alDoc` : JSON object with properties for the ALDoc reference document generation
+  - **continuousDeployment** = Determines if reference documentation will be deployed continuously as part of CI/CD. You can run the **Deploy Reference Documentation** workflow to deploy manually or on a schedule. (Default false)
+  - **deployToGitHubPages** = Determines whether or not the reference documentation site should be deployed to GitHub Pages for the repository. In order to deploy to GitHub Pages, GitHub Pages must be enabled and set to GitHub Actions. (Default true)
+  - **maxReleases** = Maximum number of releases to include in the reference documentation. (Default 3)
+  - **groupByProject** = Determines whether projects in multi-project repositories are used as folders in reference documentation
+  - **includeProjects** = An array of projects to include in the reference documentation. (Default all)
+  - **excludeProjects** = An array of projects to exclude in the reference documentation. (Default none)-
+  - **header** = Header for the documentation site. (Default: Documentation for...)
+  - **footer** = Footer for the documentation site. (Default: Made with...)
+  - **defaultIndexMD** = Markdown for the landing page of the documentation site. (Default: Reference documentation...)
+  - **defaultReleaseMD** = Markdown for the landing page of the release sites. (Default: Release reference documentation...)
+  - *Note that in header, footer, defaultIndexMD and defaultReleaseMD you can use the following placeholders: {REPOSITORY}, {VERSION}, {INDEXTEMPLATERELATIVEPATH}, {RELEASENOTES}* 
+
+### New Workflows
+- **Deploy Reference Documentation** is a workflow, which you can invoke manually or on a schedule to generate and deploy reference documentation using the aldoc tool, using the ALDoc setting properties described above.
+- **Troubleshooting** is a workflow, which you can invoke manually to run troubleshooting on the repository and check for settings or secrets, containing illegal values. When creating issues on https://github.com/microsoft/AL-Go/issues, we might ask you to run the troubleshooter to help identify common problems.
+
+### Support for ALDoc reference documentation tool
+ALDoc reference documentation tool is now supported for generating and deploying reference documentation for your projects either continuously or manually/scheduled.
+
 ## v4.0
 
 ### Removal of the InsiderSasToken

diff --git a/.github/workflows/AddExistingAppOrTestApp.yaml b/.github/workflows/AddExistingAppOrTestApp.yaml
@@ -13,12 +13,13 @@ on:
         description: Direct Download Url of .app or .zip file
         required: true
       directCommit:
-        description: Direct COMMIT (Y/N)
-        required: false
-        default: 'N'
+        description: Direct Commit?
+        type: boolean
+        default: false
       useGhTokenWorkflow:
-        description: Use GhTokenWorkflow for Pull Request/COMMIT
+        description: Use GhTokenWorkflow for PR/Commit?
         type: boolean
+        default: false
 
 permissions:
   contents: write
@@ -34,34 +35,40 @@ env:
 
 jobs:
   AddExistingAppOrTestApp:
+    needs: [ ]
     runs-on: [ windows-latest ]
     steps:
+      - name: Dump Workflow Information
+        uses: microsoft/AL-Go-Actions/[email protected]
+        with:
+          shell: powershell
+
       - name: Checkout
         uses: actions/checkout@v3
 
       - name: Initialize the workflow
         id: init
-        uses: microsoft/AL-Go-Actions/WorkflowInitialize@v4.0
+        uses: microsoft/AL-Go-Actions/WorkflowInitialize@v4.1
         with:
           shell: powershell
           eventId: "DO0090"
 
       - name: Read settings
-        uses: microsoft/AL-Go-Actions/ReadSettings@v4.0
+        uses: microsoft/AL-Go-Actions/ReadSettings@v4.1
         with:
           shell: powershell
 
       - name: Read secrets
         id: ReadSecrets
-        uses: microsoft/AL-Go-Actions/ReadSecrets@v4.0
+        uses: microsoft/AL-Go-Actions/ReadSecrets@v4.1
         with:
           shell: powershell
           gitHubSecrets: ${{ toJson(secrets) }}
           getSecrets: 'TokenForPush'
           useGhTokenWorkflowForPush: '${{ github.event.inputs.useGhTokenWorkflow }}'
 
       - name: Add existing app
-        uses: microsoft/AL-Go-Actions/AddExistingApp@v4.0
+        uses: microsoft/AL-Go-Actions/AddExistingApp@v4.1
         with:
           shell: powershell
           token: ${{ steps.ReadSecrets.outputs.TokenForPush }}
@@ -72,7 +79,7 @@ jobs:
 
       - name: Finalize the workflow
         if: always()
-        uses: microsoft/AL-Go-Actions/WorkflowPostProcess@v4.0
+        uses: microsoft/AL-Go-Actions/WorkflowPostProcess@v4.1
         with:
           shell: powershell
           eventId: "DO0090"

diff --git a/.github/workflows/CICD.yaml b/.github/workflows/CICD.yaml
@@ -24,12 +24,15 @@ env:
 
 jobs:
   Initialization:
+    needs: [ ]
     runs-on: [ windows-latest ]
     outputs:
       telemetryScopeJson: ${{ steps.init.outputs.telemetryScopeJson }}
       environmentsMatrixJson: ${{ steps.DetermineDeploymentEnvironments.outputs.EnvironmentsMatrixJson }}
       environmentCount: ${{ steps.DetermineDeploymentEnvironments.outputs.EnvironmentCount }}
       deploymentEnvironmentsJson: ${{ steps.DetermineDeploymentEnvironments.outputs.DeploymentEnvironmentsJson }}
+      generateALDocArtifact: ${{ steps.DetermineDeploymentEnvironments.outputs.GenerateALDocArtifact }}
+      deployALDocArtifact: ${{ steps.DetermineDeploymentEnvironments.outputs.DeployALDocArtifact }}
       deliveryTargetsJson: ${{ steps.DetermineDeliveryTargets.outputs.DeliveryTargetsJson }}
       githubRunner: ${{ steps.ReadSettings.outputs.GitHubRunnerJson }}
       githubRunnerShell: ${{ steps.ReadSettings.outputs.GitHubRunnerShell }}
@@ -38,21 +41,26 @@ jobs:
       buildOrderJson: ${{ steps.determineProjectsToBuild.outputs.BuildOrderJson }}
       workflowDepth: ${{ steps.DetermineWorkflowDepth.outputs.WorkflowDepth }}
     steps:
+      - name: Dump Workflow Information
+        uses: microsoft/AL-Go-Actions/[email protected]
+        with:
+          shell: powershell
+
       - name: Checkout
         uses: actions/checkout@v3
         with:
           lfs: true
 
       - name: Initialize the workflow
         id: init
-        uses: microsoft/AL-Go-Actions/WorkflowInitialize@v4.0
+        uses: microsoft/AL-Go-Actions/WorkflowInitialize@v4.1
         with:
           shell: powershell
           eventId: "DO0091"
 
       - name: Read settings
         id: ReadSettings
-        uses: microsoft/AL-Go-Actions/ReadSettings@v4.0
+        uses: microsoft/AL-Go-Actions/ReadSettings@v4.1
         with:
           shell: powershell
           get: type
@@ -64,40 +72,40 @@ jobs:
 
       - name: Determine Projects To Build
         id: determineProjectsToBuild
-        uses: microsoft/AL-Go-Actions/DetermineProjectsToBuild@v4.0
+        uses: microsoft/AL-Go-Actions/DetermineProjectsToBuild@v4.1
         with:
           shell: powershell
           maxBuildDepth: ${{ env.workflowDepth }}
 
       - name: Determine Delivery Target Secrets
         id: DetermineDeliveryTargetSecrets
-        uses: microsoft/AL-Go-Actions/DetermineDeliveryTargets@v4.0
+        uses: microsoft/AL-Go-Actions/DetermineDeliveryTargets@v4.1
         with:
           shell: powershell
           projectsJson: '${{ steps.determineProjectsToBuild.outputs.ProjectsJson }}'
-          checkContextSecrets: 'N'
+          checkContextSecrets: 'false'
 
       - name: Read secrets
         id: ReadSecrets
-        uses: microsoft/AL-Go-Actions/ReadSecrets@v4.0
+        uses: microsoft/AL-Go-Actions/ReadSecrets@v4.1
         with:
           shell: powershell
           gitHubSecrets: ${{ toJson(secrets) }}
           getSecrets: ${{ steps.DetermineDeliveryTargetSecrets.outputs.ContextSecrets }}
 
       - name: Determine Delivery Targets
         id: DetermineDeliveryTargets
-        uses: microsoft/AL-Go-Actions/DetermineDeliveryTargets@v4.0
+        uses: microsoft/AL-Go-Actions/DetermineDeliveryTargets@v4.1
         env:
           Secrets: '${{ steps.ReadSecrets.outputs.Secrets }}'
         with:
           shell: powershell
           projectsJson: '${{ steps.determineProjectsToBuild.outputs.ProjectsJson }}'
-          checkContextSecrets: 'Y'
+          checkContextSecrets: 'true'
 
       - name: Determine Deployment Environments
         id: DetermineDeploymentEnvironments
-        uses: microsoft/AL-Go-Actions/DetermineDeploymentEnvironments@v4.0
+        uses: microsoft/AL-Go-Actions/DetermineDeploymentEnvironments@v4.1
         env:
           GITHUB_TOKEN: ${{ github.token }}
         with:
@@ -106,24 +114,24 @@ jobs:
           type: 'CD'
 
   CheckForUpdates:
-    runs-on: [ windows-latest ]
     needs: [ Initialization ]
+    runs-on: [ windows-latest ]
     steps:
       - name: Checkout
         uses: actions/checkout@v3
 
       - name: Read settings
-        uses: microsoft/AL-Go-Actions/ReadSettings@v4.0
+        uses: microsoft/AL-Go-Actions/ReadSettings@v4.1
         with:
           shell: powershell
           get: templateUrl
 
       - name: Check for updates to AL-Go system files
-        uses: microsoft/AL-Go-Actions/CheckForUpdates@v4.0
+        uses: microsoft/AL-Go-Actions/CheckForUpdates@v4.1
         with:
           shell: powershell
-          parentTelemetryScopeJson: ${{ needs.Initialization.outputs.telemetryScopeJson }}
           templateUrl: ${{ env.templateUrl }}
+          downloadLatest: true
 
   Build:
     needs: [ Initialization ]
@@ -149,6 +157,53 @@ jobs:
       signArtifacts: true
       useArtifactCache: true
 
+  DeployALDoc:
+    needs: [ Initialization, Build ]
+    if: always() && needs.Build.result == 'Success' && needs.Initialization.outputs.generateALDocArtifact == 1 && github.ref_name == 'main'
+    runs-on: windows-latest
+    name: Deploy Reference Documentation
+    permissions:
+      contents: write
+      actions: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v3
+        with:
+          path: '.artifacts'
+
+      - name: Read settings
+        uses: microsoft/AL-Go-Actions/[email protected]
+        with:
+          shell: powershell
+
+      - name: Setup Pages
+        if: needs.Initialization.outputs.deployALDocArtifact == 1
+        uses: actions/configure-pages@v3
+
+      - name: Build Reference Documentation
+        uses: microsoft/AL-Go-Actions/[email protected]
+        with:
+          shell: powershell
+          artifacts: '.artifacts'
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ".aldoc/_site/"
+
+      - name: Deploy to GitHub Pages
+        if: needs.Initialization.outputs.deployALDocArtifact == 1
+        id: deployment
+        uses: actions/deploy-pages@v2
+
   Deploy:
     needs: [ Initialization, Build ]
     if: always() && needs.Build.result == 'Success' && needs.Initialization.outputs.environmentCount > 0
@@ -168,7 +223,7 @@ jobs:
           path: '.artifacts'
 
       - name: Read settings
-        uses: microsoft/AL-Go-Actions/ReadSettings@v4.0
+        uses: microsoft/AL-Go-Actions/ReadSettings@v4.1
         with:
           shell: powershell
 
@@ -181,15 +236,15 @@ jobs:
 
       - name: Read secrets
         id: ReadSecrets
-        uses: microsoft/AL-Go-Actions/ReadSecrets@v4.0
+        uses: microsoft/AL-Go-Actions/ReadSecrets@v4.1
         with:
           shell: powershell
           gitHubSecrets: ${{ toJson(secrets) }}
           getSecrets: '${{ steps.envName.outputs.envName }}-AuthContext,${{ steps.envName.outputs.envName }}_AuthContext,AuthContext,${{ steps.envName.outputs.envName }}-EnvironmentName,${{ steps.envName.outputs.envName }}_EnvironmentName,EnvironmentName,projects'
 
       - name: Deploy
         id: Deploy
-        uses: microsoft/AL-Go-Actions/Deploy@v4.0
+        uses: microsoft/AL-Go-Actions/Deploy@v4.1
         env:
           Secrets: '${{ steps.ReadSecrets.outputs.Secrets }}'
         with:
@@ -218,20 +273,20 @@ jobs:
           path: '.artifacts'
 
       - name: Read settings
-        uses: microsoft/AL-Go-Actions/ReadSettings@v4.0
+        uses: microsoft/AL-Go-Actions/ReadSettings@v4.1
         with:
           shell: powershell
 
       - name: Read secrets
         id: ReadSecrets
-        uses: microsoft/AL-Go-Actions/ReadSecrets@v4.0
+        uses: microsoft/AL-Go-Actions/ReadSecrets@v4.1
         with:
           shell: powershell
           gitHubSecrets: ${{ toJson(secrets) }}
           getSecrets: '${{ matrix.deliveryTarget }}Context'
 
       - name: Deliver
-        uses: microsoft/AL-Go-Actions/Deliver@v4.0
+        uses: microsoft/AL-Go-Actions/Deliver@v4.1
         env:
           Secrets: '${{ steps.ReadSecrets.outputs.Secrets }}'
         with:
@@ -242,16 +297,16 @@ jobs:
           artifacts: '.artifacts'
 
   PostProcess:
+    needs: [ Initialization, Build, Deploy, Deliver, DeployALDoc ]
     if: (!cancelled())
     runs-on: [ windows-latest ]
-    needs: [ Initialization, Build, Deploy, Deliver ]
     steps:
       - name: Checkout
         uses: actions/checkout@v3
 
       - name: Finalize the workflow
         id: PostProcess
-        uses: microsoft/AL-Go-Actions/WorkflowPostProcess@v4.0
+        uses: microsoft/AL-Go-Actions/WorkflowPostProcess@v4.1
         with:
           shell: powershell
           eventId: "DO0091"