ALDoc support in AL-Go (#760)

# TO:DO ```[tasklist] # Tasks - [x] Create new Action: BuildALDoc to build reference documentation - [x] Create new job in CI/CD to build and publish reference documentation - [x] Create reference documentation for x versions of the apps. - [x] Create new workflow for publishing ALDoc reference documentation - [x] Only allow publishing reference documentation if GitHub Pages is set to GitHub Actions - [x] Add release notes - [x] Add documentation - [x] Add end 2 end test ``` # Implementation ## New Settings: ALDoc structure The following settings structure will be added to repository settings (with default values): ``` "ALDoc" = [ordered]@{ "ContinuousDeployment" = $false "DeployToGitHubPages" = $true "MaxReleases" = 3 "Projects" = @() "ExcludeProjects" = @() "Header" = "Documentation for {REPOSITORY} {VERSION}" "Footer" = "Made with <a href=""https://aka.ms/AL-Go"">AL-Go for GitHub</a>, <a href=""https://go.microsoft.com/fwlink/?linkid=2247728"">ALDoc</a> and <a href=""https://dotnet.github.io/docfx"">DocFx</a>" "DefaultIndexMD" = "## Reference documentation\n\nThis is the generated reference documentation for [{REPOSITORY}](https://github.com/{REPOSITORY}).\n\nYou can use the navigation bar at the top and the table of contents to the left to navigate your documentation.\n\nYou can change this content by creating/editing the **{INDEXTEMPLATERELATIVEPATH}** file in your repository or use the ALDoc:DefaultIndexMD setting in your repository settings file (.github/AL-Go-Settings.json)\n\n{RELEASENOTES}" "DefaultReleaseMD" = "## Release reference documentation\n\nThis is the generated reference documentation for [{REPOSITORY}](https://github.com/{REPOSITORY}).\n\nYou can use the navigation bar at the top and the table of contents to the left to navigate your documentation.\n\nYou can change this content by creating/editing the **{INDEXTEMPLATERELATIVEPATH}** file in your repository or use the ALDoc:DefaultReleaseMD setting in your repository settings file (.github/AL-Go-Settings.json)\n\n{RELEASENOTES}" } ``` Where: - ALDoc.ContinuousDeployment controls whether or not to run continuous deployment of reference documentation - ALDoc.DeployToGitHubPages determines whether or not the generated reference documentation is deployed to the repo's GitHub pages site. - ALDoc.MaxReleases is the number of releases to include in the reference documentation - ALDoc.Projects is an array of projects to include in the reference documentation - ALDoc.ExcludeProjects is an array of projects to exclude in the reference documentation - ALDoc.Header and ALDoc.Footer are the header and footer markdown of the reference documentation - ALDOc.DefaultIndexMD is the default markdown to use for the landing page of the reference documentation - ALDoc.DefaultReleaseMD is the default markdown to use for the landing page of a release in the reference documentation ALDoc.Header, ALDoc.Footer, ALDoc.DefaultIndexMD and ALDoc.DefaultReleaseMD can have the following placeholders, which will be replaced by their actual values during generation: - {REPOSITORY} is the repository (like microsoft/AL-Go) - {VERSION} is the version of the release - {RELEASENOTES} are the release notes of the release - {INDEXTEMPLATERELATIVEPATH} is the path of the index template ## New Action: BuildALDoc New action, which builds the ALDoc documentation for the apps in the .artifacts folder and places it in .aldoc/_site It includes the projects specified in ALDoc.Projects (or all if not specified) and excludes the projects from ALDoc.ExcludeProjects. It uses ALDoc.Header, ALDoc.Footer when invoking docfx. It uses ALDoc.DefaultIndexMD as index.md for the reference docs and ALDoc.DefaultReleaseMD as index.md for reference docs for released versions. The action also generates reference documentation for a number of prior releases (determined by setting ALDoc.MaxReleases) and adds those to the documentation site as well (under releases/version) ## Modified Workflow: CI/CD New job added: Deploy ALDoc documentation, invoked if ALDoc.ContinuousDeployment is true. If ALDoc.DeployToGitHubPages is true (which is default) the workflow automatically deploys to GitHub pages (if supported by the SKU) ## New Workflow: Deploy Reference Documentation If ALDoc.ContinuousDeployment is false (or if you want to redeploy) you can invoke this workflow to manually generate and publish the reference documentation. If ALDoc.DeployToGitHubPages is true (which is default) the workflow automatically deploys to GitHub pages (if supported by the SKU) # Try it out Update AL-Go system files with **freddydk/AL-Go@aldoc** --------- Co-authored-by: freddydk <freddydk@users.noreply.github.com> Co-authored-by: Maria Zhelezova <43066499+mazhelez@users.noreply.github.com> Co-authored-by: Alexander Holstrup <117829001+aholstrup1@users.noreply.github.com>
2023-12-05 08:06:02 +01:00 · 2023-12-05 08:06:02 +01:00 · 39d8f99a5d
--- a/Actions/AL-Go-Helper.ps1
+++ b/Actions/AL-Go-Helper.ps1
@ -620,9 +620,21 @@ function ReadSettings {
        "environments"                                  = @()
        "buildModes"                                    = @()
        "useCompilerFolder"                             = $false
-        "PullRequestTrigger"                            = "pull_request_target"
+        "pullRequestTrigger"                            = "pull_request_target"
        "fullBuildPatterns"                             = @()
        "excludeEnvironments"                           = @()
+        "alDoc"                                         = [ordered]@{
+            "continuousDeployment"                      = $false
+            "deployToGitHubPages"                       = $true
+            "maxReleases"                               = 3
+            "groupByProject"                      = $true
+            "includeProjects"                           = @()
+            "excludeProjects"                           = @()
+            "header"                                    = "Documentation for {REPOSITORY} {VERSION}"
+            "footer"                                    = "Documentation for <a href=""https://github.com/{REPOSITORY}"">{REPOSITORY}</a> made with <a href=""https://aka.ms/AL-Go"">AL-Go for GitHub</a>, <a href=""https://go.microsoft.com/fwlink/?linkid=2247728"">ALDoc</a> and <a href=""https://dotnet.github.io/docfx"">DocFx</a>"
+            "defaultIndexMD"                            = "## Reference documentation\n\nThis is the generated reference documentation for [{REPOSITORY}](https://github.com/{REPOSITORY}).\n\nYou can use the navigation bar at the top and the table of contents to the left to navigate your documentation.\n\nYou can change this content by creating/editing the **{INDEXTEMPLATERELATIVEPATH}** file in your repository or use the alDoc:defaultIndexMD setting in your repository settings file (.github/AL-Go-Settings.json)\n\n{RELEASENOTES}"
+            "defaultReleaseMD"                          = "## Release reference documentation\n\nThis is the generated reference documentation for [{REPOSITORY}](https://github.com/{REPOSITORY}).\n\nYou can use the navigation bar at the top and the table of contents to the left to navigate your documentation.\n\nYou can change this content by creating/editing the **{INDEXTEMPLATERELATIVEPATH}** file in your repository or use the alDoc:defaultReleaseMD setting in your repository settings file (.github/AL-Go-Settings.json)\n\n{RELEASENOTES}"
+        }
    }

    # Read settings from files and merge them into the settings object
@ -1075,6 +1087,7 @@ function CheckAppDependencyProbingPaths {
        [hashTable] $settings,
        $token,
        [string] $baseFolder = $ENV:GITHUB_WORKSPACE,
+        [string] $repository = $ENV:GITHUB_REPOSITORY,
        [string] $project = '.',
        [string[]] $includeOnlyAppIds
    )
@ -1095,10 +1108,10 @@ function CheckAppDependencyProbingPaths {
                throw "The Setting AppDependencyProbingPaths needs to contain a repo property, pointing to the repository on which your project have a dependency"
            }
            if ($dependency.Repo -eq ".") {
-                $dependency.Repo = "$ENV:GITHUB_SERVER_URL/$ENV:GITHUB_REPOSITORY"
+                $dependency.Repo = "https://github.com/$repository"
            }
            elseif ($dependency.Repo -notlike "https://*") {
-                $dependency.Repo = "$ENV:GITHUB_SERVER_URL/$($dependency.Repo)"
+                $dependency.Repo = "https://github.com/$($dependency.Repo)"
            }
            if (-not ($dependency.PsObject.Properties.name -eq "Version")) {
                $dependency | Add-Member -name "Version" -MemberType NoteProperty -Value "latest"
@ -1145,7 +1158,7 @@ function CheckAppDependencyProbingPaths {
            }

            if ($dependency.release_status -eq "include") {
-                if ($dependency.Repo -ne "$ENV:GITHUB_SERVER_URL/$ENV:GITHUB_REPOSITORY") {
+                if ($dependency.Repo -ne "https://github.com/$repository") {
                    OutputWarning "Dependencies with release_status 'include' must be to other projects in the same repository."
                }
                else {
@ -1160,7 +1173,7 @@ function CheckAppDependencyProbingPaths {
                            $thisIncludeOnlyAppIds = @($dependencyIds + $includeOnlyAppIds + $dependency.alwaysIncludeApps)
                            $depSettings = ReadSettings -baseFolder $baseFolder -project $depProject -workflowName "CI/CD"
                            $depSettings = AnalyzeRepo -settings $depSettings -baseFolder $baseFolder -project $depProject -includeOnlyAppIds $thisIncludeOnlyAppIds -doNotCheckArtifactSetting -doNotIssueWarnings
-                            $depSettings = CheckAppDependencyProbingPaths -settings $depSettings -token $token -baseFolder $baseFolder -project $depProject -includeOnlyAppIds $thisIncludeOnlyAppIds
+                            $depSettings = CheckAppDependencyProbingPaths -settings $depSettings -token $token -baseFolder $baseFolder -repository $repository -project $depProject -includeOnlyAppIds $thisIncludeOnlyAppIds

                            $projectPath = Join-Path $baseFolder $project -Resolve
                            Push-Location $projectPath
@ -1503,6 +1516,7 @@ function CreateDevEnv {
        [string] $caller = 'local',
        [Parameter(Mandatory = $true)]
        [string] $baseFolder,
+        [string] $repository = "$ENV:GITHUB_REPOSITORY",
        [string] $project,
        [string] $userName = $env:Username,

@ -1530,6 +1544,16 @@ function CreateDevEnv {
        throw "Specified parameters doesn't match kind=$kind"
    }

+    if ("$repository" -eq "") {
+        Push-Location $baseFolder
+        try {
+            $repoInfo = invoke-gh -silent -returnValue repo view --json "owner,name" | ConvertFrom-Json
+            $repository = "$($repoInfo.owner.login)/$($repoInfo.name)"
+        }
+        finally {
+            Pop-Location
+        }
+    }
    $projectFolder = Join-Path $baseFolder $project -Resolve
    $dependenciesFolder = Join-Path $projectFolder ".dependencies"
    $runAlPipelineParams = @{}
@ -1660,7 +1684,7 @@ function CreateDevEnv {
            }
        }
        $settings = AnalyzeRepo -settings $settings -baseFolder $baseFolder -project $project @params
-        $settings = CheckAppDependencyProbingPaths -settings $settings -baseFolder $baseFolder -project $project
+        $settings = CheckAppDependencyProbingPaths -settings $settings -baseFolder $baseFolder -repository $repository -project $project

        if (!$accept_insiderEula -and ($settings.artifact -like 'https://bcinsider.blob.core.windows.net/*' -or $settings.artifact -like 'https://bcinsider.azureedge.net/*')) {
            Read-Host 'Press ENTER to accept the Business Central insider EULA (https://go.microsoft.com/fwlink/?linkid=2245051) or break the script to cancel'
--- a/Actions/AddExistingApp/action.yaml
+++ b/Actions/AddExistingApp/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Freddy Kristiansen
+name: Add Existing App
+author: Microsoft Corporation
 permissions:
  contents: write
  pull-requests: write
--- a/Actions/AnalyzeTests/action.yaml
+++ b/Actions/AnalyzeTests/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Freddy Kristiansen
+name: Analyze Tests
+author: Microsoft Corporation
 inputs:
  shell:
    description: Shell in which you want to run the action (powershell or pwsh)
--- a/Actions/BuildReferenceDocumentation/BuildReferenceDocumentation.HelperFunctions.ps1
+++ b/Actions/BuildReferenceDocumentation/BuildReferenceDocumentation.HelperFunctions.ps1
@ -0,0 +1,298 @@
+function DownloadAlDoc {
+    if ("$ENV:aldocPath" -eq "") {
+        Write-Host "Locating aldoc"
+        $artifactUrl = Get-BCArtifactUrl -storageAccount bcinsider -type sandbox -country core -select Latest -accept_insiderEula
+        Write-Host "Downloading aldoc"
+        $folder = Download-Artifacts $artifactUrl
+        $alLanguageVsix = Join-Path $folder '*.vsix' -Resolve
+        $tempFolder = Join-Path ([System.IO.Path]::GetTempPath()) ([Guid]::NewGuid().ToString())
+        Copy-Item -Path $alLanguageVsix -Destination "$($tempFolder).zip"
+        New-Item -Path $tempFolder -ItemType Directory | Out-Null
+        Write-Host "Extracting aldoc"
+        Expand-Archive -Path "$($tempFolder).zip" -DestinationPath $tempFolder -Force
+        Remove-Item -Path "$($tempFolder).zip" -Force
+        if ($IsLinux) {
+            $ENV:aldocPath = Join-Path $tempFolder 'extension/bin/linux/aldoc'
+        }
+        else {
+            $ENV:aldocPath = Join-Path $tempFolder 'extension/bin/win32/aldoc.exe'
+        }
+        if (-not (Test-Path $ENV:aldocPath)) {
+            throw "aldoc tool not found at $ENV:aldocPath"
+        }
+        if ($IsLinux) {
+            & /usr/bin/env sudo pwsh -command "& chmod +x $ENV:aldocPath"
+        }
+        Write-Host "Installing/Updating docfx"
+        CmdDo -command dotnet -arguments @("tool","update","-g docfx")
+    }
+    return $ENV:aldocPath
+}
+
+function SanitizeFileName([string] $fileName) {
+    $fileName.Replace('_','-').Replace('?','_').Replace('*','_').Replace(' ','-').Replace('\','-').Replace('/','-').Replace(':','-').Replace('<','-').Replace('>','-').Replace('|','-').Replace('%','pct')
+}
+
+function GetAppNameAndFolder {
+    Param(
+        [string] $appFile
+    )
+
+    $tmpFolder = Join-Path ([System.IO.Path]::GetTempPath()) ([Guid]::NewGuid().ToString())
+    Extract-AppFileToFolder -appFilename $appFile -appFolder $tmpFolder -generateAppJson
+    $appJson = Get-Content -Path (Join-Path $tmpFolder 'app.json') -Encoding utf8 | ConvertFrom-Json
+    $appJson.name
+    (SanitizeFileName -fileName $appJson.name).ToLower()
+    Remove-Item -Path $tmpFolder -Recurse -Force
+}
+
+function GenerateTocYml {
+    Param(
+        [string] $version,
+        [string[]] $allVersions,
+        [hashtable] $allApps,
+        [switch] $groupByProject
+    )
+
+    $prefix = ''
+    if ($version) {
+        # If $version is set, then we are generating reference documentation for a release
+        # all releases will be in a subfolder called releases/$version
+        # prefix is used to reference links in the root of the site relative to the site we are building now
+        # We cannot use / as prefix, because that will not work when hosting the site on GitHub pages
+        $prefix = "../../"
+    }
+    $tocYml = @(
+        "items:"
+        )
+    if ($allVersions.Count -gt 0) {
+        $tocYml += @(
+            "  - name: Releases"
+            "    items:"
+            "    - name: main"
+            "      href: $($prefix)index.html"
+            )
+        foreach($ver in $allVersions) {
+            $tocYml += @(
+                "    - name: $ver"
+                "      href: $($prefix)releases/$ver/index.html"
+                )
+        }
+    }
+    $allApps | ConvertTo-Json -Depth 99 | Out-Host
+    if ($allApps.Keys.Count -eq 1 -and $allApps.Keys[0] -eq $repoName) {
+        # Single project repo - do not use project names as folders
+        $groupByProject = $false
+    }
+    $projects = @($allApps.Keys.GetEnumerator() | Sort-Object)
+    foreach($project in $projects) {
+        if ($groupByProject) {
+            $tocYml += @(
+                "  - name: $project"
+                "    items:"
+                )
+            $indent = "    "
+        }
+        else {
+            $indent = "  "
+        }
+        $theseApps = @{}
+        # Get all apps for this project
+        foreach($appFile in $allApps."$project") {
+            $appName, $appFolder = GetAppNameAndFolder -appFile $appFile
+            $theseApps."$appName" = $appFolder
+        }
+        # Add all apps sorted by name
+        $theseApps.Keys.GetEnumerator() | Sort-Object | ForEach-Object {
+            $tocYml += @(
+                "$($indent)- name: $($_)"
+                "$($indent)  href: reference/$($theseApps."$_")/toc.yml"
+                )
+        }
+    }
+    $tocYml
+}
+
+
+#
+# Generate Reference documentation for a branch or a release.
+# All Apps to use for the ref. doc. are downloaded from the release or latest build of the branch.
+#
+function GenerateDocsSite {
+    Param(
+        [string] $version,
+        [string[]] $allVersions,
+        [hashtable] $allApps,
+        [string] $repoName,
+        [string] $releaseNotes,
+        [string] $header,
+        [string] $footer,
+        [string] $defaultIndexMD,
+        [string] $defaultReleaseMD,
+        [string] $docsPath,
+        [string] $logLevel,
+        [switch] $groupByProject,
+        [switch] $hostIt
+    )
+
+    function ReplacePlaceHolders {
+        Param(
+            [string] $str,
+            [string] $version = '',
+            [string] $releaseNotes = '',
+            [string] $indexTemplateRelativePath = ''
+        )
+        return $str.Replace('{REPOSITORY}',$ENV:GITHUB_REPOSITORY).Replace('{VERSION}',$version).Replace('{RELEASENOTES}',$releaseNotes).Replace('{INDEXTEMPLATERELATIVEPATH}',$indexTemplateRelativePath)
+    }
+
+    $indexTemplateRelativePath = '.aldoc/index.md'
+    if ($version) {
+        $thisTemplateRelativePath = '.aldoc/release.md'
+        $thisDefaultMD = $defaultReleaseMD
+    }
+    else {
+        $thisTemplateRelativePath = $indexTemplateRelativePath
+        $thisDefaultMD = $defaultIndexMD
+    }
+
+    $indexTemplatePath = Join-Path $ENV:GITHUB_WORKSPACE $thisTemplateRelativePath
+    if (-not (Test-Path $indexTemplatePath)) {
+        $indexTemplatePath = Join-Path $ENV:GITHUB_WORKSPACE $indexTemplateRelativePath
+    }
+    if (Test-Path $indexTemplatePath) {
+        $indexTemplate = Get-Content -Encoding utf8 -Path $indexTemplatePath -Raw
+    }
+    else {
+        $indexTemplate = $thisDefaultMD
+    }
+    $indexContent = ReplacePlaceHolders -str $indexTemplate -version $version -releaseNotes $releaseNotes -indexTemplateRelativePath $thisTemplateRelativePath
+
+    $alDocPath = DownloadAlDoc
+    $docfxPath = Join-Path ([System.IO.Path]::GetTempPath()) ([Guid]::NewGuid().ToString())
+    New-Item -Path $docfxPath -ItemType Directory | Out-Null
+    try {
+        # Generate new toc.yml with releases and apps
+        $newTocYml = GenerateTocYml -version $version -allVersions $allVersions -allApps $allApps -repoName $repoName -groupByProject $groupByProject
+
+        # calculate apps for aldoc
+        $apps = @()
+        foreach($value in $allApps.Values) {
+            $apps += @($value)
+        }
+        $apps = @($apps | Select-Object -Unique)
+
+        $arguments = @(
+            "init"
+            "--output ""$docfxpath"""
+            "--loglevel $loglevel"
+            "--targetpackages ""$($apps -join '","')"""
+            )
+        Write-Host "invoke aldoc $arguments"
+        CmdDo -command $aldocPath -arguments $arguments
+
+        # Update docfx.json
+        Write-Host "Update docfx.json"
+        $docfxJsonFile = Join-Path $docfxPath 'docfx.json'
+        $docfxJson = Get-Content -Encoding utf8 -Path $docfxJsonFile | ConvertFrom-Json
+        $docfxJson.build.globalMetadata._appName = ReplacePlaceHolders -str $header -version $version -releaseNotes $releaseNotes
+        $docfxJson.build.globalMetadata._appFooter = ReplacePlaceHolders -str $footer -version $version -releaseNotes $releaseNotes
+        $docfxJson | ConvertTo-Json -Depth 99 | Set-Content -Path $docfxJsonFile -Encoding utf8
+
+        Write-Host "docfx.json:"
+        Get-Content $docfxJsonFile | Out-Host
+
+        # Create new toc.yml
+        Write-Host "Create new toc.yml"
+        $tocYmlFile = Join-Path $docfxpath 'toc.yml'
+
+        Write-Host "Original TOC (from aldoc)):"
+        Get-Content $tocYmlFile | Out-Host
+
+        Set-Content -Path $tocYmlFile -Value ($newTocYml -join "`n") -Encoding utf8
+
+        Write-Host "TOC:"
+        Get-Content $tocYmlFile | Out-Host
+
+        $apps | ForEach-Object {
+            $arguments = @(
+                "build"
+                "--output ""$docfxpath"""
+                "--loglevel $loglevel"
+                "--source ""$_"""
+                )
+            Write-Host "invoke aldoc $arguments"
+            CmdDo -command $aldocPath -arguments $arguments
+        }
+
+        # Set release notes
+        Write-Host "Update index.md"
+        $indexMdFile = Join-Path $docfxpath 'index.md'
+        Set-Content -path $indexMdFile -value $indexContent -encoding utf8
+
+        Write-Host "index.md:"
+        Get-Content $indexMdFile | Out-Host
+
+        $arguments = @(
+            "build"
+            "--output ""$docsPath"""
+            "--logLevel $loglevel"
+            """$docfxJsonFile"""
+            )
+        if ($hostIt) {
+            $arguments += @("-s")
+            Write-Host "Generate and host site"
+        }
+        Write-Host "invoke doxfx $arguments"
+        CmdDo -command docfx -arguments $arguments
+    }
+    finally {
+        Remove-Item -Path $docfxPath -Recurse -Force
+    }
+}
+
+# Build a list of all projects (folders) and apps to use when building reference documentation
+# return value is a hashtable for all apps and a hashtable for all dependencies
+# Every hashtable has project name as key and an array of app files as value
+# if groupByProject is false, all apps will be collected in one "project" called "dummy", which is never displayed
+function CalculateProjectsAndApps {
+    Param(
+        [string] $tempFolder,
+        [string[]] $includeProjects,
+        [string[]] $excludeProjects,
+        [switch] $groupByProject
+    )
+
+    if ($includeProjects.Count -eq 0) { $includeProjects = @("*") }
+    $projectList = @($includeProjects | ForEach-Object { $_.Replace('\','_').Replace('/','_') })
+    Write-Host "Include Project Patterns"
+    $projectList | ForEach-Object { Write-Host "- $_" }
+    $excludeProjectList = @($excludeProjects | ForEach-Object { $_.Replace('\','_').Replace('/','_') })
+    Write-Host "Exclude Project Patterns"
+    $excludeProjectList | ForEach-Object { Write-Host "- $_" }
+    foreach($mask in 'Apps','Dependencies') {
+        $allApps = @{}
+        foreach($folder in (Get-ChildItem -Path $tempFolder | Where-Object { $_.PSIsContainer })) {
+            if (($folder.Name -match "^(.*)-main-$mask-(\d*\.\d*\.\d*\.\d*)$") -or
+                ($folder.Name -match "^(.*)-release.*-$mask-(\d*\.\d*\.\d*\.\d*)$")) {
+                $project = $Matches[1]
+                $includeIt = $null -ne ($projectList | Where-Object { $project -like $_ })
+                if ($includeIt) {
+                    $excludeIt = $null -ne ($excludeProjectList | Where-Object { $project -like $_ })
+                    if (-not $excludeIt) {
+                        if (-not $groupByProject) {
+                            # use project name dummy for all apps when not using projects as folders
+                            $project = 'dummy'
+                        }
+                        if (-not $allApps.ContainsKey("$project")) {
+                            $allApps."$project" = @()
+                        }
+                        Get-ChildItem -Path $folder.FullName -Filter '*.app' | ForEach-Object {
+                            $allApps."$project" += @($_.FullName)
+                        }
+                    }
+                }
+            }
+        }
+        $allApps
+    }
+}
--- a/Actions/BuildReferenceDocumentation/BuildReferenceDocumentation.ps1
+++ b/Actions/BuildReferenceDocumentation/BuildReferenceDocumentation.ps1
@ -0,0 +1,112 @@
+Param(
+    [Parameter(HelpMessage = "The GitHub token running the action", Mandatory = $false)]
+    [string] $token,
+    [Parameter(HelpMessage = "The artifacts to build documentation for or a folder in which the artifacts have been downloaded", Mandatory = $true)]
+    [string] $artifacts
+)
+
+. (Join-Path -Path $PSScriptRoot -ChildPath "..\AL-Go-Helper.ps1" -Resolve)
+. (Join-Path -Path $PSScriptRoot -ChildPath "BuildReferenceDocumentation.HelperFunctions.ps1" -Resolve)
+DownloadAndImportBcContainerHelper
+
+$settings = $env:Settings | ConvertFrom-Json
+$includeProjects = $settings.alDoc.includeProjects
+$excludeProjects = $settings.alDoc.excludeProjects
+$maxReleases = $settings.alDoc.maxReleases
+$artifactsFolder = Join-Path $ENV:GITHUB_WORKSPACE ".artifacts"
+$artifactsFolderCreated = $false
+if ($artifacts -ne ".artifacts") {
+    Write-Host "::group::Downloading artifacts"
+    $artifactsFolderCreated = $true
+    New-Item $artifactsFolder -ItemType Directory | Out-Null
+    $allArtifacts = @(GetArtifacts -token $token -api_url $ENV:GITHUB_API_URL -repository $ENV:GITHUB_REPOSITORY -mask "Apps" -projects '*' -Version $artifacts -branch $ENV:GITHUB_REF_NAME)
+    if ($allArtifacts) {
+        $allArtifacts | ForEach-Object {
+            $filename = DownloadArtifact -token $token -artifact $_ -path $artifactsFolder
+            if (!(Test-Path $filename)) {
+                throw "Unable to download artifact $($_.name)"
+            }
+            $destFolder = Join-Path $artifactsFolder ([System.IO.Path]::GetFileNameWithoutExtension($filename))
+            Expand-Archive -Path $filename -DestinationPath $destFolder -Force
+            Remove-Item -Path $filename -Force
+        }
+    }
+    Write-Host "::endgroup::"
+}
+
+$header = $settings.alDoc.header
+$footer = $settings.alDoc.footer
+$defaultIndexMD = $settings.alDoc.defaultIndexMD.Replace('\n',"`n")
+$defaultReleaseMD = $settings.alDoc.defaultReleaseMD.Replace('\n',"`n")
+
+$releases = @()
+if ($maxReleases -gt 0) {
+    $releases = GetReleases -token $token -api_url $ENV:GITHUB_API_URL -repository $ENV:GITHUB_REPOSITORY | Where-Object { $_ } | Where-Object { -not ($_.prerelease -or $_.draft) } | Select-Object -First $maxReleases
+}
+
+$docsPath = Join-Path $ENV:GITHUB_WORKSPACE ".aldoc"
+New-Item $docsPath -ItemType Directory | Out-Null
+$loglevel = 'Info'
+
+$versions = @($releases | ForEach-Object { $_.Name })
+$latestReleaseTag = $releases | Select-Object -First 1 -ExpandProperty tag_name
+
+foreach($release in $releases) {
+    $tempFolder = Join-Path ([System.IO.Path]::GetTempPath()) ([Guid]::NewGuid().ToString())
+    New-Item -Path $tempFolder -ItemType Directory | Out-Null
+    try {
+        Write-Host "::group::Release $($release.Name)"
+        foreach($mask in 'Apps', 'Dependencies') {
+            DownloadRelease -token $token -projects "$($includeProjects -join ',')" -api_url $ENV:GITHUB_API_URL -repository $ENV:GITHUB_REPOSITORY -release $release -path $tempFolder -mask $mask -unpack
+        }
+        Get-ChildItem -Path $tempFolder -Recurse -File | ForEach-Object { Write-Host "- $($_.FullName.Substring($tempFolder.Length+1))" }
+        $allApps, $allDependencies = CalculateProjectsAndApps -tempFolder $tempFolder -includeProjects $includeProjects -excludeProjects $excludeProjects -groupByProject:$settings.alDoc.groupByProject
+        $version = $release.Name
+        $releaseNotes = $release.body
+        GenerateDocsSite -version $version -allVersions $versions -allApps $allApps -repoName $settings.repoName -releaseNotes $releaseNotes -header $header -footer $footer -defaultIndexMD $defaultIndexMD -defaultReleaseMD $defaultReleaseMD -docsPath $docsPath -logLevel $logLevel -groupByProject:$settings.alDoc.groupByProject
+        do {
+            try {
+                $retry = $false
+                Start-Sleep -Seconds 2
+                Rename-Item -Path (join-Path $docsPath "_site") -NewName $version
+            }
+            catch {
+                $retry = $true
+            }
+        } while ($retry)
+        Write-Host "::endgroup::"
+    }
+    finally {
+        Remove-Item -Path $tempFolder -Recurse -Force
+    }
+}
+
+$releasesPath = Join-Path $docsPath "_site/releases"
+New-Item -Path $releasesPath -ItemType Directory | Out-Null
+foreach($version in $versions) {
+    Move-Item -Path (join-Path $docsPath $version) -Destination $releasesPath
+}
+
+Write-Host "::group::Main"
+
+Get-ChildItem -Path $artifactsFolder -Depth 1 -File | ForEach-Object { Write-Host "- $($_.FullName.Substring($artifactsFolder.Length))" }
+$allApps, $allDependencies = CalculateProjectsAndApps -tempFolder $artifactsFolder -includeProjects $includeProjects -excludeProjects $excludeProjects -groupByProject:$settings.alDoc.groupByProject
+$releaseNotes = ''
+if ($latestReleaseTag) {
+    try {
+        $releaseNotes = (GetReleaseNotes -token $token -tag_name 'main' -previous_tag_name $latestReleaseTag -target_commitish $ENV:GITHUB_SHA | ConvertFrom-Json).body
+    }
+    catch {
+        $releaseNotes = "## What's new`n`nError creating release notes"
+    }
+}
+else {
+    $releaseNotes = ''
+}
+GenerateDocsSite -version '' -allVersions $versions -allApps $allApps -repoName $settings.repoName -releaseNotes $releaseNotes -header $header -footer $footer -defaultIndexMD $defaultIndexMD -defaultReleaseMD $defaultReleaseMD -docsPath $docsPath -logLevel $logLevel -groupByProject:$settings.alDoc.groupByProject
+
+Write-Host "::endgroup::"
+
+if ($artifactsFolderCreated) {
+    Remove-Item $artifactsFolder -Recurse -Force
+}
--- a/Actions/BuildReferenceDocumentation/README.md
+++ b/Actions/BuildReferenceDocumentation/README.md
@ -0,0 +1,19 @@
+# BuildReferenceDocumentation
+Build documentation using [ALDoc](https://go.microsoft.com/fwlink/?linkid=2247728) and [DocFx](https://dotnet.github.io/docfx)
+
+## INPUT
+
+### ENV variables
+| Name | Description |
+| :-- | :-- |
+| Settings | env.Settings must be set by a prior call to the ReadSettings Action |
+
+### Parameters
+| Name | Required | Description | Default value |
+| :-- | :-: | :-- | :-- |
+| shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell |
+| token | | The GitHub token running the action | github.token |
+| artifacts | Yes | The artifacts to build documentation for or a folder in which the artifacts have been downloaded | |
+
+## OUTPUT
+none
--- a/Actions/BuildReferenceDocumentation/action.yaml
+++ b/Actions/BuildReferenceDocumentation/action.yaml
@ -0,0 +1,34 @@
+name: Build Reference Documentation
+author: Microsoft Corporation
+inputs:
+  shell:
+    description: Shell in which you want to run the action (powershell or pwsh)
+    required: false
+    default: powershell
+  token:
+    description: The GitHub token running the action
+    required: false
+    default: ${{ github.token }}
+  artifacts:
+    description: The artifacts to build documentation for or a folder in which the artifacts have been downloaded
+    required: true
+runs:
+  using: composite
+  steps:
+    - name: run
+      shell: ${{ inputs.shell }}
+      env:
+        _token: ${{ inputs.token }}
+        _artifacts: ${{ inputs.artifacts }}
+      run: |
+        $errorActionPreference = "Stop"; $ProgressPreference = "SilentlyContinue"; Set-StrictMode -Version 2.0
+        try {
+          ${{ github.action_path }}/BuildReferenceDocumentation.ps1 -token $ENV:_token -artifacts $ENV:_artifacts
+        }
+        catch {
+          Write-Host "::ERROR::Unexpected error when running action. Error Message: $($_.Exception.Message.Replace("`r",'').Replace("`n",' ')), StackTrace: $($_.ScriptStackTrace.Replace("`r",'').Replace("`n",' <- '))";
+          exit 1
+        }
+branding:
+  icon: terminal
+  color: blue
--- a/Actions/CalculateArtifactNames/action.yaml
+++ b/Actions/CalculateArtifactNames/action.yaml
@ -1,4 +1,4 @@
-name: PowerShell script
+name: Calculate Artifact Names
 author: Microsoft Corporation
 inputs:
  shell:
--- a/Actions/CheckForUpdates/CheckForUpdates.HelperFunctions.ps1
+++ b/Actions/CheckForUpdates/CheckForUpdates.HelperFunctions.ps1
@ -78,9 +78,9 @@ function ModifyPullRequestHandlerWorkflow {
        [Yaml] $yaml,
        [hashtable] $repoSettings
    )
-    # The PullRequestHandler workflow can have a RepoSetting called PullRequestTrigger which specifies the trigger to use for Pull Requests
+    # 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):"
+    $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
@ -92,7 +92,7 @@ function ModifyPullRequestHandlerWorkflow {
    }

    # update the branches: line with the new branches
-    $yaml.Replace("on:/$($repoSettings.PullRequestTrigger):/branches:", "branches: [ '$($CICDPullRequestBranches -join "', '")' ]")
+    $yaml.Replace("on:/$($repoSettings.pullRequestTrigger):/branches:", "branches: [ '$($CICDPullRequestBranches -join "', '")' ]")
 }

 function ModifyRunsOnAndShell {
--- a/Actions/CheckForUpdates/action.yaml
+++ b/Actions/CheckForUpdates/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Freddy Kristiansen
+name: Check For Updates
+author: Microsoft Corporation
 permissions:
  contents: write
  pull-requests: write
--- a/Actions/CreateApp/action.yaml
+++ b/Actions/CreateApp/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Freddy Kristiansen
+name: Create App
+author: Microsoft Corporation
 permissions:
  contents: write
  pull-requests: write
--- a/Actions/CreateDevelopmentEnvironment/action.yaml
+++ b/Actions/CreateDevelopmentEnvironment/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Freddy Kristiansen
+name: Create Development Environment
+author: Microsoft Corporation
 permissions:
  contents: write
  pull-requests: write
--- a/Actions/CreateReleaseNotes/action.yaml
+++ b/Actions/CreateReleaseNotes/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Pooya Kharamesh
+name: Create Release Notes
+author: Microsoft Corporation
 permissions:
  contents: write
  pull-requests: write
--- a/Actions/Deliver/Deliver.ps1
+++ b/Actions/Deliver/Deliver.ps1
@ -9,7 +9,7 @@
    [string] $projects = "*",
    [Parameter(HelpMessage = "Delivery target (AppSource or Storage)", Mandatory = $true)]
    [string] $deliveryTarget,
-    [Parameter(HelpMessage = "Artifacts to deliver", Mandatory = $true)]
+    [Parameter(HelpMessage = "The artifacts to deliver or a folder in which the artifacts have been downloaded", Mandatory = $true)]
    [string] $artifacts,
    [Parameter(HelpMessage = "Type of delivery (CD or Release)", Mandatory = $false)]
    [ValidateSet('CD','Release')]
--- a/Actions/Deliver/README.md
+++ b/Actions/Deliver/README.md
@ -18,7 +18,7 @@ Deliver App to deliveryTarget (AppSource, Storage, or...)
 | parentTelemetryScopeJson | | Specifies the parent telemetry scope for the telemetry signal | {} |
 | projects | | Comma-separated list of projects to deliver | * |
 | deliveryTarget | Yes | Delivery target (AppSource, Storage, GitHubPackages,...) | |
-| artifacts | Yes | The artifacts to deliver | |
+| artifacts | Yes | The artifacts to deliver or a folder in which the artifacts have been downloaded | |
 | type | | Type of delivery (CD or Release) | CD |
 | atypes | | Artifact types to deliver | Apps,Dependencies,TestApps |
 | goLive | | Only relevant for AppSource delivery type. Promote AppSource App to Go Live? | false |
--- a/Actions/Deliver/action.yaml
+++ b/Actions/Deliver/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Freddy Kristiansen
+name: Deliver
+author: Microsoft Corporation
 inputs:
  shell:
    description: Shell in which you want to run the action (powershell or pwsh)
@ -25,7 +25,7 @@ inputs:
    description: Delivery target (AppSource or Storage)
    required: true
  artifacts:
-    description: Artifacts to deliver
+    description: The artifacts to deliver or a folder in which the artifacts have been downloaded
    required: true
  type:
    description: Type of delivery (CD or Release)
--- a/Actions/Deploy/Deploy.ps1
+++ b/Actions/Deploy/Deploy.ps1
@ -5,7 +5,7 @@
    [string] $parentTelemetryScopeJson = '7b7d',
    [Parameter(HelpMessage = "Name of environment to deploy to", Mandatory = $true)]
    [string] $environmentName,
-    [Parameter(HelpMessage = "Artifacts to deploy", Mandatory = $true)]
+    [Parameter(HelpMessage = "The artifacts to deploy or a folder in which the artifacts have been downloaded", Mandatory = $true)]
    [string] $artifacts,
    [Parameter(HelpMessage = "Type of deployment (CD or Publish)", Mandatory = $false)]
    [ValidateSet('CD','Publish')]
@ -201,7 +201,7 @@ try {
                Write-Host "Publishing apps using development endpoint"
                Publish-BcContainerApp @parameters -useDevEndpoint -checkAlreadyInstalled -excludeRuntimePackages
            }
-            elseif (!$sandboxEnvironment -and $type -eq 'CD' -and !($deploymentSettings.ContinuousDeployment)) {
+            elseif (!$sandboxEnvironment -and $type -eq 'CD' -and !($deploymentSettings.continuousDeployment)) {
                # Continuous deployment is undefined in settings - we will not deploy to production environments
                Write-Host "::Warning::Ignoring environment $($deploymentSettings.EnvironmentName), which is a production environment"
            }
--- a/Actions/Deploy/README.md
+++ b/Actions/Deploy/README.md
@ -18,7 +18,7 @@ Deploy Apps to online environment
 | parentTelemetryScopeJson | | Specifies the parent telemetry scope for the telemetry signal | {} |
 | projects | | Comma-separated list of projects to deploy. | |
 | environmentName | Yes | Name of environment to deploy to |
-| artifacts | Yes | Artifacts to deploy |
+| artifacts | Yes | The artifacts to deploy or a folder in which the artifacts have been downloaded | |
 | type | | Type of delivery (CD or Release) | CD |

 ## OUTPUT
--- a/Actions/Deploy/action.yaml
+++ b/Actions/Deploy/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Freddy Kristiansen
+name: Deploy
+author: Microsoft Corporation
 inputs:
  shell:
    description: Shell in which you want to run the action (powershell or pwsh)
@ -17,7 +17,7 @@ inputs:
    description: Name of environment to deploy to
    required: true
  artifacts:
-    description: Artifacts to deploy
+    description: The artifacts to deploy or a folder in which the artifacts have been downloaded
    required: true
  type:
    description: Type of deployment (CD or Publish)
--- a/Actions/DetermineArtifactUrl/action.yaml
+++ b/Actions/DetermineArtifactUrl/action.yaml
@ -1,4 +1,4 @@
-name: Determine ArtifactUrl to use
+name: Determine ArtifactUrl
 author: Microsoft Corporation
 inputs:
  shell:
--- a/Actions/DetermineDeploymentEnvironments/DetermineDeploymentEnvironments.ps1
+++ b/Actions/DetermineDeploymentEnvironments/DetermineDeploymentEnvironments.ps1
@ -6,6 +6,19 @@
    [string] $type
 )

+function IsGitHubPagesAvailable() {
+    $headers = GetHeader -token $env:GITHUB_TOKEN
+    $url = "$($ENV:GITHUB_API_URL)/repos/$($ENV:GITHUB_REPOSITORY)/pages"
+    try {
+        Write-Host "Requesting GitHub Pages settings from GitHub"
+        $ghPages = InvokeWebRequest -Headers $headers -Uri $url -ignoreErrors | ConvertFrom-Json
+        return ($ghPages.build_type -eq 'workflow')
+    }
+    catch {
+        return $false
+    }
+}
+
 function GetGitHubEnvironments() {
    $headers = GetHeader -token $env:GITHUB_TOKEN
    $url = "$($ENV:GITHUB_API_URL)/repos/$($ENV:GITHUB_REPOSITORY)/environments"
@ -46,6 +59,27 @@ function Get-BranchesFromPolicy($ghEnvironment) {
 . (Join-Path -Path $PSScriptRoot -ChildPath "..\AL-Go-Helper.ps1" -Resolve)

 $settings = $env:Settings | ConvertFrom-Json | ConvertTo-HashTable -recurse
+
+$includeGitHubPages = $getEnvironments.Split(',') | Where-Object { 'github-pages' -like $_ }
+$generateALDocArtifact = ($includeGitHubPages) -and (($type -eq 'Publish') -or $settings.alDoc.continuousDeployment)
+Add-Content -Encoding UTF8 -Path $env:GITHUB_OUTPUT -Value "GenerateALDocArtifact=$([int]$generateALDocArtifact)"
+Write-Host "GenerateALDocArtifact=$([int]$generateALDocArtifact)"
+
+$deployToGitHubPages = $settings.alDoc.DeployToGitHubPages
+if ($generateALDocArtifact -and $deployToGitHubPages) {
+    $deployToGitHubPages = IsGitHubPagesAvailable
+    if (!$deployToGitHubPages) {
+        Write-Host "::Warning::GitHub Pages is not available in this repository (or GitHub Pages is not set to use GitHub Actions). Go to Settings -> Pages and set Source to GitHub Actions"
+    }
+}
+Add-Content -Encoding UTF8 -Path $env:GITHUB_OUTPUT -Value "DeployALDocArtifact=$([int]$deployToGitHubPages)"
+Write-Host "DeployALDocArtifact=$([int]$deployToGitHubPages)"
+
+if ($getEnvironments -eq 'github-pages') {
+    # if github-pages is specified as environment - only include if GitHub Pages is available
+    exit 0
+}
+
 Write-Host "Environment pattern to use: $getEnvironments"
 $ghEnvironments = @(GetGitHubEnvironments)

@ -71,7 +105,7 @@ if (!($environments)) {
                "BranchesFromPolicy" = @()
                "Projects" = '*'
                "SyncMode" = $null
-                "ContinuousDeployment" = !($getEnvironments -like '* (PROD)' -or $getEnvironments -like '* (Production)' -or $getEnvironments -like '* (FAT)' -or $getEnvironments -like '* (Final Acceptance Test)')
+                "continuousDeployment" = !($getEnvironments -like '* (PROD)' -or $getEnvironments -like '* (Production)' -or $getEnvironments -like '* (FAT)' -or $getEnvironments -like '* (Final Acceptance Test)')
                "runs-on" = @($settings."runs-on".Split(',').Trim())
            }
        }
@ -103,7 +137,7 @@ else {
            "BranchesFromPolicy" = @()
            "Projects" = '*'
            "SyncMode" = $null
-            "ContinuousDeployment" = $null
+            "continuousDeployment" = $null
            "runs-on" = @($settings."runs-on".Split(',').Trim())
        }

--- a/Actions/DetermineDeploymentEnvironments/README.md
+++ b/Actions/DetermineDeploymentEnvironments/README.md
@ -21,5 +21,7 @@ Determines the environments to be used for a build or a publish
 | DeploymentEnvironmentsJson | Deployment Environments with settings in compressed JSON format |
 | EnvironmentCount | Number of Deployment Environments |
 | UnknownEnvironment | Flag determining whether we try to publish to an unknown environment (invoke device code flow) |
+| GenerateALDocArtifact | Flag determining whether to generate the ALDoc artifact |
+| DeployALDocArtifact | Flag determining whether to deploy the ALDoc artifact to GitHub Pages |

 ### ENV variables
--- a/Actions/DetermineDeploymentEnvironments/action.yaml
+++ b/Actions/DetermineDeploymentEnvironments/action.yaml
@ -24,6 +24,12 @@ outputs:
  UnknownEnvironment:
    description: Flag determining whether the environment is unknown
    value: ${{ steps.determineDeploymentEnvironments.outputs.UnknownEnvironment }}
+  GenerateALDocArtifact:
+    description: Flag determining whether to generate the ALDoc artifact
+    value: ${{ steps.determineDeploymentEnvironments.outputs.GenerateALDocArtifact }}
+  DeployALDocArtifact:
+    description: Flag determining whether to deploy the ALDoc artifact to GitHub Pages
+    value: ${{ steps.determineDeploymentEnvironments.outputs.DeployALDocArtifact }}
 runs:
  using: composite
  steps:
--- a/Actions/Github-Helper.psm1
+++ b/Actions/Github-Helper.psm1
@ -123,7 +123,8 @@ function GetDependencies {
    Param(
        $probingPathsJson,
        [string] $api_url = $ENV:GITHUB_API_URL,
-        [string] $saveToPath = (Join-Path $ENV:GITHUB_WORKSPACE ".dependencies")
+        [string] $saveToPath = (Join-Path $ENV:GITHUB_WORKSPACE ".dependencies"),
+        [string[]] $masks = @('Apps','Dependencies','TestApps')
    )

    if (!(Test-Path $saveToPath)) {
@ -131,7 +132,7 @@ function GetDependencies {
    }

    $downloadedList = @()
-    foreach($mask in 'Apps','Dependencies','TestApps') {
+    foreach($mask in $masks) {
        foreach($dependency in $probingPathsJson) {
            $projects = $dependency.projects
            $buildMode = $dependency.buildMode
@ -574,7 +575,7 @@ function GetReleaseNotes {
    Write-Host "Generating release note $api_url/repos/$repository/releases/generate-notes"

    $postParams = @{
-        tag_name = $tag_name;
+        tag_name = $tag_name
    }

    if ($previous_tag_name) {
@ -595,6 +596,7 @@ function DownloadRelease {
        [string] $repository = $ENV:GITHUB_REPOSITORY,
        [string] $path,
        [string] $mask = "Apps",
+        [switch] $unpack,
        $release
    )

@ -616,6 +618,15 @@ function DownloadRelease {
            Write-Host $uri
            $filename = Join-Path $path $asset.name
            InvokeWebRequest -Headers $headers -Uri $uri -OutFile $filename
+            if ($unpack) {
+                $unzipPath = Join-Path $path $asset.name.Replace('.zip','')
+                if (Test-Path $unzipPath) {
+                    Remove-Item $unzipPath -Recurse -Force
+                }
+                Expand-Archive -Path $filename -DestinationPath $unzipPath
+                Remove-Item $filename -Force
+                $filename = $unzipPath
+            }
            $filename
        }
    }
--- a/Actions/IncrementVersionNumber/action.yaml
+++ b/Actions/IncrementVersionNumber/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Freddy Kristiansen
+name: Increment Version Number
+author: Microsoft Corporation
 permissions:
  contents: write
  pull-requests: write
--- a/Actions/PipelineCleanup/action.yaml
+++ b/Actions/PipelineCleanup/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Freddy Kristiansen
+name: Pipeline Cleanup
+author: Microsoft Corporation
 inputs:
  shell:
    description: Shell in which you want to run the action (powershell or pwsh)
--- a/Actions/ReadSecrets/action.yaml
+++ b/Actions/ReadSecrets/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Freddy Kristiansen
+name: Read Secrets
+author: Microsoft Corporation
 inputs:
  shell:
    description: Shell in which you want to run the action (powershell or pwsh)
--- a/Actions/ReadSettings/action.yaml
+++ b/Actions/ReadSettings/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Freddy Kristiansen
+name: Read Settings
+author: Microsoft Corporation
 inputs:
  shell:
    description: Shell in which you want to run the action (powershell or pwsh)
--- a/Actions/RunPipeline/action.yaml
+++ b/Actions/RunPipeline/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Freddy Kristiansen
+name: Run Pipeline
+author: Microsoft Corporation
 inputs:
  shell:
    description: Shell in which you want to run the action (powershell or pwsh)
--- a/Actions/VerifyPRChanges/action.yaml
+++ b/Actions/VerifyPRChanges/action.yaml
@ -1,4 +1,4 @@
-name: PowerShell script
+name: Verify PR Changes
 author: Microsoft Corporation
 inputs:
  shell:
--- a/Actions/WorkflowInitialize/action.yaml
+++ b/Actions/WorkflowInitialize/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Pooya Kharamesh
+name: Workflow Initialize
+author: Microsoft Corporation
 inputs:
  shell:
    description: Shell in which you want to run the action (powershell or pwsh)
--- a/Actions/WorkflowPostProcess/action.yaml
+++ b/Actions/WorkflowPostProcess/action.yaml
@ -1,5 +1,5 @@
-name: PowerShell script
-author: Pooya Kharamesh
+name: Workflow Post Process
+author: Microsoft Corporation
 inputs:
  shell:
    description: Shell in which you want to run the action (powershell or pwsh)
--- a/RELEASENOTES.md
+++ b/RELEASENOTES.md
@ -18,6 +18,27 @@ If false, the templateSha repository setting is used to download specific AL-Go
 - 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.

+### 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.
+
+### 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
--- a/Scenarios/settings.md
+++ b/Scenarios/settings.md
@ -51,17 +51,19 @@ The repository settings are only read from the repository settings file (.github
 | <a id="nextMajorSchedule"></a>nextMajorSchedule | CRON schedule for when NextMajor workflow should run. Default is no scheduled run, only manual trigger. Build your CRON string here: [https://crontab.guru](https://crontab.guru) |
 | <a id="nextMinorSchedule"></a>nextMinorSchedule | CRON schedule for when NextMinor workflow should run. Default is no scheduled run, only manual trigger. Build your CRON string here: [https://crontab.guru](https://crontab.guru) |
 | <a id="currentSchedule"></a>currentSchedule | CRON schedule for when Current workflow should run. Default is no scheduled run, only manual trigger. Build your CRON string here: [https://crontab.guru](https://crontab.guru) |
+| <a id="DeployReferenceDocumentationSchedule"></a>deployReferenceDocumentationSchedule | CRON schedule for when the Deploy Reference Documentation workflow should run. Default is no scheduled run, only manual trigger. Build your CRON string here: [https://crontab.guru](https://crontab.guru) |
 | <a id="runs-on"></a>runs-on | Specifies which github runner will be used for all non-build/test jobs in all workflows (except the Update AL-Go System Files workflow). The default is to use the GitHub hosted runner _windows-latest_. You can specify a special GitHub Runner for the build job using the GitHubRunner setting. Read [this](SelfHostedGitHubRunner.md) for more information.<br />Setting runs-on to _ubuntu-latest_ will run all non-build/test jobs on Linux, build jobs will still run _windows-latest_ (or whatever you have set in **githubRunner**) |
 | <a id="shell"></a>shell | Specifies which shell will be used as the default in all jobs. **powershell** is the default, which results in using _PowerShell 5.1_ (unless you selected _ubuntu-latest_, then **pwsh** is used, which results in using _PowerShell 7_) |
 | <a id="githubRunner"></a>githubRunner | Specifies which github runner will be used for the build/test jobs in workflows including a build job. This is the most time consuming task. By default this job uses the _Windows-latest_ github runner (unless overridden by the runs-on setting). This settings takes precedence over runs-on so that you can use different runners for the build job and the housekeeping jobs. See **runs-on** setting. |
 | <a id="githubRunnerShell"></a>githubRunnerShell | Specifies which shell is used for build jobs in workflows including a build job. The default is to use the same as defined in **shell**. If the shell setting isn't defined, **powershell** is the default, which results in using _PowerShell 5.1_. Use **pwsh** for _PowerShell 7_. |
-| <a id="environments"></a>environments | Array of logical environment names. You can specify environments in GitHub environments or in the repo settings file. If you specify environments in the settings file, you can create your AUTHCONTEXT secret using **&lt;environmentname&gt;_AUTHCONTEXT**. You can specify additional information about environments in a setting called **DeployTo&lt;environmentname&gt;** | [ ] |
-| <a id="deliverto"></a>DeliverTo&lt;deliveryTarget&gt; | Structure with additional properties for the deliveryTarget specified. Some properties are deliveryTarget specific. The structure can contain the following properties:<br />**Branches** = an array of branch patterns, which are allowed to deliver to this deliveryTarget. (Default main)<br />**CreateContainerIfNotExist** = *[Only for DeliverToStorage]* Create Blob Storage Container if it doesn't already exist. (Default false)<br /> | { } |
-| <a id="deployto"></a>DeployTo&lt;environmentname&gt; | Structure with additional properties for the environment specified. The structure can contain the following properties:<br />**EnvironmentType** = specifies the type of environment. The environment type can be used to invoke a custom deployment. (Default SaaS)<br />**EnvironmentName** = specifies the "real" name of the environment if it differs from the GitHub environment.<br />**Branches** = an array of branch patterns, which are allowed to deploy to this environment. (Default main)<br />**Projects** = In multi-project repositories, this property can be a comma-separated list of project patterns to deploy to this environment. (Default *)<br />**SyncMode** = ForceSync if deployment to this environment should happen with ForceSync, else Add. If deploying to the development endpoint you can also specify Development or Clean. (Default Add)<br />**ContinuousDeployment** = true if this environment should be used for continuous deployment, else false. (Default: AL-Go will continuously deploy to sandbox environments or environments, which doesn't end in (PROD) or (FAT)<br />**runs-on** = specifies which runner to use when deploying to this environment. (Default is settings.runs-on)<br /> | { } |
+| <a id="environments"></a>environments | Array of logical environment names. You can specify environments in GitHub environments or in the repo settings file. If you specify environments in the settings file, you can create your AUTHCONTEXT secret using **&lt;environmentname&gt;_AUTHCONTEXT**. You can specify additional information about environments in a setting called **DeployTo&lt;environmentname&gt;** |
+| <a id="deliverto"></a>DeliverTo&lt;deliveryTarget&gt; | Structure with additional properties for the deliveryTarget specified. Some properties are deliveryTarget specific. The structure can contain the following properties:<br />**Branches** = an array of branch patterns, which are allowed to deliver to this deliveryTarget. (Default main)<br />**CreateContainerIfNotExist** = *[Only for DeliverToStorage]* Create Blob Storage Container if it doesn't already exist. (Default false)<br /> |
+| <a id="deployto"></a>DeployTo&lt;environmentname&gt; | Structure with additional properties for the environment specified. The structure can contain the following properties:<br />**EnvironmentType** = specifies the type of environment. The environment type can be used to invoke a custom deployment. (Default SaaS)<br />**EnvironmentName** = specifies the "real" name of the environment if it differs from the GitHub environment.<br />**Branches** = an array of branch patterns, which are allowed to deploy to this environment. (Default main)<br />**Projects** = In multi-project repositories, this property can be a comma separated list of project patterns to deploy to this environment. (Default *)<br />**SyncMode** = ForceSync if deployment to this environment should happen with ForceSync, else Add. If deploying to the development endpoint you can also specify Development or Clean. (Default Add)<br />**ContinuousDeployment** = true if this environment should be used for continuous deployment, else false. (Default: AL-Go will continuously deploy to sandbox environments or environments, which doesn't end in (PROD) or (FAT)<br />**runs-on** = specifies which runner to use when deploying to this environment. (Default is settings.runs-on)<br /> |
+| <a id="aldoc"></a>alDoc | Structure with properties for the aldoc reference document generation. The structure can contain the following properties:<br />**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)<br />**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 Actuibs. (Default true)<br />**maxReleases** = Maximum number of releases to include in the reference documentation. (Default 3)<br />**groupByProject** = Determines whether projects in multi-project repositories are used as folders in reference documentation<br />**includeProjects** = An array of projects to include in the reference documentation. (Default all)<br />**excludeProjects** = An array of projects to exclude in the reference documentation. (Default none)<br />**header** = Header for the documentation site. (Default: Documentation for...)<br />**footer** = Footer for the documentation site. (Default: Made with...)<br />**defaultIndexMD** = Markdown for the landing page of the documentation site. (Default: Reference documentation...)<br />**defaultReleaseMD** = Markdown for the landing page of the release sites. (Default: Release reference documentation...)<br />*Note that in header, footer, defaultIndexMD and defaultReleaseMD you can use the following placeholders: {REPOSITORY}, {VERSION}, {INDEXTEMPLATERELATIVEPATH}, {RELEASENOTES}* |
 | <a id="useProjectDependencies"></a>useProjectDependencies | Determines whether your projects are built using a multi-stage built workflow or single stage. After setting useProjectDependencies to true, you need to run Update AL-Go System Files and your workflows including a build job will change to have multiple build jobs, depending on each other. The number of build jobs will be determined by the dependency depth in your projects.<br />You can change dependencies between your projects, but if the dependency **depth** changes, AL-Go will warn you that updates for your AL-Go System Files are available and you will need to run the workflow. |
 | <a id="CICDPushBranches"></a>CICDPushBranches | CICDPushBranches can be specified as an array of branches, which triggers a CI/CD workflow on commit.<br />Default is [ "main", "release/\*", "feature/\*" ] |
 | <a id="CICDPullrequestBranches"></a>CICDPullRequestBranches | CICDPullRequestBranches can be specified as an array of branches, which triggers a CI/CD workflow on a PR.<br />Default is [ "main" ] |
-| <a id="PullRequestTrigger"></a>PullRequestTrigger | Setting for specifying the trigger AL-Go should use to trigger Pull Request Builds. By default it is set to [pull_request_target](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target) |
+| <a id="pullRequestTrigger"></a>pullRequestTrigger | Setting for specifying the trigger AL-Go should use to trigger Pull Request Builds. By default it is set to [pull_request_target](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target) |
 | <a id="CICDSchedule"></a>CICDSchedule | CRON schedule for when CI/CD workflow should run. Default is no scheduled run, only manually triggered or triggered by Push or Pull Request. Build your CRON string here: [https://crontab.guru](https://crontab.guru) |
 | <a id="UpdateGitHubGoSystemFilesSchedule"></a>UpdateGitHubGoSystemFilesSchedule | CRON schedule for when Update AL-Go System Files should run. When Update AL-Go System Files runs on a schedule, it uses direct Commit instead of creating a PR. Default is no scheduled run, only manual trigger. Build your CRON string here: [https://crontab.guru](https://crontab.guru) |
 | <a id="buildModes"></a>buildModes | A list of build modes to use when building the AL-Go projects. Every AL-Go projects will be built using each built mode. Available build modes are:<br /> **Default**: Apps are compiled as they are in the source code.<br />**Clean**: _PreprocessorSymbols_ are enabled when compiling the apps. The values for the symbols correspond to the `cleanModePreprocessorSymbols` setting of the AL-Go project.<br />**Translated**: `TranslationFile` compiler feature is enabled when compiling the apps. |
@ -104,7 +106,7 @@ The repository settings are only read from the repository settings file (.github
 | <a id="assignPremiumPlan"></a>assignPremiumPlan | Setting assignPremiumPlan to true in your project setting file, causes the build container to be created with the AssignPremiumPlan set. This causes the auto-created user to have Premium Plan enabled. This setting is needed if your tests require premium plan enabled. | false |
 | <a id="enableTaskScheduler"></a>enableTaskScheduler | Setting enableTaskScheduler to true in your project setting file, causes the build container to be created with the Task Scheduler running. | false |
 | <a id="useCompilerFolder"></a>useCompilerFolder | Setting useCompilerFolder to true causes your pipelines to use containerless compiling. Unless you also set **doNotPublishApps** to true, setting useCompilerFolder to true won't give you any performance advantage, since AL-Go for GitHub will still need to create a container in order to publish and test the apps. In the future, publishing and testing will be split from building and there will be other options for getting an instance of Business Central for publishing and testing. | false |
-| <a id="excludeEnvironments"></a>excludeEnvironments | excludeEnvironments can be an array of GitHub Environments, which should be excluded from the list of environments considered for deployment. github_pages is automatically added to this array and cannot be used as environment for deployment of AL-Go for GitHub projects. | [ ] |
+| <a id="excludeEnvironments"></a>excludeEnvironments | excludeEnvironments can be an array of GitHub Environments, which should be excluded from the list of environments considered for deployment. github-pages is automatically added to this array and cannot be used as environment for deployment of AL-Go for GitHub projects. | [ ] |

 ## AppSource specific advanced settings

--- a/App/.github/workflows/CICD.yaml
+++ b/App/.github/workflows/CICD.yaml
@ -31,6 +31,8 @@ jobs:
      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 }}
@ -155,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/ReadSettings@main
+        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/BuildReferenceDocumentation@main
+        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
@ -248,7 +297,7 @@ jobs:
          artifacts: '.artifacts'

  PostProcess:
-    needs: [ Initialization, Build, Deploy, Deliver ]
+    needs: [ Initialization, Build, Deploy, Deliver, DeployALDoc ]
    if: (!cancelled())
    runs-on: [ windows-latest ]
    steps:
--- a/App/.github/workflows/DeployReferenceDocumentation.yaml
+++ b/App/.github/workflows/DeployReferenceDocumentation.yaml
@ -0,0 +1,71 @@
+name: ' Deploy Reference Documentation'
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  actions: read
+  pages: write
+  id-token: write
+
+defaults:
+  run:
+    shell: powershell
+
+env:
+  ALGoOrgSettings: ${{ vars.ALGoOrgSettings }}
+  ALGoRepoSettings: ${{ vars.ALGoRepoSettings }}
+
+jobs:
+  DeployALDoc:
+    runs-on: [ windows-latest ]
+    name: Deploy Reference Documentation
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Initialize the workflow
+        id: init
+        uses: microsoft/AL-Go-Actions/WorkflowInitialize@main
+        with:
+          shell: powershell
+          eventId: "DO0097"
+        
+      - name: Read settings
+        uses: microsoft/AL-Go-Actions/ReadSettings@main
+        with:
+          shell: powershell
+
+      - name: Determine Deployment Environments
+        id: DetermineDeploymentEnvironments
+        uses: microsoft/AL-Go-Actions/DetermineDeploymentEnvironments@main
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        with:
+          shell: powershell
+          getEnvironments: 'github-pages'
+          type: 'Publish'
+            
+      - name: Setup Pages
+        if: steps.DetermineDeploymentEnvironments.outputs.deployALDocArtifact == 1
+        uses: actions/configure-pages@v3
+        
+      - name: Build Reference Documentation
+        uses: microsoft/AL-Go-Actions/BuildReferenceDocumentation@main
+        with:
+          shell: powershell
+          artifacts: 'latest'
+        
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ".aldoc/_site/"
+        
+      - name: Deploy to GitHub Pages
+        if: steps.DetermineDeploymentEnvironments.outputs.deployALDocArtifact == 1
+        id: deployment
+        uses: actions/deploy-pages@v2
--- a/Extension/.github/workflows/CICD.yaml
+++ b/Extension/.github/workflows/CICD.yaml
@ -31,6 +31,8 @@ jobs:
      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 }}
@ -155,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/ReadSettings@main
+        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/BuildReferenceDocumentation@main
+        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
@ -248,7 +297,7 @@ jobs:
          artifacts: '.artifacts'

  PostProcess:
-    needs: [ Initialization, Build, Deploy, Deliver ]
+    needs: [ Initialization, Build, Deploy, Deliver, DeployALDoc ]
    if: (!cancelled())
    runs-on: [ windows-latest ]
    steps:
--- a/Extension/.github/workflows/DeployReferenceDocumentation.yaml
+++ b/Extension/.github/workflows/DeployReferenceDocumentation.yaml
@ -0,0 +1,71 @@
+name: ' Deploy Reference Documentation'
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  actions: read
+  pages: write
+  id-token: write
+
+defaults:
+  run:
+    shell: powershell
+
+env:
+  ALGoOrgSettings: ${{ vars.ALGoOrgSettings }}
+  ALGoRepoSettings: ${{ vars.ALGoRepoSettings }}
+
+jobs:
+  DeployALDoc:
+    runs-on: [ windows-latest ]
+    name: Deploy Reference Documentation
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Initialize the workflow
+        id: init
+        uses: microsoft/AL-Go-Actions/WorkflowInitialize@main
+        with:
+          shell: powershell
+          eventId: "DO0097"
+        
+      - name: Read settings
+        uses: microsoft/AL-Go-Actions/ReadSettings@main
+        with:
+          shell: powershell
+
+      - name: Determine Deployment Environments
+        id: DetermineDeploymentEnvironments
+        uses: microsoft/AL-Go-Actions/DetermineDeploymentEnvironments@main
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        with:
+          shell: powershell
+          getEnvironments: 'github-pages'
+          type: 'Publish'
+            
+      - name: Setup Pages
+        if: steps.DetermineDeploymentEnvironments.outputs.deployALDocArtifact == 1
+        uses: actions/configure-pages@v3
+        
+      - name: Build Reference Documentation
+        uses: microsoft/AL-Go-Actions/BuildReferenceDocumentation@main
+        with:
+          shell: powershell
+          artifacts: 'latest'
+        
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ".aldoc/_site/"
+        
+      - name: Deploy to GitHub Pages
+        if: steps.DetermineDeploymentEnvironments.outputs.deployALDocArtifact == 1
+        id: deployment
+        uses: actions/deploy-pages@v2
--- a/Tests/BuildReferenceDocumentation.Action.Test.ps1
+++ b/Tests/BuildReferenceDocumentation.Action.Test.ps1
@ -0,0 +1,64 @@
+Get-Module TestActionsHelper | Remove-Module -Force
+Import-Module (Join-Path $PSScriptRoot 'TestActionsHelper.psm1')
+
+Describe "BuildReferenceDocumentation Action Tests" {
+    BeforeAll {
+        $actionName = "BuildReferenceDocumentation"
+        $scriptRoot = Join-Path $PSScriptRoot "..\Actions\$actionName" -Resolve
+        $scriptName = "$actionName.ps1"
+        [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'scriptPath', Justification = 'False positive.')]
+        $scriptPath = Join-Path $scriptRoot $scriptName
+        [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'actionScript', Justification = 'False positive.')]
+        $actionScript = GetActionScript -scriptRoot $scriptRoot -scriptName $scriptName
+    }
+
+    It 'Compile Action' {
+        Invoke-Expression $actionScript
+    }
+
+    It 'Test action.yaml matches script' {
+        $permissions = [ordered]@{
+        }
+        $outputs = [ordered]@{
+        }
+        YamlTest -scriptRoot $scriptRoot -actionName $actionName -actionScript $actionScript -permissions $permissions -outputs $outputs
+    }
+
+    It 'CalculateProjectsAndApps' {
+        . (Join-Path $scriptRoot 'BuildReferenceDocumentation.HelperFunctions.ps1')
+
+        Mock Get-ChildItem {
+            if ($filter -eq '*.app') {
+                $project = [System.IO.Path]::GetFileName($path).Substring(0,2)
+                $noOfApps = [int]$project.substring(1,1)
+                $apps = @()
+                for($i=1; $i -le $noOfApps; $i++) {
+                    $apps += [PSCustomObject]@{ FullName = Join-Path $path "$($project)_app$i.app" }
+                }
+                return $apps
+            }
+            else {
+                return @(
+                    [PSCustomObject]@{ Name = 'P1-main-Apps-1.0.0.0'; FullName = Join-Path $path 'P1-main-Apps-1.0.0.0'; "PsIsContainer" = $true }
+                    [PSCustomObject]@{ Name = 'P2-main-Apps-1.0.0.0'; FullName = Join-Path $path 'P2-main-Apps-1.0.0.0'; "PsIsContainer" = $true }
+                    [PSCustomObject]@{ Name = 'P3-main-Apps-1.0.0.0'; FullName = Join-Path $path 'P3-main-Apps-1.0.0.0'; "PsIsContainer" = $true }
+                    [PSCustomObject]@{ Name = 'P4-main-Apps-1.0.0.0'; FullName = Join-Path $path 'P4-main-Apps-1.0.0.0'; "PsIsContainer" = $true }
+                )
+            }
+        }
+
+        $allApps = CalculateProjectsAndApps -tempFolder (Get-Location).Path -includeProjects @('P1','P2') -excludeProjects @('P3')
+        $allApps.Count | Should -Be 2
+        $allApps[0].Keys.Count | Should -be 1
+        $allApps[0].ContainsKey('dummy') | Should -be $true
+        $allApps[0]."dummy".Count | Should -be 3
+
+        $allApps = CalculateProjectsAndApps -tempFolder (Get-Location).Path -includeProjects @('*') -excludeProjects @('P3') -groupByProject
+        $allApps.Count | Should -Be 2
+        $allApps[0].Keys.Count | Should -be 3
+        $allApps[0].ContainsKey('dummy') | Should -be $false
+        $allApps[0]."P1".Count | Should -be 1
+        $allApps[0]."P2".Count | Should -be 2
+        $allApps[0]."P4".Count | Should -be 4
+    }
+}
--- a/Tests/DetermineDeploymentEnvironments.Test.ps1
+++ b/Tests/DetermineDeploymentEnvironments.Test.ps1
@ -44,6 +44,8 @@ Describe "DetermineDeploymentEnvironments Action Test" {
            "DeploymentEnvironmentsJson" = "Deployment Environments with settings in compressed JSON format"
            "EnvironmentCount" = "Number of Deployment Environments"
            "UnknownEnvironment" = "Flag determining whether the environment is unknown"
+            "GenerateALDocArtifact" = "Flag determining whether to generate the ALDoc artifact"
+            "DeployALDocArtifact" = "Flag determining whether to deploy the ALDoc artifact to GitHub Pages"
        }
        YamlTest -scriptRoot $scriptRoot -actionName $actionName -actionScript $actionScript -permissions $permissions -outputs $outputs
    }
@ -54,17 +56,17 @@ Describe "DetermineDeploymentEnvironments Action Test" {
            return (ConvertTo-Json -Compress -Depth 99 -InputObject @{ "environments" = @( @{ "name" = "test"; "protection_rules" = @() }, @{ "name" = "another"; "protection_rules" = @() } ) })
        }

-        $env:Settings = @{ "type" = "PTE"; "runs-on" = "ubuntu-latest"; "environments" = @(); "excludeEnvironments" = @( 'github_pages' ) } | ConvertTo-Json -Compress
+        $env:Settings = @{ "type" = "PTE"; "runs-on" = "ubuntu-latest"; "environments" = @(); "excludeEnvironments" = @( 'github-pages' ); "alDoc" = @{ "continuousDeployment" = $false; "deployToGitHubPages" = $false } } | ConvertTo-Json -Compress
        . (Join-Path $scriptRoot $scriptName) -getEnvironments '*' -type 'CD'
        PassGeneratedOutput
        $EnvironmentsMatrixJson | ConvertFrom-Json | ConvertTo-HashTable -recurse | Should -MatchHashtable @{"matrix"=@{"include"=@(@{"environment"="another";"os"="[""ubuntu-latest""]"};@{"environment"="test";"os"="[""ubuntu-latest""]"})};"fail-fast"=$false}
-        $DeploymentEnvironmentsJson | ConvertFrom-Json | ConvertTo-HashTable -recurse | Should -MatchHashtable @{"test"=@{"EnvironmentType"="SaaS";"EnvironmentName"="test";"Branches"=@();"BranchesFromPolicy"=@();"Projects"="*";"SyncMode"=$null;"ContinuousDeployment"=$null;"runs-on"=@("ubuntu-latest")};"another"=@{"EnvironmentType"="SaaS";"EnvironmentName"="another";"Branches"=@();"BranchesFromPolicy"=@();"Projects"="*";"SyncMode"=$null;"ContinuousDeployment"=$null;"runs-on"=@("ubuntu-latest")}}
+        $DeploymentEnvironmentsJson | ConvertFrom-Json | ConvertTo-HashTable -recurse | Should -MatchHashtable @{"test"=@{"EnvironmentType"="SaaS";"EnvironmentName"="test";"Branches"=@();"BranchesFromPolicy"=@();"Projects"="*";"SyncMode"=$null;"continuousDeployment"=$null;"runs-on"=@("ubuntu-latest")};"another"=@{"EnvironmentType"="SaaS";"EnvironmentName"="another";"Branches"=@();"BranchesFromPolicy"=@();"Projects"="*";"SyncMode"=$null;"continuousDeployment"=$null;"runs-on"=@("ubuntu-latest")}}
        $EnvironmentCount | Should -Be 2

        . (Join-Path $scriptRoot $scriptName) -getEnvironments 'test' -type 'CD'
        PassGeneratedOutput
        $EnvironmentsMatrixJson | ConvertFrom-Json | ConvertTo-HashTable -recurse | Should -MatchHashtable @{"matrix"=@{"include"=@(@{"environment"="test";"os"="[""ubuntu-latest""]"})};"fail-fast"=$false}
-        $DeploymentEnvironmentsJson | ConvertFrom-Json | ConvertTo-HashTable -recurse | Should -MatchHashtable @{"test"=@{"EnvironmentType"="SaaS";"EnvironmentName"="test";"Branches"=@();"BranchesFromPolicy"=@();"Projects"="*";"SyncMode"=$null;"ContinuousDeployment"=$null;"runs-on"=@("ubuntu-latest")}}
+        $DeploymentEnvironmentsJson | ConvertFrom-Json | ConvertTo-HashTable -recurse | Should -MatchHashtable @{"test"=@{"EnvironmentType"="SaaS";"EnvironmentName"="test";"Branches"=@();"BranchesFromPolicy"=@();"Projects"="*";"SyncMode"=$null;"continuousDeployment"=$null;"runs-on"=@("ubuntu-latest")}}
        $EnvironmentCount | Should -Be 1
    }

@ -77,11 +79,11 @@ Describe "DetermineDeploymentEnvironments Action Test" {
            return (ConvertTo-Json -Compress -Depth 99 -InputObject @( @{ "name" = "branch"; "protected" = $true }, @{ "name" = "main"; "protected" = $false } ))
        }

-        $env:Settings = @{ "type" = "PTE"; "runs-on" = "ubuntu-latest"; "environments" = @(); "excludeEnvironments" = @( 'github_pages' ) } | ConvertTo-Json -Compress
+        $env:Settings = @{ "type" = "PTE"; "runs-on" = "ubuntu-latest"; "environments" = @(); "excludeEnvironments" = @( 'github-pages' ); "alDoc" = @{ "continuousDeployment" = $false; "deployToGitHubPages" = $false } } | ConvertTo-Json -Compress
        . (Join-Path $scriptRoot $scriptName) -getEnvironments '*' -type 'CD'
        PassGeneratedOutput
        $EnvironmentsMatrixJson | ConvertFrom-Json | ConvertTo-HashTable -recurse | Should -MatchHashtable @{"matrix"=@{"include"=@(@{"environment"="another";"os"="[""ubuntu-latest""]"})};"fail-fast"=$false}
-        $DeploymentEnvironmentsJson | ConvertFrom-Json | ConvertTo-HashTable -recurse | Should -MatchHashtable @{"another"=@{"EnvironmentType"="SaaS";"EnvironmentName"="another";"Branches"=@();"BranchesFromPolicy"=@();"Projects"="*";"SyncMode"=$null;"ContinuousDeployment"=$null;"runs-on"=@("ubuntu-latest")}}
+        $DeploymentEnvironmentsJson | ConvertFrom-Json | ConvertTo-HashTable -recurse | Should -MatchHashtable @{"another"=@{"EnvironmentType"="SaaS";"EnvironmentName"="another";"Branches"=@();"BranchesFromPolicy"=@();"Projects"="*";"SyncMode"=$null;"continuousDeployment"=$null;"runs-on"=@("ubuntu-latest")}}
        $EnvironmentCount | Should -Be 1

        $env:GITHUB_REF_NAME = 'branch'
@ -102,12 +104,12 @@ Describe "DetermineDeploymentEnvironments Action Test" {
            return @{ "branch_policies" = @( @{ "name" = "branch" }, @{ "name" = "branch2" } ) } | ConvertTo-Json -Depth 99 -Compress
        }

-        $env:Settings = @{ "type" = "PTE"; "runs-on" = "ubuntu-latest"; "environments" = @(); "excludeEnvironments" = @( 'github_pages' ) } | ConvertTo-Json -Compress
+        $env:Settings = @{ "type" = "PTE"; "runs-on" = "ubuntu-latest"; "environments" = @(); "excludeEnvironments" = @( 'github-pages' ); "alDoc" = @{ "continuousDeployment" = $false; "deployToGitHubPages" = $false } } | ConvertTo-Json -Compress
        # Only another environment should be included when deploying from main
        . (Join-Path $scriptRoot $scriptName) -getEnvironments '*' -type 'CD'
        PassGeneratedOutput
        $EnvironmentsMatrixJson | ConvertFrom-Json | ConvertTo-HashTable -recurse | Should -MatchHashtable @{"matrix"=@{"include"=@(@{"environment"="another";"os"="[""ubuntu-latest""]"})};"fail-fast"=$false}
-        $DeploymentEnvironmentsJson | ConvertFrom-Json | ConvertTo-HashTable -recurse | Should -MatchHashtable @{"another"=@{"EnvironmentType"="SaaS";"EnvironmentName"="another";"Branches"=@();"BranchesFromPolicy"=@();"Projects"="*";"SyncMode"=$null;"ContinuousDeployment"=$null;"runs-on"=@("ubuntu-latest")}}
+        $DeploymentEnvironmentsJson | ConvertFrom-Json | ConvertTo-HashTable -recurse | Should -MatchHashtable @{"another"=@{"EnvironmentType"="SaaS";"EnvironmentName"="another";"Branches"=@();"BranchesFromPolicy"=@();"Projects"="*";"SyncMode"=$null;"continuousDeployment"=$null;"runs-on"=@("ubuntu-latest")}}
        $EnvironmentCount | Should -Be 1
        ($EnvironmentsMatrixJson | ConvertFrom-Json | ConvertTo-HashTable -recurse).matrix.include.environment | Should -Contain "another"

@ -150,7 +152,7 @@ Describe "DetermineDeploymentEnvironments Action Test" {
            return (ConvertTo-Json -Compress -Depth 99 -InputObject @{ "environments" = @( @{ "name" = "test"; "protection_rules" = @() }; @{ "name" = "another"; "protection_rules" = @() } ) })
        }

-        $settings = @{ "type" = "PTE"; "runs-on" = "ubuntu-latest"; "environments" = @("settingsenv"); "excludeEnvironments" = @( 'github_pages' ) }
+        $settings = @{ "type" = "PTE"; "runs-on" = "ubuntu-latest"; "environments" = @("settingsenv"); "excludeEnvironments" = @( 'github-pages' ); "alDoc" = @{ "continuousDeployment" = $false; "deployToGitHubPages" = $false } }
        $env:Settings = $settings | ConvertTo-Json -Compress
        . (Join-Path $scriptRoot $scriptName) -getEnvironments '*' -type 'CD'
        PassGeneratedOutput
@ -191,7 +193,7 @@ Describe "DetermineDeploymentEnvironments Action Test" {
        }

        # One PROD environment and one non-PROD environment - only non-PROD environment is selected for CD
-        $settings = @{ "type" = "PTE"; "runs-on" = "ubuntu-latest"; "environments" = @("test (PROD)","another"); "excludeEnvironments" = @( 'github_pages' ) }
+        $settings = @{ "type" = "PTE"; "runs-on" = "ubuntu-latest"; "environments" = @("test (PROD)","another"); "excludeEnvironments" = @( 'github-pages' ); "alDoc" = @{ "continuousDeployment" = $false; "deployToGitHubPages" = $false } }
        $env:Settings = $settings | ConvertTo-Json -Compress
        . (Join-Path $scriptRoot $scriptName) -getEnvironments '*' -type 'CD'
        PassGeneratedOutput
@ -208,7 +210,7 @@ Describe "DetermineDeploymentEnvironments Action Test" {

    # 2 environments defined in Settings - one PROD and one non-PROD (settings based)
    It 'Test calling action directly - 2 environments defined in Settings - one PROD and one non-PROD (settings based)' {
-        $settings = @{ "type" = "PTE"; "runs-on" = "ubuntu-latest"; "environments" = @("test (PROD)","another"); "excludeEnvironments" = @( 'github_pages' ) }
+        $settings = @{ "type" = "PTE"; "runs-on" = "ubuntu-latest"; "environments" = @("test (PROD)","another"); "excludeEnvironments" = @( 'github-pages' ); "alDoc" = @{ "continuousDeployment" = $false; "deployToGitHubPages" = $false } }

        Mock InvokeWebRequest -ParameterFilter { $uri -like '*/environments' } -MockWith {
            throw "Not supported"
@ -216,10 +218,10 @@ Describe "DetermineDeploymentEnvironments Action Test" {

        $settings += @{
            "DeployToTest" = @{
-                "ContinuousDeployment" = $false
+                "continuousDeployment" = $false
            }
            "DeployToAnother" = @{
-                "ContinuousDeployment" = $true
+                "continuousDeployment" = $true
            }
        }

--- a/Workshop/AddAnApp.md
+++ b/Workshop/AddAnApp.md
@ -14,40 +14,44 @@ Enter the following values in the form:

 | Name | Value |
 | :-- | :-- |
+| Use workflow from | `Branch: main` |
 | Project name | `.` |
 | Name | `app1` |
 | Publisher | `<your publisher name>` |
 | ID Range (from..to) | `55000..55100` |
-| Include Sample Code | `yes` |
-| Direct Commit | `no` |
+| Include Sample Code | :ballot_box_with_check: |
+| Direct Commit | :black_square_button: |
+| Use GhTokenWorkflow | :black_square_button: |

-| ![image](https://user-images.githubusercontent.com/10775043/231540732-4a1ef920-abe2-4611-a2b0-9ac9a8310e3b.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/b556ae00-469c-4156-9b1b-925ee4632e4d) |
 |-|

 Wait a few minutes until the workflow completes and click **Pull requests** to see that there is a Pull request open for review.

-| ![image](https://user-images.githubusercontent.com/10775043/231541168-7f38a62a-84a3-4d31-9e44-4836f51ec9c0.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/295d2d32-1101-4471-af30-9192e63c1a3d) |
 |-|

 Open the **Pull request** and click **Files changed** to see what the Pull request will add to your repository.

-| ![image](https://user-images.githubusercontent.com/10775043/231541315-9c738120-3b16-4746-b066-1e22345fb1a8.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/79081ae2-2d98-41e0-9abd-25e5da4cfec8) |
 |-|

-The changes made by the workflow includes adding the new app path to the **al.code-workspace**, and adding an app folder with **app.json**, **HelloWorld.al** (sample code) and **.vscode/launch.json**.
+> [!NOTE]
+> The changes made by the workflow includes adding the new app path to the **al.code-workspace**, and adding an app folder with **app.json**, **HelloWorld.al** (sample code) and **.vscode/launch.json**.
 The **Create a new app** workflow doesn't do anything else than just adding these changes, no magic behind the scenes.

 Select **Conversation** and merge the pull request by clicking **Merge the pull request**, **Confirm merge** and then delete the temporary branch created for the pull request, by clicking **Delete branch**. Select **Actions** and see that a merge commit workflow was kicked off:

-| ![image](https://user-images.githubusercontent.com/10775043/231541665-e9a29056-e681-42fc-b272-ff0fd0ce3d94.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/80b1c400-7ce2-4511-a9e2-febb7da9f171) |
 |-|

 When the merge commit is **done**, click the workflow line and **scroll down** to see the artifacts created by this build:

-| ![image](https://user-images.githubusercontent.com/10775043/231544822-71bf956d-a050-4d18-b429-69fdb08083f9.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/ba90341f-75f5-47f3-be7f-b00e49e4ba19) |
 |-|

-Note that my artifacts are created with version **1.0.2.0** - that might not be the same in your repository.
+> [!NOTE]
+> My artifacts are created with version **1.0.4.0** - that might not be the same in your repository.

 Let's talk about versioning and naming...

--- a/Workshop/AutomatedTests.md
+++ b/Workshop/AutomatedTests.md
@ -1,49 +1,57 @@
 # Automated Tests
 In order to run automated tests, you need to change a few things in settings.

-During prerequisites we added two AL-Go settings:
+During prerequisites we added two AL-Go settings to the ALGOORGSETTINGS organizational variable:

-```
-  "useCompilerFolder": true
+```json
+  "useCompilerFolder": true,
  "doNotPublishApps": true
 ```

-These settings means that AL-Go will use a CompilerFolder to compile the apps instead of a container and that we will never actually publish the apps (meaning that Test runs are also disabled).
+These settings means that AL-Go will use a CompilerFolder functionality to compile the apps instead of a container and that we will never actually publish the apps (meaning that Test runs are also disabled).

 In this step, we will add a test app to the single-project repository and see how AL-Go handles test runs and test results.

-So, navigate to your single-project repository, locate the .github/AL-Go-Settings.json file and add the following two settings:
+So, navigate single-project repository, locate the .github/AL-Go-Settings.json file and add the following two settings:

-```
-  "useCompilerFolder": false
+```json
+  "useCompilerFolder": false,
  "doNotPublishApps": false
 ```

-| ![image](https://user-images.githubusercontent.com/10775043/232327081-6c6f7be3-fa18-41d2-98b3-ff540a953125.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/3860cb67-67d6-4954-966d-df6923dbfe56) |
 |-|

 Now select **Actions** and locate the **Create a new test app** action and click **Run workflow** and use the following parameters:

 | Name | Value |
 | :-- | :-- |
+| Use workflow from | `Branch: main` |
 | Project name | `.` |
 | Name | `app1.test` |
 | Publisher | `<your publisher name>` |
 | ID Range (from..to) | `70000..99999` |
-| Include Sample Code | `yes` |
-| Direct Commit | `no` |
+| Include Sample Code | :ballot_box_with_check: |
+| Direct Commit | :black_square_button: |
+| Use GhTokenWorkflow | :black_square_button: |

-| ![image](https://user-images.githubusercontent.com/10775043/232327235-bd4350f7-d05f-423b-a69b-0b0c226180b3.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/4e4d69e2-2b65-4ed0-b56b-91270d5a7410) |
 |-|

-Inspect and **merge** the pull request. Now completion of the merge pull request **will be much slower than before**, as the GitHub hosted runners needs to download the Business Central Generic image and the artifacts every single time. When the workflow is done, you should see that below the artifacts produced by the **CI/CD** workflow, there is a summary field with the test results.
+When the workflow is complete, inspect and **merge** the pull request.

-| ![image](https://user-images.githubusercontent.com/10775043/232337935-f20f3e8b-94a7-42cf-a97a-37ce09f9a479.png) |
+> [!NOTE]
+> Completion of the merge pull request **will be much slower than before**, as the GitHub hosted runners needs to download the Business Central Generic image and the artifacts every single time.
+
+When the workflow is done, you should see that below the artifacts produced by the **CI/CD** workflow, there is a summary field with the test results.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/fb2aa04d-d75b-4651-8e4d-a7d76451a536) |
 |-|

 As already mentioned, running complete builds with full tests does take more time than containerless compiling. We are working on improving this.

-Our recommendation is that you run your full test suite during **CI/CD**, but it is possible with **AL-Go for GitHub**, to not run the tests during **CI/CD** and then postpone them to a nightly test run using a scheduled run of the **Test Current** workflow.
+> [!NOTE]
+> Our recommendation is that you run your full test suite during **CI/CD**, but it is possible with **AL-Go for GitHub**, to not run the tests during **CI/CD** and then postpone them to a nightly test run using a scheduled run of the **Test Current** workflow.

 So, let's see what it takes to setup scheduled runs for running the tests with **latest** or **future versions** of Business Central?

--- a/Workshop/ContinuousDelivery.md
+++ b/Workshop/ContinuousDelivery.md
@ -5,6 +5,7 @@ Currently, the following targets are supported:
 - GitHub Packages
 - Storage
 - AppSource
+- NuGet (work in progress)
 - Custom

 This workshop has already described how to setup continuous delivery for GitHub Packages [here](Dependencies2.md).
@ -12,30 +13,64 @@ This workshop has already described how to setup continuous delivery for GitHub
 ## Storage
 Setting up continuous delivery to a storage account is done in the same mechanism as we did with GitHub Packages.

-Create an organizational secret called **StorageContext**. The format of the secret needs to be **compressed JSON**, containing 4 values: **StorageAccountName**, **StorageAccountKey**, **ContainerName** and **BlobName**. Example:
+In order to setup **continuous delivery** to a **storage account**, you need to have an Azure Account and setup a storage account in the **Azure Portal**. You can create a **blob container** with the name of the the calculated container (based on containerName in the StorageContext) or you can add a setting called **DeliverToStorage** in your repository settings gile (.github/AL-Go-Settings.json) with a property called **CreateContainerIfNotExist** set to true for auto generation of the blob container. 
+
+```json
+  "DeliverToStorage": {
+    "CreateContainerIfNotExist": true
+  }
 ```
+
+Now, create an organizational secret called **StorageContext**. The format of the secret needs to be **compressed JSON**, containing 4 values: **storageAccountName**, **containerName**, **blobName** and either **storageAccountKey** or **sasToken**. Example:
+
+```json
 {"StorageAccountName":"accountnanme","StorageAccountKey":"HOaRhoNXXX==","containerName":"{project}","blobName":"{version}/{project}-{type}.zip"}
 ```

-ContainerName and BlobName can contain "variable", like {project}, {version} and {type} which will be replaced by the real values when delivering.
+or

-In order to setup **continuous delivery** to a **storage account**, you need to have an Azure Account and setup a storage account in the **Azure Portal**, and create a **blob container** with the name of the the calculated container (based on containerName in the StorageContext). After this, create the secret above manually or use the **New-ALGoStorageContext** from BcContainerHelper.
+```json
+{"storageAccountName":"accountnanme","sasToken":"?sv=2021-10-04\u0026ss=b\u0026srt=sco...","containerName":"{project}","blobName":"{version}/{project}-{type}.zip"}
+```

-| ![image](https://user-images.githubusercontent.com/10775043/232289028-e73c8395-b39d-49d7-9e5b-52eb8e8c8db4.png) |
+ContainerName and BlobName can contain placeholders, like {project}, {version} and {type} which will be replaced by the real values when delivering.
+
+> [!NOTE]
+> You can use the **BcContainerHelper** function **New-ALGoStorageContext** to assist in the correct format of the secret.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/7287e068-b2d5-4fc2-b428-d0ddd4ffa0e3) |
 |-|

-and when running **CI/CD** afterwards, you will see that continuous delivery is now setup for a storage account as well
+Now create an organizational secret called **StorageContext** with the secret value.

-| ![image](https://user-images.githubusercontent.com/10775043/232289443-9109d260-8009-470f-950a-b8960ab2a44e.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/3e5b4ddc-bff2-4cf5-9b2a-1a3696189eaf) |
+|-|
+
+and add the deliverToStorage setting to the ALGOORGSETTINGS organizational variable:
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/6b7b4072-67d0-40b2-87ae-bfa2d130162b) |
+|-|
+
+When re-running **CI/CD** afterwards, you will see that continuous delivery is now setup for a storage account as well
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/def2c115-e8c2-46dd-a7f8-4f745a93c2fb) |
+|-|
+
+Checking the storage account using Storage Explorer reveals the new container and the new app.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/5b8317ca-64c2-4c10-9cf2-53bf61c4af07) |
 |-|

 ## AppSource
 Continuous delivery to **AppSource** is supported by the AppSource template and will be included in the workshop later, but basically, creating a secret called **AppSourceContext** and setting a **AppSourceContinuousDelivery** to true in the repository settings file.

+## NuGet
+Still work-in-progress. Delivery to NuGet is supposed to be delivery to a NuGet feed, where your partners can get access to your apps or runtime packages. This section will be updated when we release delivery to NuGet in it's final version.
+
 ## Custom delivery
 Custom delivery will be handled in an advanced part of this workshop later.

-OK, so **CD** stands for **Continuous Delivery**, I thought it was **Continuous Deployment**? Well, it is both, so let's talk about **Continuous Deployment**...
+OK, so **CD** stands for **Continuous Delivery**, I thought it was **Continuous Deployment**? Well, it is actually both, so let's talk about **Continuous Deployment**...

 ---
 [Index](Index.md)&nbsp;&nbsp;[next](ContinuousDeployment.md)
--- a/Workshop/ContinuousDeployment.md
+++ b/Workshop/ContinuousDeployment.md
@ -1,57 +1,81 @@
 # Continuous Deployment

-Continuous Deployment is currently only supporting sandox environments (like **QA** or **FAT** environments)
+Using Continuous Deployment you can deploy your apps to an online environment continuously. Much like with continuous delivery, you need to setup an authentication context and then you need to setup an environment.

-Much like with continuous delivery, you need to setup an authentication context and then you need to setup an environment.
+> [!NOTE]
+> The authentication context can use **impersonation** (which uses a **refreshtoken**, which typically is valid for **90** days) or **S2S** (which uses **ClientId** and **ClientSecret**, which needs to be **registered** inside your **Business Central Environment**.

-The authentication context can use **impersonation** (which uses a **refreshtoken** that is valid for **90** days) or **S2S** (which uses **ClientId** and **ClientSecret**, which needs to be **registered** inside your **Business Central Environment**.
+First thing we need to do is to create an **environment** in your **GitHub repository** with a name, which identifies your Business Central environment.

-First thing we need to do is to create an **environment** in your **GitHub repository**, which the same name as your Business Central environment.
+Navigate to your single-project repository (**repo1**), select **Settings** -> **Environments** and click **New environment**. Enter a name for your Business Central environment and click **Configure environment**

-Navigate to your single-project repository (**repo1**), select **Settings** and **Environments** and click **New environment**. Enter the name of your Business Central environment and click **Configure environment**
-
-| ![image](https://user-images.githubusercontent.com/10775043/232294280-cc92b21b-f5ae-4381-b63b-e05b72159486.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/72dc1a40-bb14-4e2a-9d8a-35f36bf623a3) |
 |-|

-In the environment configuration screen, Click **Add secret** under **environment secrets**. Create a secret called AUTHCONTEXT and use one of the two mechanisms described below to create the auth context value:
+In the environment configuration screen, Click **Add secret** under **Environment secrets**. Create a secret called AUTHCONTEXT and use one of the two mechanisms described below to create the auth context value:

-## Using Impersonation
-Easiest way to create an authentication context with impersonation for AL-Go for GitHub is to use the following PowerShell line from a machine with the BcContainerHelper module installed:
+> [!NOTE]
+> The Environments tab in repository **Settings** is only supported in **paid SKUs** of GitHub or for **public repositories**. It is possible to use repository or organizational secrets for authenticating to environments defined in **Settings**, as an alternative to using environment secrets as we have done here, but this is not part of this workshop.

+After creating the environment and the AUTHCONTEXT secret, you should create a setting structure called DeployTo followed by your GitHub environment name. Read more about the DeployTo setting [here](https://aka.ms/algosettings#DeployTo)).
+If your actual Business Central environment has a different name than your GitHub environment, you can add an EnvironmentName property to the DeliverTo settings like:
+
+```json
+  "DeployToMy-QA": {
+    "EnvironmentName": "QA",
+    "continuousDeployment": true
+  }
 ```
+
+At this time, these settings cannot be added as environment variables, we might add this in the future.
+
+## Creating an AUTHCONTEXT that uses impersonation
+Easiest way to create an authentication context with impersonation for AL-Go for GitHub is to use the following PowerShell line from a machine with the latest **BcContainerHelper** module installed:
+
+```powershell
 New-BcAuthContext -includeDeviceLogin | New-ALGoAuthContext | set-Clipboard
 ```

-This command will display the well-known device login text: To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code XXXXXXX to authenticate.
+This command will display the well-known device login text: **To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code XXXXXXX to authenticate.**

 Complete the login with a Business Central user, which has access to deploy applications in the environment setup for continuous deployment. This will generate an Aothorization context for the environment and Copy it automatically to your clipboard.

 Return to the "Add Secret" dialog from the environment configuration screen, paste the secret into the "Value" field, and click **Add secret**.

-| ![image](https://user-images.githubusercontent.com/10775043/232296180-7ef20c2c-6a2a-4127-b524-7646512994e2.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/7d825d02-a22f-41fc-b291-08dea0685676) |
 |-|

 Now, select **Actions** and select the **CI/CD** workflow and click **Run workflow**. Inspect the workflow and see that deployment now also deploys your apps:

-| ![image](https://user-images.githubusercontent.com/10775043/232300284-49ca8a4c-bd91-46b8-9608-76f4a6289f0f.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/2e390351-f9a5-49a5-a50c-25671022633c) |
 |-|

-Note that you need to update the AuthContext secret every 90 days for now.
+The URL under the deployment will navigate to the environment.

-## Using S2S
-For using **S2S**, you need to do some preparation first. Follow [this](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/automation-apis-using-s2s-authentication) description to setup an **AAD App** and register it inside the **Business Central environment** you want to deploy to.
+Opening the Business Central environment and navigating to **Extension Management** reveals that both apps from repo1 has been installed in the development scope. If the environment was a production environment, the apps would have been installed in the Global Scope as Per Tenant Extensions.

-Once this is done, you can then create an Authentication context secret by using this PowerShell line from a machine with the BcContainerHelper module installed:
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/40e5f9de-319c-4151-aa31-98a32732bfce) |
+|-|

-```
+> [!NOTE]
+> You need to update the AuthContext secret every 90 days for now.
+
+## Creating an AUTHCONTEXT that uses S2S
+For using **S2S**, you need to do some preparation first. Follow [this](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/automation-apis-using-s2s-authentication) description to setup a **Microsoft Entra application** and register it inside the **Business Central environment** you want to deploy to.
+
+Once this is done, you can then create an Authentication context secret by using this PowerShell line from a machine with the latest BcContainerHelper module installed:
+
+```powershell
 New-BcAuthContext -clientID $clientID -clientSecret $clientSecret -tenantID $tenantID | New-ALGoAuthContext | Set-Clipboard
 ```

 Paste the value from the clipboard into the "Value" field of the **AuthContext** secret for the environment and you should be good to go.

-**Note** The Environments tab in repository **Settings** is only supported in **paid SKUs** of GitHub or for **public repositories**. It is possible to use repository or organizational secrets for authenticating to environments defined in **Settings**, as an alternative to using environment secrets as we have done here, but this is not part of this workshop.
+## Custom Deployments

-Now you might think, if this only supports sandbox environments, how do you then publish to production?
+AL-Go can also be setup for custom deployment when you want to deploy to non-SaaS environments. More about this in the advanced section.
+
+This section was about Continuous Deployment, but you might not want to deploy to production environments continuously - how can we publish to production on demand?

 ---
 [Index](Index.md)&nbsp;&nbsp;[next](PublishToProduction.md)
--- a/Workshop/Dependencies1.md
+++ b/Workshop/Dependencies1.md
@ -1,63 +1,70 @@
-# Dependencies to a project in the same repository
+# Dependencies #1 - Dependencies to a project in the same repository
+
 Dependencies is a BIG topic, which is why it is handled in multiple sections in this workshop.

-In general, dependencies between apps in the same repository are handled 100% automatically. AL-Go for GitHub will determine the order in which apps within the same project need to be built, and will use the apps built to satisfy dependencies from other apps. You only need to add your dependencies in app.json and you are good to go.
+In general, dependencies between apps in the same project are handled 100% automatically. AL-Go for GitHub will determine the order in which apps within the same project need to be built, and will use the apps built to satisfy dependencies from other apps.
+
+This means that in a single project repository, you only need to add your dependencies in app.json and you are good to go.

 This topic describes two ways to handle dependencies to apps within another project in the same repository. In the MySolution example from the multi-project sample [here](Projects.md), we could have a dependency from the DK and US apps to the W1 app.

 ## useProjectDependencies
-Let's go ahead and add the dependencies and see what happens. Grab the **id**, **name**, **publisher** and **version** from the **mysolution.w1** app.json and use them to add a dependency to that app into **mysolution.dk** and **mysolution.us**.

-| ![image](https://user-images.githubusercontent.com/10775043/231805415-2e8f345c-f228-4940-9f77-9a05514bd8c0.png) |
+Let's go ahead and add the dependencies and see what happens. Grab the **id**, **name**, **publisher** and **version** from the **mysolution.w1/app.json** and use them to add a dependency to that app into **mysolution.dk/app.json** and **mysolution.us/app.json**.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/ecab7ae7-f113-4df4-999e-d5cad6baac63) |
 |-|

 **Stage** your changes, **Commit** them and **Sync** your changes.

-Another **CI/CD** workflow will be kicked off. Two of the jobs should fail fairly quickly.
+Another **CI/CD** workflow will be kicked off. Two of the jobs (the DK and the US apps) should fail fairly quickly as AL-Go cannot find the W1 app dependency anywhere.

-| ![image](https://user-images.githubusercontent.com/10775043/231809668-a914793d-3e7f-4c02-9deb-13f7a1fce3e7.png) |
-|-|
-
-At this time, the error message displayed in the annotations isn't very clear - we will fix that. If you drill into the failing workflow and into the compile step, you will find the real error:
-
-| ![image](https://user-images.githubusercontent.com/10775043/231810146-8ffe7305-da1d-4d43-ab2a-20952628632e.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/66230407-bbdd-4b30-bf89-6ebdcbe9d3a2) |
 |-|

 It cannot find the mysolution.w1 app on which the two other apps depend, but we kind of knew that.

-The recommended solution to this problem is to set a repository setting called **useProjectDependencies** to **true** and then run Update AL-Go System files.
+The recommended solution to this problem is to set a repository setting called **useProjectDependencies** to **true** and then run Update AL-Go System Files.
+
 Repository settings are in **.github/AL-Go-Settings.json**

-| ![image](https://user-images.githubusercontent.com/10775043/231811594-fd29cc88-2aed-425d-bffb-eb84bfca0463.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/eb63bb7d-e830-4abd-9158-1ad01e8e9c5e) |
 |-|

 Changing the settings file will kick off another build, which also will fail.

-To address that failure, select **Actions**, select **Update AL-Go System Files** and click **Run workflow**. No need to change any parameters, just run the workflow.
+Now, select **Actions**, select **Update AL-Go System Files** and click **Run workflow**. No need to change any parameters, just run the workflow.

 Looking at the **Pull request** created by the **Update AL-Go System Files** workflow, we can see that all build workflows have been changed and now ínclude a **workflowDepth: 2** (instead of 1).
-**Merge** the Pull request, **confirm** the merge and **delete** the temporary branch.

-Open the latest merge commit and see that the structure of the **CI/CD** workflow has changed. Now it builds the W1 project first and any dependencies to the apps DK or US that are found in W1 will be automatically located.
-
-![image](https://user-images.githubusercontent.com/10775043/231813913-1685f87a-a822-4830-a1d3-f35f8422bcb0.png)
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/f63124b5-0f16-4da1-b6e4-208da617c1a7) |
 |-|

+**Merge** the Pull request, **confirm** the merge and **delete** the temporary branch. Open the latest merge commit and see that the structure of the **CI/CD** workflow has changed. Now it builds the W1 project first and dependencies from the apps DK or US that are found in W1 will be automatically located.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/22328924-3c49-4295-bf5d-32cf3509241c) |
+|-|
+
+> [!NOTE]
+> It isn't necessary to update AL-Go System files every time you change or add dependencies, but you will need to run the upgrade code every time you change the workflow dependency depth.
+
 Looking at the artifacts produced by the build, we can see

-| ![image](https://user-images.githubusercontent.com/10775043/231855006-a9f69995-200f-433b-8321-c0652289320d.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/97f24f75-7483-4ec6-a1d9-7fff2bacab80) |
 |-|

-The **thisbuild** artifacts are shortlived--they are only there so that **depending projects** can find build artifacts from other jobs in the same workflow.
+> [!NOTE]
+> The **thisbuild** artifacts are shortlived - they are only there so that **depending projects** can find build artifacts from other jobs in the same workflow.

 ## include
 The other mechanism is to *include* the dependency projects in the project we are building. This is done by using the project setting **appDependencyProbingPaths**, which specifies where to search for dependencies in general.

-If you already set up **useProjectDependencies**, please remove this setting from **.github/AL-Go-Settings.json** and run **Update AL-Go System Files** to get back to a situation where AL-Go cannot locate the **mysolution.w1** dependency.
+> [!NOTE]
+> If you already set up **useProjectDependencies**, please remove this setting from **.github/AL-Go-Settings.json**. You don't need to run **Update AL-Go System Files** before building, but you will be notified to do so when building.

 Now, modify **DK/.AL-Go/settings.json** and **US/.AL-Go/settings.json** by adding this property

-```
+```json
  "appDependencyProbingPaths": [
    {
      "repo": ".",
@ -69,20 +76,21 @@ Now, modify **DK/.AL-Go/settings.json** and **US/.AL-Go/settings.json** by addin

 Specifying a **"."** in **repo**, means to search in the same repository for the depdency. **Release_status** **include** means that AL-Go will include the actual source from the dependent project instead of downloading just a specific build. **Stage** the changes, **Commit** them, and **Sync**.

-| ![image](https://user-images.githubusercontent.com/10775043/231878939-470d6693-218f-4cad-9cc9-001497ba1bb8.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/8d70b96d-2b6f-4cf0-80cc-a34dfdede60b) |
 |-|

-The **CI/CD** workflow is again kicked off and you can see that all builds complete
+The **CI/CD** workflow runs again and you can observe that all the builds finish successfully.

-| ![image](https://user-images.githubusercontent.com/10775043/231880993-89a18260-430d-4b55-b6bf-e30a27c2ee34.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/1b90eea9-258a-451e-9564-e31916ee550d) |
 |-|

-If you inspect the log, you will see that it is checking **appDependencyProbingPaths** and adding the **mysolution.w1** folder to the folders that it needs to build for this job.
+A look at the log reveals that it adds the **mysolution.w1** folder to the list of folders it needs to build for this job, as it checks **appDependencyProbingPaths**.

-| ![image](https://user-images.githubusercontent.com/10775043/231883087-64921fdc-45c2-4e4d-8e96-7be99432af41.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/295a32fd-1048-44f1-975f-22a761040ba3) |
 |-|

-**Note** that this means that the **mysolution.w1** will be built three times, and every project will have their own copy of that app. The apps will be identical, but they will have different package IDs.
+> [!NOTE]
+> This implies that **mysolution.w1** will be compiled three times, and each project will contain its own copy of that app. The apps will be the same, but they will have different package IDs.

 ---
 [Index](Index.md)&nbsp;&nbsp;[next](Dependencies2.md)
--- a/Workshop/Dependencies2.md
+++ b/Workshop/Dependencies2.md
@ -1,40 +1,43 @@
-# Dependencies to AL-Go projects in other repositories
+# Dependencies #2 - Dependencies to AL-Go projects in other repositories
+
 Many partners have a set of common helper functions, tables and other things, which they reuse in other apps.

 With AL-Go for GitHub, the recommendation is to create a Common repository, which has one or more projects, which can be used in several of your other apps.

 So, let's setup a single-project common repository like this. Navigate to https://aka.ms/algopte to create a new repository. Click Use this template and select Create a new repository. Select your organization as owner, specify a name and select Public.

-| ![image](https://user-images.githubusercontent.com/10775043/232203510-095f1f0d-e407-413d-9e17-7a3e3e43b821.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/3ac95b12-7e51-4378-9072-d1415b9ed38d) |
 |-|

-Run Update **AL-Go System Files** with **microsoft/AL-Go-PTE@preview** as the template URL and **Y** in Direct Commit.
-
-When upgrade is done, create 2 apps within the repository using the **Create a new app** workflow called **Common** and **Licensing**, using the following parameters:
+Create 2 apps within the repository using the **Create a new app** workflow called **Common** and **Licensing**, using the following parameters:

 | Name | Value |
 | :-- | :-- |
+| Use workflow from | `Branch: main` |
 | Project name | `.` |
 | Name | `Common` |
 | Publisher | `<your publisher name>` |
 | ID Range (from..to) | `60000..60099` |
-| Include Sample Code | `no` |
-| Direct Commit | `yes` |
+| Include Sample Code | :black_square_button: |
+| Direct Commit | :ballot_box_with_check: |
+| Use GhTokenWorkflow | :black_square_button: |

 and

 | Name | Value |
 | :-- | :-- |
+| Use workflow from | `Branch: main` |
 | Project name | `.` |
 | Name | `Licensing` |
 | Publisher | `<your publisher name>` |
 | ID Range (from..to) | `60100..60199` |
-| Include Sample Code | `no` |
-| Direct Commit | `yes` |
+| Include Sample Code | :black_square_button: |
+| Direct Commit | :ballot_box_with_check: |
+| Use GhTokenWorkflow | :black_square_button: |

 Leaving out the sample code in order to avoid name clashes.

-| ![image](https://user-images.githubusercontent.com/10775043/232205313-3e3df750-55d3-44ac-bb27-40f84971a9a0.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/ce08e813-bf5a-4814-8c56-a6f38cced01d) |
 |-|

 Wait for both workflows to complete.
@ -43,7 +46,7 @@ Under **Code** locate the **app.json** file for the **Common** app and copy **id

 Now locate the **app.json** file for the **Licensing** app and create a dependency to the **Common** app and commit the changes.

-| ![image](https://user-images.githubusercontent.com/10775043/232205817-c0c2adef-a61f-4406-8880-5d7db55c7804.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/29885e4e-072b-46d4-8b22-135adb973d48) |
 |-|

 Also copy the **id**, **name**, **publisher** and **version** from the **Licensing** app to the clipboard as well.
@ -54,83 +57,110 @@ Now, navigate back to your multi-project repository, which you created [here](Pr

 Add a dependency to the **Licensing** app from the **Common** repository, from the **mysolution.w1** app in the **W1** project.

-| ![image](https://user-images.githubusercontent.com/10775043/232206403-bd93b016-3fe5-44fa-8aae-057323735034.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/40d496fa-64ac-41e3-8b32-d1d33ba17a06) |
 |-|

 And as expected, the builds will fail.

-| ![image](https://user-images.githubusercontent.com/10775043/232211698-943bdad0-18e8-4163-94b7-3e77a4bad486.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/7e7bc6c2-0783-4415-aaac-b2dea56998cf) |
 |-|

-In this example using the **include** mechanism, but builds would also fail when using **useProjectDependencies**.
+In this example using the **useProjectDependencies** mechanism, but builds would also fail when using **include**.

 In this workshop, I will describe two ways to to make this work.

 ## Using appDependencyProbingPaths

-Now your organization variable ALGoOrgSettings, and add:
+In the MySolution repository, navigate to Settings -> Secrets and Variables -> Actions and select Variables. Create a new repository variable called **ALGOREPOSETTINGS** with this content:

-```
-    "appDependencyProbingPaths": [
-        {
-            "repo": "freddydkorg/Common",
-            "release_status": "latestBuild"
-        }
-    ]
+```json
+  "appDependencyProbingPaths": [
+    {
+      "repo": "freddydkorg/Common",
+      "release_status": "latestBuild"
+    }
+  ]
 ```

-| ![image](https://user-images.githubusercontent.com/10775043/232247041-b9e20016-b734-4a39-9f87-e28a7af9d354.png) |
+replacing **freddydkorg** with your organization name obviously.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/0ae5d283-0494-4a3d-b6a0-661092b46e09) |
 |-|

-This setting means that all repositories in this organization will download the **latest build** from **freddydkorg/Common** and a subsequent build will succeed.
+> [!NOTE]
+> Make sure you create a repository variable and not a repository secret

-| ![image](https://user-images.githubusercontent.com/10775043/232249808-bed9cb0c-e73d-422e-a629-1373dc128c13.png) |
+This setting means that all projects in this repository will download the **latest build** from **freddydkorg/Common** and a subsequent build will succeed. Go to **Actions**, select the **CI/CD** workflow, click **Run workflow** and wait for the workflow to complete.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/b10c3050-dd45-47a0-8c2b-fbeb517c94c2) |
 |-|

-If we had added the**appDependencyProbingPaths** only to the **W1** project, then the **W1** project would **succeed** and the **DK** and **US** projects **fail**. The reason for this is that we are using the **include** mechanism, which includes the source of **W1** in **DK** and **US**, but it doesn't add the **appDependencyProbingPaths** from **W1**.
+> [!NOTE]
+> You can also define **appDependencyProbingPaths** in the settings file for individual projects (f.ex. **W1** project). This would also work when using **useProjectDependencies**.
+> When using **include** however the **DK** and **US** projects would **fail** as they would **include** the source code for the **W1** project, but not the settings (i.e. the appDependencyProbingPaths).

 ## Using GitHub Packages

-If you already added appDependencyProbingPaths, then please remove these settings before continuing, making your build fail again.
+> [!NOTE]
+> If you already added appDependencyProbingPaths, then please remove these settings before continuing, making your build fail again.

 In order to use GitHub Packages for dependency resolution, we need to create an organizational secret called **GitHubPackagesContext**. The format of this secret needs to be **compressed JSON** containing two values: **serverUrl** and **token**. Example:
-```
-{"token":"ghp_XXXX","serverUrl":"https://nuget.pkg.github.com/freddydkorg/index.json"}
+
+```json
+{"token":"ghp_XXX","serverUrl":"https://nuget.pkg.github.com/freddydkorg/index.json"}
 ```

-Where **ghp_XXX** should be replaced by your **personal access token** with permissions to **Packages** and **freddydkorg** should be replaced by your **organization name**.
+Where **ghp_XXX** should be replaced by a **personal access token** with permissions to **write:packages** and **freddydkorg** should be replaced by your **organization name**.

-You can also use BcContainerHelper and the function **New-ALGoNuGetContext** to create a JSON structure in the right format.
+> [!NOTE]
+> Fine-grained personal access tokens doesn't support packages at this time, you need to use classic personal access tokens.

-Go to your organization settings and create an **organizational secret** called **GitHubPackagesContext** with the value above.
+To create a personal access token, navigate to [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new), give it a name and select write:packages.

-| ![image](https://user-images.githubusercontent.com/10775043/232253023-7131dba1-1be1-4cac-8786-27715899200b.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/48f7a8c5-728b-499d-ab38-1a4726b52da8) |
+|-|
+
+> [!NOTE]
+> You can also use the BcContainerHelper function **New-ALGoNuGetContext** to create a correctly formed JSON structure.
+
+Go to your organization settings and create an **organizational secret** called **GitHubPackagesContext** with the your secret value.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/f369d7df-fed2-48e7-bf85-aa7924dd9cfa) |
 |-|

 Now, navigate to your **Common** repository and run the **CI/CD** Workflow. Inspect the workflow summary after completion:

-| ![image](https://user-images.githubusercontent.com/10775043/232253742-7728e4a2-587e-40fa-a547-4c95ba4e9951.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/39023475-78a3-4be1-9f01-d3a476697c7f) |
 |-|

-Notice the **Deliver to GitHub Packages** job, by creating the **GitHubPackagesContext** secret, you have enabled Continuous Delivery to GitHub Packages.
+Notice the **Deliver to GitHubPackages** job. By creating the **GitHubPackagesContext** secret, you have enabled Continuous Delivery to GitHub Packages.

-Now, navigate to your organization and select **Packages** and you will see GitHub Packages created for the two apps in **Common**.
+Now, click **Code** and see that you have 2 Packages delivered from the repository:

-| ![image](https://user-images.githubusercontent.com/10775043/232253790-7aee6c91-a858-4dd9-b85c-5f22a67394b5.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/3fbf27fb-d0c1-442f-9221-83b1096612b0) |
 |-|

-Next, navigate to your **MySolution** repository and run the **CI/CD** workflow and magically, all dependencies are now also resolved.
+Click **Packages**, which will take you to Packages in your organizational profile. All packages are stored on the organization with a link to the owning repository:

-| ![image](https://user-images.githubusercontent.com/10775043/232286871-845f02ea-a59a-46e8-b720-5ff1d6927ffe.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/5d3f7089-7826-4651-8081-9b95d07e0e5e) |
 |-|

-And GitHub Packages have been published for the 3 apps in MySolution as well
+Next, navigate to your **MySolution** repository (where you deleted the ALGOREPOSETTINGS repository variable) and run the **CI/CD** workflow and magically, all dependencies are now also resolved.

-| ![image](https://user-images.githubusercontent.com/10775043/232286814-4d4572f3-fa14-460e-84ba-f18fa071860f.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/a9f12ea7-5414-441b-9e5c-c14ea803f35b) |
+|-|
+
+Looking into the logs under the **Build** step, you will find that **Resolving Dependencies** will find that it is missing the **Licensing** dependency and then, under **installing app dependencies**, it searches GitHub Packages to locate the missing dependencies (+ their dependencies)
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/d6504c55-19fc-489f-bdb5-b345f00432c2) |
+|-|
+
+and looking at packages for the organization, we will now see that there are 5 packages - 3 of them published from the MySolutions repository:
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/95f989ed-1d88-4cd6-8959-25291d23d569) |
 |-|

 Continuous Delivery is not only GitHub Packages. Let's have a look at continuous delivery...

 ---
 [Index](Index.md)&nbsp;&nbsp;[next](ContinuousDelivery.md)
-
--- a/Workshop/Dependencies3.md
+++ b/Workshop/Dependencies3.md
@ -1,6 +1,8 @@
-# Dependencies to other apps
+# Dependencies #3 - Dependencies to third party apps
 Dependencies to apps from other partners...

+TO:DO
+
 With symbols, you can compile your app

 With runtime packages or the full .app file, you can also run tests
--- a/Workshop/DevelopmentEnvironments.md
+++ b/Workshop/DevelopmentEnvironments.md
@ -1,4 +1,4 @@
-# Development Environments
+# FUTURE TOPIC: Development Environments

 This topic will be finalized later

--- a/Workshop/GetStarted.md
+++ b/Workshop/GetStarted.md
@ -3,24 +3,37 @@ With our prerequisites in place, it is time to get started and create our first

 In a browser, navigate to https://aka.ms/algopte:

-| ![image](https://user-images.githubusercontent.com/10775043/231536061-8594cfec-d312-4f5b-9ff4-a3d0cf46ab69.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/1c6a3d1d-b712-4837-9654-58fccbdd911e) |
 |-|

-Click **Use This Template** and select **Create a new repository**. Select your **organizational account** as **owner** and enter **repo1** as repository name. Make the repo **public** and click **Create repository form template**.
+And you should see:

-| ![image](https://user-images.githubusercontent.com/10775043/231535787-43d8af7d-1554-4e11-9753-8e7d7d21401c.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/7e74715a-0e9a-4f7a-b261-a7107fad8888) |
 |-|

-Click **Actions**, select the **CI/CD** workflow, click **Run workflow** and run the CI/CD workflow on our empty repository. Wait for the CI/CD workflow to complete.
+Click **Use This Template** and select **Create a new repository**. Select your **organizational account** as **owner** and enter **repo1** as repository name. Make the repo **public** and click **Create repository**.

-![image](https://github.com/microsoft/AL-Go/assets/10775043/d411bc1f-8494-4c00-93b5-26046ecda6a1)
-
- By clicking the workflow in the list, and scrolling down, you should see:
-
-| ![image](https://user-images.githubusercontent.com/10775043/231540402-05af1336-0f60-45e7-a86c-501a95a657de.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/32ce5b05-b347-4174-b83d-e344756f2d06) |
 |-|

-Note the three warnings explaining that no apps have been added.  The CI/CD workflow doesn't have anything to compile yet as you didn't add any source code.
+After a few seconds, your new repository should be ready for you.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/11d7f51d-f38c-4163-a929-a55f2360911d) |
+|-|
+
+Click **Actions**, and you should see that a CI/CD workflow has already been kicked off on our empty repository.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/e13fc12d-c36d-4014-bbe5-0f8003c90bb0) |
+|-|
+
+Wait for the CI/CD workflow to complete and click the completed workflow to see details.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/cc181fb1-0496-45aa-87c5-69fd000d772f) |
+|-|
+
+Note the warnings explaining that no apps have been added. The CI/CD workflow doesn't have anything to compile yet as you didn't add any source code.
+
+Ignore the warning about available updates for now.

 After this step, we are done setting up a basic AL-Go for GitHub repository and we only need to add our apps.

--- a/Workshop/Index.md
+++ b/Workshop/Index.md
@ -1,5 +1,5 @@
 # AL-Go for GitHub Workshop
-This workshop...
+This workshop shows you how to take advantage of the functionality, which is provided out-of-the-box by AL-Go for GitHub.

 1. [Introduction](Introduction.md) - Introduction to GitHub, AL-Go for GitHub, personal and organizational accounts.
 1. [Prerequisites](Prerequisites.md) - Setup pre-requisites for the Workshop.
@ -15,14 +15,14 @@ This workshop...
 1. [Publish to Production](PublishToProduction.md) - Publish your apps to a production environment securely.
 1. [Automated Tests](AutomatedTests.md) - Add automated testing to your project.
 1. [Scheduled test runs](ScheduledTestRuns.md) - Testing your app against the latest (and future Business Central versions) daily or weekly.
+1. [Performance Testing](PerformanceTesting.md) - *FUTURE TOPIC: Add performance tests to your daily test runs.*
+1. [Reference Documentation Generation](ReferenceDoc.md) - Keep your reference documentation up-to-date.
+1. [Delevelopment Environments](DevelopmentEnvironments.md) - *FUTURE TOPIC: How to setup a development environment for a project.*
+1. [The Development Process](TheDevelopmentProcess.md) - *FUTURE TOPIC: The recommended way to work with feature branches, pull requests, code reviews and branch protection rules.*
+1. [Keeping your Repository Up-to-date](KeepUpToDate.md) - *FUTURE TOPIC: Updating AL-Go for GitHub to the latest version by running a workflow.*


-
-## Future topics
-1. [Performance Testing](PerformanceTesting.md) - Add performance tests to your daily test runs.
-1. [Delevelopment Environments](DevelopmentEnvironments.md) - How to setup a development environment for a project.
-1. [The Development Process](TheDevelopmentProcess.md) - The recommended way to work with feature branches, pull requests, code reviews and branch protection rules.
-1. [Keeping your Repository Up-to-date](KeepUpToDate.md) - Updating AL-Go for GitHub to the latest version by running a workflow.
+## Additional Future topics
 1. Dependencies to other apps
 1. AppSource validation
 1. Settings
@ -30,3 +30,4 @@ This workshop...
 1. Power Platform solution
 1. Self Hosted Runners
 1. Make it your own
+
--- a/Workshop/KeepUpToDate.md
+++ b/Workshop/KeepUpToDate.md
@ -1,4 +1,4 @@
-# Keeping your AL-Go repository up-to-date
+# FUTURE TOPIC: Keeping your AL-Go repository up-to-date

 This topic will be finalized later

--- a/Workshop/PerformanceTesting.md
+++ b/Workshop/PerformanceTesting.md
@ -1,9 +1,9 @@
-# Performance Testing
+# FUTURE TOPIC: Performance Testing

 This topic will be finalized later


-Maybe it is about time to actually explain how you create a development environment and code your app?
+Testing is an important part of the app quality, but so is documentation. Let's look at generating reference documentation your app, and... - keeping it up-to-date...

 ---
-[Index](Index.md)&nbsp;&nbsp;[next](DevelopmentEnvironments.md)
+[Index](Index.md)&nbsp;&nbsp;[next](ReferenceDoc.md)
--- a/Workshop/Prerequisites.md
+++ b/Workshop/Prerequisites.md
@ -6,17 +6,19 @@ You will need:
   - Free should be enough to follow the workshop
 1. A GitHub organizational account
   - Free should be enough to follow the workshop
-1. An organizational secret called GHTOKENWORKFLOW
-   - Containing a personal access token with permissions to modify workflows.
+1. An organizational **secret** called GHTOKENWORKFLOW containing a personal access token (classic or fine-grained)
+   - Using classic tokens, the token should have **workflow** permissions (automatically includes repo permissions)
+   - Using Fine-grained tokens, the token should have **Read and Write** access to **Contents**, **Pull Requests** and **Workflows** (automatically includes Read-only access to Metadata)
   - The secret should be available to all public repositories (you cannot have organizational secret accessible for private repos in Free GitHub)
-1. An organizational variable called ALGOORGSETTINGS
+1. An organizational **variable** called ALGOORGSETTINGS
   - Containing the following JSON structure (for performance reasons)
-```
-    {
-        "useCompilerFolder": true,
-        "doNotPublishApps": true,
-        "artifact": "https://bcartifacts.azureedge.net/sandbox/22.0.54157.55210/us"
-    }
+
+```json
+  {
+    "useCompilerFolder": true,
+    "doNotPublishApps": true,
+    "artifact": "https://bcartifacts.azureedge.net/sandbox/23.0.12034.13450/us"
+  }
 ```

 The combination of useCompilerFolder and doNotPublishApps, means that AL-Go will never actually create a container, which saves a great amount of time.
--- a/Workshop/Projects.md
+++ b/Workshop/Projects.md
@ -5,6 +5,11 @@ Every repository can have any number of projects, which each can have any number

 Up until now we have worked with a repository which contained 2 apps. This is called a single-project repository.

+Things that are determined at the app level:
+- Version of the app
+- Dependencies to other apps
+- Functionality of the app (obviously)
+
 Things that are determined at the project level:
 - Version and localization of Business Central to use during build
 - Dependencies to other projects
@ -20,92 +25,99 @@ A multi-project repository could look like this:

 ![image](https://user-images.githubusercontent.com/10775043/231688802-4d08e4f2-6bbc-4677-902b-0bef9ed068d8.png)

-So, let's setup a multi-project repository like this. Navigate to **https://aka.ms/algopte** to create a new repository. Click **Use this template** and select **Create a new repository**. Select your **organization** as owner, specify a **name** and select **Public**.
+So, let's setup a multi-project repository like this. Navigate to **https://aka.ms/algopte** to create a new repository. Click **Use this template** and select **Create a new repository**. Select your **organization** as owner, specify a **name**,select **Public** and click **Create repository**.

-| ![image](https://user-images.githubusercontent.com/10775043/231751252-51f0c80a-dd74-4f32-95d5-39a363e2b2ff.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/ecbdaa03-1cd2-4043-8ec0-a7f4d87bb819) |
 |-|

-Like when we ran GetStarted, we want to use the preview version of AL-Go for GitHub. Select **Actions**, select the **Update AL-Go System Files** workflow and click **Run workflow**.
-
-Specify **microsoft/AL-Go-PTE@preview** as template repository, **Y** in Direct Commit and click **Run workflow**. You don't have to wait for the CI/CD workflow to complete. You can locate the **Create a new app** workflow in the list of workflows and run it with the following parameters:
+Locate the **Create a new app** workflow in the list of workflows and run it with the following parameters:

 | Name | Value |
 | :-- | :-- |
+| Use workflow from | `Branch: main` |
 | Project name | `US` |
 | Name | `mysolution.us` |
 | Publisher | `<your publisher name>` |
 | ID Range (from..to) | `50000..50100` |
-| Include Sample Code | `yes` |
-| Direct Commit | `no` |
+| Include Sample Code | :ballot_box_with_check: |
+| Direct Commit | :black_square_button: |
+| Use GhTokenWorkflow | :black_square_button: |

-| ![image](https://user-images.githubusercontent.com/10775043/231755134-303a59b3-f616-4d08-b46d-47810e459a1b.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/683a4ebd-364a-4373-81f9-512faa195391) |
 |-|

-Select **Pull requests**, click the **New PTE** pull request and select **Files changed** to inspect what changes was done to the repo:
+When the **Create a new app in [main]** workflow has completed, select **Pull requests**, click the **New PTE** pull request and select **Files changed** to inspect what changes was done to the repo:

-![image](https://user-images.githubusercontent.com/10775043/231753510-4a0cb9a9-c1b8-4fc8-9481-4e7a4ea80c89.png)
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/557661dd-587f-43cc-8ff8-d71a38a55638) |
+|-|

-Notice that:
-1. The .AL-Go folder was moved from the root of the repo and into the US folder.
-2. A new US.code-workspace was created as a workspace for this project
-3. An app was added under the US folder called mysolution.us
+> [!NOTE]
+> 1. The .AL-Go folder was moved from the root of the repo and into the US folder.
+> 2. A new US.code-workspace was created as a workspace for this project
+> 3. An app was added under the US folder called mysolution.us

-Go ahead and **merge the pull request** and **delete** the temporary branch.
+Go ahead click **Conversation**, **merge the pull request** and **delete** the temporary branch.

 You don't have to wait for the **CI/CD workflow** to complete, just go ahead and run the **Create a new app** again. This time with the following parameters:

 | Name | Value |
 | :-- | :-- |
+| Use workflow from | `Branch: main` |
 | Project name | `DK` |
 | Name | `mysolution.dk` |
 | Publisher | `<your publisher name>` |
 | ID Range (from..to) | `51000..51100` |
-| Include Sample Code | `yes` |
-| Direct Commit | `no` |
+| Include Sample Code | :ballot_box_with_check: |
+| Direct Commit | :black_square_button: |
+| Use GhTokenWorkflow | :black_square_button: |

 and run the same workflow again with these parameters:

 | Name | Value |
 | :-- | :-- |
+| Use workflow from | `Branch: main` |
 | Project name | `W1` |
 | Name | `mysolution.w1` |
 | Publisher | `<your publisher name>` |
 | ID Range (from..to) | `52000..52100` |
-| Include Sample Code | `yes` |
-| Direct Commit | `no` |
+| Include Sample Code | :ballot_box_with_check: |
+| Direct Commit | :black_square_button: |
+| Use GhTokenWorkflow | :black_square_button: |

-When the **New App (mysolution.dk)** and **New App (mysolution.w1)** pull requests are created, **merge the pull request** and **delete** the temporary branch.
+When the **New PTE (mysolution.dk)** and **New PTE (mysolution.w1)** pull requests are created, merge both pull request and delete the temporary branches.

 Now select Actions and see that a number of workflows have been kicked off. Some are completed, some might still be running.

 Click the latest CI/CD commit workflow and notice the 3 jobs (you can expand the jobs by clicking show all jobs):

-| ![image](https://user-images.githubusercontent.com/10775043/231756744-8952ba6b-edaa-47d8-b1ad-cf74990ba86d.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/bae168e5-bc9e-4f32-9ac8-05a4b94a4a41) |
 |-|

-At this time, all apps will be using US as localization and use the same Business Central version as we entered when setting up prerequisites.
+> [!NOTE]
+> At this time, all apps will be using US as localization and use the same Business Central version as we entered when setting up prerequisites, but you can change this in the settings file for each individual project.

-After the build completes, you can inspecting the artifacts created from this multi-project repository:
+After the build completes, you can inspect the artifacts created from this multi-project repository, by clicking Summary and scrolling down:

-| ![image](https://user-images.githubusercontent.com/10775043/231757819-64d9a4b8-bda2-4b36-974b-540052007c76.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/60973d66-bf60-4b38-9776-fa720fbd3e52) |
 |-|

-DK, US and W1 all have an artifact of the type **Apps** generated, but they are obviously wrong. We need **DK** to be build using the danish localization and **W1** using W1.
+DK, US and W1 all have an artifact of the type **Apps** generated, but as already stated, they are all build using the US localization. We need **DK** to be build using the Danish localization and **W1** using W1.

-Note also the CheckForUpdates annotation. AL-Go says that there are system files updates. This is because when creating a new project, AL-Go will (at the next system file update) place scripts in the .AL-Go folder for creating local and cloud development environments.
+> [!NOTE]
+> AL-Go states that there are system files updates (the CheckForUpdates annotation). This is because when creating a new project, AL-Go will (at the next system file update) place scripts in the .AL-Go folder for creating local and cloud development environments.

-Before running **Update AL-Go System Files** however, let's make some changes to the repository and we will do this from VS Code. Select **Code** and click the **Code** dropdown to copy the GIT URL for the repo:
+Before running **Update AL-Go System Files** however, let's make some changes to the repository and we will do this from VS Code. Select **Code** and click the **Copy** button to copy the GIT URL for the repo:

-| ![image](https://user-images.githubusercontent.com/10775043/231759163-33006212-6191-4ed6-8a96-84ff0c7d944e.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/b5d0ce1b-084b-44b6-bccc-a486f7a72ecc) |
 |-|

 Open **VS Code** and run **Git Clone** to clone your repository to your local machine:

-| ![image](https://user-images.githubusercontent.com/10775043/231759374-671a9933-9602-4ec0-bc06-ea5c7236b457.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/a911144c-fad7-4c18-bdad-2332aa74df5f) |
 |-|

 Open the repository (do not open the workspace) and perform the following changes:
- in **DK/.AL-Go/settings.json**, add **"artifact": "https://bcartifacts.azureedge.net/sandbox/22.0.54157.55210/dk"**
+- in **DK/.AL-Go/settings.json**, add **"artifact": "https://bcartifacts.azureedge.net/sandbox/23.0.12034.13450/dk"**
 - in **DK/.AL-Go/settings.json**, change **country** to **"dk"**
 - in **DK/mysolution.dk/HelloWorld.al**, add DK to the pageextension name (i.e. CustomerListExt to **CustomerListExtDK**)
 - in **US/.AL-Go/settings.json**, add **"artifact": "https://bcartifacts.azureedge.net/sandbox/22.0.54157.55210/us"**
@ -116,16 +128,42 @@ Open the repository (do not open the workspace) and perform the following change

 **Stage the changes** in **VS Code**, **Commit** the changes and **Sync**.

-Now, we can create a release and inspect that. Run the **Create release** workflow and release v1.0 like this:
-
-| ![image](https://user-images.githubusercontent.com/10775043/231798204-2b7c4689-596b-42a6-ac5b-62093192e595.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/5ae5b03a-bc15-45b2-89d9-d96468755879) |
 |-|

-After this is done, select **Code** and click the newly created release to see the artifacts (which also reveals a bug)
+In GitHub, wait for the **CI/CD** workflow to complete:

-| ![image](https://user-images.githubusercontent.com/10775043/231798973-1ed29f6d-fb08-4b8e-b2f1-efd415b20bf1.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/87d64b0e-a930-4cfc-80d7-e3e8769a50d4) |
 |-|

+Now, we can create a release and inspect that. Run the **Create release** workflow and release v1.0 with these parameters:
+
+| Name | Value |
+| :-- | :-- |
+| Use workflow from | `Branch: main` |
+| App version | `latest` |
+| Name of this release | `v1.0` |
+| Tag of this release | `1.0.0` |
+| Prerelease | :black_square_button: |
+| Draft | :black_square_button: |
+| Create Release Branch | :black_square_button: |
+| New Version Number | `+0.1` |
+| Direct Commit | :black_square_button: |
+| Use GhTokenWorkflow | :black_square_button: |
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/9b69803c-8133-47ef-a9a8-f1681a988907) |
+|-|
+
+After this is done, select **Code** and click the newly created release to see the artifacts.
+
+> [!NOTE]
+> In the auto generated release notes, you will see all merged Pull Requests under **What's Changed** and by clicking the **Full Changelog** link you will find all commits.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/15c67508-33c1-4592-a227-05262651dcd6) |
+|-|
+
+You will see that every project has it's own release artifact.
+
 OK - so that's fine, but normally in a solution like this, DK and US have a dependency on W1 or a common app - you don't have all code duplicated 3 times - how does AL-Go handle dependencies?

 ---
--- a/Workshop/PublishToProduction.md
+++ b/Workshop/PublishToProduction.md
@ -1,26 +1,52 @@
 # Publish To Production
 In [this](ContinuousDeployment.md) section you learned how to setup a QA environment for continuous deployment.

-If you follow the same process for setting up an environment, but postfix your environment name with **(Production)**, like:
+If you follow the same process and setup an environment called PROD and add the same AUTHCONTEXT secret to that environment.

-| ![image](https://user-images.githubusercontent.com/10775043/232310956-96179562-e101-4b90-9a01-12c8c316cfd3.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/1008fcf4-ed2a-4cc1-a786-3b5cf6692266) |
 |-|

-Then that environment will not be picked up for **continuous deployment**, but can only be deployed to using the **Publish To Environment** workflow.
+> [!NOTE]
+> You can add protection rules to environments in GitHub, like which branches can deploy to this environment and which users should review every deployment to this environment as well.

-**Note** that there are plans to update the mechanism for when an environment is picked up for deployment, to allow deployment to environments postfixed with **(Production)**. This will be done by including some settings. But until those settings are present, the mechanism will work as described here.
+By default, all environments will be picked up for **continuous deployment**, but production environments will be skipped unless you add the ContinuousDeployment setting from the previous chapter. The Deployment job will succeed, but looking into the step, you will see that the PROD environment is ignored:

-Publish to the production environment by running the workflow and specifying which version to deploy, and which environment to deploy to.
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/205e4eed-919c-4cb0-bb54-924857b53898) |
+|-|

-**Note** that the default version is "current". This will deploy the **current release**. If you specify *latest* you will get the **latest build**
+By adding a setting like this to your repository settings file (.github/AL-Go-Settings.json)

-> Current is the **current release**, which is the release tagged with *Latest* in your repository
-> 
-> ![image](https://github.com/microsoft/AL-Go/assets/10775043/236f1eac-3045-4b19-90a1-1f81e2ad26a6)
+```json
+  "DeployToPROD": {
+    "continuousDeployment": false
+  }
+```

-And... again, if you want to just use the latest *build*, you would specify "latest":
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/a0822808-f773-49dc-ba4d-753a5677ca38) |
+|-|

-| ![image](https://user-images.githubusercontent.com/10775043/232312134-0028a08d-1004-43f2-8127-aeeee8ed1a5e.png) |
+Then the PROD environment is not even included in the CI/CD workflow, and again, setting the ContinuousDeployment to true will enable continuous deployment to the production environment.
+
+## Publish to Environment
+
+Menually publishing to environments is done by running the **Publish To Environment** workflow and specifying which version to publish.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/57f8441b-d414-4225-9cf4-dc2f7ce185a0) |
+|-|
+
+> [!NOTE]
+> The default version is **current**. This will deploy the **current release**, which is the release tagged with *Latest* in your repository.
+>
+> ![image](https://github.com/microsoft/AL-Go/assets/10775043/5c653d70-106e-4d0a-9684-ae91275abb77)
+
+If you want to deploy the latest *build*, you would specify "latest" and if you want to deploy a specific version, you should specify the project version number to deploy.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/ab6878fb-3480-46ec-948e-2f55efc572a5) |
+|-|
+
+Investigating the **Publish To Environment** workflow run, you will see a Deploy step like the one in CI/CD, which also includes a link to the environment.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/9bbfac60-e191-412f-9ff0-313ce4cd7379) |
 |-|

 But... - would you do that without running automated tests?
--- a/Workshop/ReferenceDoc.md
+++ b/Workshop/ReferenceDoc.md
@ -0,0 +1,96 @@
+# Reference Documentation
+
+A vital part of your development processes is reference documentation. AL-Go for GitHub supports the ALDoc tool for reference documentation generation, either continuously as part of CI/CD, manually or scheduled.
+
+> [!NOTE]
+> The [ALDoc tool](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/help/help-aldoc-generate-help) generates content based on the source code. Generating content based on source code has many advantages such as accuracy, 100% reflection of the current codebase, less error-prone documentation, and it saves time. The ALDoc tool generates documentation from symbolic and syntactical information, code comments, and overall application structure based on input .app file(s). The tool also generates a help site with these reference articles, sorted by the application structure, based on the provided template.
+
+AL-Go for GitHub supports deploying the reference documentation to GitHub Pages. GitHub Pages is websites for you and your projects, hosted directly from your GitHub repository. It is also possible to deploy the reference documentation to other static HTML hosting providers, but this requires some scripting and is not included here.
+
+## GitHub Pages
+
+> [!NOTE]
+> GitHub Pages is available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub’s plans](https://docs.github.com/en/get-started/learning-about-github/githubs-plans).
+
+Navigate to your Common repository, go to **Settings** -> **Pages** and under **Build and deployment** select **GitHub Actions** as the source.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/a71fc75f-027c-4ef9-a8f4-63b1332ac9a4) |
+|-|
+
+Choose Actions, select the **Deploy Reference Documentation** workflow and click **Run workflow**
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/43b88ca8-0420-48f0-b875-3fab3393bbe7) |
+|-|
+
+When the workflow is done, click the workflow to open workflow details and you will find a URL to your reference documentation in the deploy step. There is also an artifact called github-pages, which is the artifact deployed to the GitHub pages website. This artifact can be deployed to any other hosting provider if needed.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/452d1a68-c6f3-4adb-964f-bfa5a2186c5a) |
+|-|
+
+Clicking the link to your reference documentation reveals the website
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/52b4f77b-aa52-474b-a2b5-3e25425c2843) |
+|-|
+
+Now, there isn't much documentation in the Common repository as the apps doesn't contain any objects, so let's repeat the above steps with Repo1 (single-project) and MySolution (multi-project) repository.
+
+In all repositories, click the settings icon in the About section to open repository details, specify a description and check **Use your GitHub Pages website**
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/53f2223b-d102-4194-9ebe-3d1789255819) |
+|-|
+
+After this, the link to the reference documentation is available in the upper right corner of your repository landing page.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/556de268-c8f3-4e55-a282-252ff9b39d70) |
+|-|
+
+Clicking the link on the multi-project repository, in which we did a release earlier, shows that AL-Go for GitHub includes reference documentation for prior releases as well as the current main repository.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/00e38e2e-1429-43cc-b16c-445a9303f997) |
+|-|
+
+You will see the three projects as "folders" and the apps, which are built in these projects, are listed below. You will also find a **Releases** folder under which earlier versions of the apps from the repository are listed.
+
+## Deploying the reference documentation daily
+
+To allow daily generation of the reference documentation, modify the .github/AL-Go-Settings.json and add a setting like this:
+
+```json
+  "DeployReferenceDocumentationSchedule": "0 4 * * *"
+```
+
+> [!NOTE]
+> This will update the reference documentation every night at 4
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/5b3a1c0a-6696-483c-857a-590e39dfa860) |
+|-|
+
+## Deploying the reference documentation continuously
+
+If you want to setup continuous deployment of the reference documentation, you can add this setting:
+
+```json
+  "alDoc": {
+    "continuousDeployment": true
+  }
+```
+
+> [!NOTE]
+> There are other settings in the ALDoc settings structure, which controls the generation of the reference documentation. Inspect [https://aka.ms/algosettings#aldoc](https://aka.ms/algosettings#aldoc) to see them all.
+
+Adding this to the ALGOORGSETTINGS organizational variable causes all repositories to continuously deploy reference documentation:
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/898a58ab-f560-4507-9924-c34985d608cb) |
+|-|
+
+But you can also add the setting to a repository settings variable called **ALGOREPOSETTINGS** or to the repository settings file **.github/AL-Go-Settings.json** if you only want to enable this for a single repository.
+
+Running CI/CD after enabling continuous deployment reveals the **Deploy Reference Documentation** job being run and the link to the reference documentation is available in the job.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/a92b4dad-67fe-4c57-81f2-a7fc2abfd848) |
+|-|
+
+Maybe it is about time to actually explain how you create a development environment and code your app?
+
+---
+[Index](Index.md)&nbsp;&nbsp;[next](DevelopmentEnvironments.md)
--- a/Workshop/Releasing.md
+++ b/Workshop/Releasing.md
@ -14,63 +14,104 @@ Select **Actions**, select the **Create Release** workflow and click **Run workf

 | Name | Value |
 | :-- | :-- |
+| Use workflow from | `Branch: main` |
 | App version | `latest` |
 | Name of this release | `v1.0` |
 | Tag of this release | `1.0.4` |
-| Prerelease | `no` |
-| Draft | `no` |
-| Create Release Branch | `yes` |
+| Prerelease | :black_square_button: |
+| Draft | :black_square_button: |
+| Create Release Branch | :ballot_box_with_check: |
 | New Version Number | `+1.0` |
-| Direct Commit | `no` |
+| Direct Commit | :black_square_button: |
+| Use GhTokenWorkflow | :black_square_button: |

-After completion of the **Create release** workflow, you can select **Code** and see that you have 1 releases:
-![image](https://user-images.githubusercontent.com/10775043/231591177-d2a85451-a717-4f87-a2ae-55e26c19a17f.png)
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/8ae1628e-0368-4af3-8c01-16e3e8a62917) |
+|-|
+
+After completion of the **Create release** workflow, you can select **Code** and see that you have 1 release:
+
+![image](https://github.com/microsoft/AL-Go/assets/10775043/c23b0d4f-9476-462d-ace6-788337164f88)

 Also, you have a Pull request waiting, which increments version number by 1.0.

-| ![image](https://user-images.githubusercontent.com/10775043/231591451-040c40d7-75d0-43c2-af8f-744ae29f36e8.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/83c9ea64-f3df-4bd1-8fd1-5a2b2c85e9e2) |
 |-|

 **Merge the Pull request**, **delete the temporary branch** and select **Actions** to see that a Merge Pull request was kicked off.

-| ![image](https://user-images.githubusercontent.com/10775043/231591751-b2ebe08a-689c-446b-84d5-3c7c285e754c.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/79704699-7cd4-4589-a7ff-d7a98cd29cca) |
 |-|

-Inspecting the build from the Pull request, you will see that the artifacts are now **2.0.5.0**, **app1** is **2.2.5.0** and **app2** is **2.0.5.0**.
+Inspecting the build from the Pull request, you will see that the artifacts are now **2.0.7.0**, **app1** is **2.2.7.0** and **app2** is **2.0.7.0** (in my repository)

-| ![image](https://user-images.githubusercontent.com/10775043/231592915-f1f7e4d7-061c-42cd-9f37-dfd06c11b09d.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/22d28d32-b826-450f-af6c-77982235b57d) |
 |-|

-And all subsequent builds from main will now be 2.x. You will also see that the annotation stating that **No previous release found** has now gone.
-All builds from main will use the latest release version for upgrade testing. Inspecting the build step in the workflow, reveals that AL-Go for GitHub was able to locate the previous release
+> [!NOTE]
+> All subsequent builds from main will now be 2.x. You will also see that the annotation stating that **No previous release found** has now gone and all builds from main will use the latest release version for upgrade testing.

-| ![image](https://user-images.githubusercontent.com/10775043/231593914-0f83255e-d027-4826-b23a-17625ee3c2fb.png) |
+Inspecting the **build** step in the workflow, reveals that AL-Go for GitHub was able to locate the previous release
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/0b6cdefb-c379-4392-b11c-b714f19f75fb) |
 |-|

-Now, if you at some point in time need to create a hotfix for version **1.0.4**, you can simply select **Code** and switch to the release branch.
+Now, if you at some point in time need to create a hotfix for version **1.0.6**, you can simply select **Code** and switch to the release branch.

-| ![image](https://user-images.githubusercontent.com/10775043/231594145-f18ae77d-895b-41db-a04b-711028486896.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/e4a3b1fd-9c66-4558-aa6a-48b410e26cc9) |
 |-|

-Now you can navigate to the **HelloWorld.al** file, make a **simple change** and **commit the changes**.
+In the release branch, navigate to the **HelloWorld.al** file in the **app2** app, make a simple change and commit the changes directory to the release branch

-| ![image](https://user-images.githubusercontent.com/10775043/231594386-fbde022d-a53c-4eef-928d-92b2b2dace66.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/addda836-1cd4-478d-b33a-f62f46084851) |
 |-|

 Select **Actions** and see that a build was kicked off in the release branch.

-| ![image](https://user-images.githubusercontent.com/10775043/231594500-1d86a0f5-a001-4244-9005-7275e1b72278.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/5ae406bc-31e0-4433-ac5d-f9d3b12f7668) |
 |-|

-This version will use the **latest released build**, which has a version number lower than the one you are building as previous release and will use the version numbers from the release branch for versioning.
-After the build is completed, you will need to release this new build in order for CI/CD to see the new bits as a release.
+> [!NOTE]
+> This build will use the latest released build, which has a version number lower than the one you are building as previous release and will use the version numbers from the release branch for versioning.
+After the build is completed, you will need to release this new build in order for subsequent CI/CD builds from main to see the new bits as a release.

 The artifacts in the hotfix build looks like this:

-| ![image](https://user-images.githubusercontent.com/10775043/231595957-cd61fc0e-f7c7-4dc3-8fe7-dccad3de32a0.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/54dda4c3-4510-4b48-8437-24a0bece09a1) |
 |-|

-where the branch name main has been replaced by the release branch name.
+where the branch name main has been replaced by the release branch name and if you want to release this hotfix, you can run the **Create Release** and specify these parameters:
+
+| Name | Value |
+| :-- | :-- |
+| Use workflow from | `Branch: release/1.0.6` |
+| App version | `latest` |
+| Name of this release | `v1.0.8` |
+| Tag of this release | `1.0.8` |
+| Prerelease | :black_square_button: |
+| Draft | :black_square_button: |
+| Create Release Branch | :black_square_button: |
+| New Version Number | |
+| Direct Commit | :black_square_button: |
+| Use GhTokenWorkflow | :black_square_button: |
+
+> [!NOTE]
+> You must select to use workflow from the release branch. Else the create release workflow cannot locate the build in the release branch.
+> In this case, we select to not create a new release branch. We can just create any future hotfixes from the existing release branch if needed. We can also always create a release branch from a release later.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/e65f7a48-8c4d-426f-a6c4-97bb0d14b34d) |
+|-|
+
+After the release has been created we can (under Code) see that we have 2 releases:
+
+![image](https://github.com/microsoft/AL-Go/assets/10775043/ff0719ac-5510-4fca-9f54-10e19c3aaa4e)
+
+and clicking Releases will show the content of the releases:
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/6e52727e-bff3-431c-88ac-264965ad911f) |
+|-|
+
+> [!NOTE]
+> GitHub sorts the releases after the tag and sorting only works correctly if the tag is SemVer compatible (i.e. 3 tuples). This is the reason why AL-Go for GitHub forces you to enter a SemVer compatible version number in the tag when creating a new release.

 OK, so that is clear, versioning and releasing, pretty smart - but what is this project concept?

--- a/Workshop/ScheduledTestRuns.md
+++ b/Workshop/ScheduledTestRuns.md
@ -1,30 +1,51 @@
 # Scheduled Test Runs
+
 Building and testing your apps with the latest and the upcoming versions of Business Central is a crucial part of your DevOps setup. You will know when your app will be broken and can be prepared for the next version way ahead of time, making sure that your customers are not held up by your apps.

-To be able to run the workflows for testing against **Next Minor** and **Next Major** versions of Business Central, you will need an **insider SAS Token**, which is available on https://aka.ms/collaborate (Select **Packages** and **Working with Business Central insider builds**). The Direct URL is [here](https://partner.microsoft.com/en-us/dashboard/collaborate/packages/9387), but you will have to have an account with collaborate in order to use the link.
+AL-Go for GitHub includes 3 workflows for this purpose: **Test Current**, **Test Next Minor** and **Test Next Major**, which will build and test your app against the corresponding versions of Business Central.

-Use **https://crontab.guru** to create a crontab for the schedule you want to run your workflows on. I have selected the following:
+These workflows can be run manually by simply selecting the workflow and clicking **Run workflow**.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/7747d778-40f8-4d3e-9e26-02e3cf410834) |
+|-|
+
+Microsoft recommands running these workflows on a schedule to ensure that your app is ready for upcoming releases at all times and at the same time keeping compatibility with the versions you want to support.
+
+Use **Bing Copilot Chat** and ask it to generate the crontab you want (ex. *Create a crontab which triggers every saturday at 2am*) or use **https://crontab.guru** to create a crontab for the schedule you want to run your workflows on. I have selected the following for some of my apps:
 - I want to run the **Test Current** workflow every day at 2 in the morning. The crontab for that is: 0 2 * * *
 - I want to run the **Test Next Minor** workflow every Saturday at 2 in the morning. The crontab for that is: 0 2 * * 6
 - I want to run the **Test Next Major** workflow every Sunday at 2 in the morning. The crontab for that is: 0 2 * * 0

-In your single-project repository, select **Code**, navigate to **.github/AL-Go-Settings.json**, remove the 2 settings (**useCompilerFolder** and **doNotPublishApps**) we added to run tests and add 3 new settings:
+In your single-project repository, select **Code**, navigate to **.github/AL-Go-Settings.json**, remove the 2 settings (**useCompilerFolder** and **doNotPublishApps** ) we added to run tests and add 3 new settings:

-| ![image](https://user-images.githubusercontent.com/10775043/232339274-3c295485-ccc3-48b1-ab57-cd9ad85c5e04.png) |
+```json
+  "CurrentSchedule": "0 2 * * *",
+  "NextMinorSchedule": "0 2 * * 6",
+  "NextMajorSchedule": "0 2 * * 0"
+```
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/c82e1393-e7b1-4e3a-8b64-488c107fff7b) |
 |-|

 Now, select **Actions** and run the **Update AL-Go System Files** workflow in order for the schedule to take effect. You can see the changes to the workflows done by the **Update AL-Go System Files** workflow in the **pull request**.

-| ![image](https://user-images.githubusercontent.com/10775043/232339690-047441f5-cd65-43f9-a40a-5b46e923c77d.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/4a65a694-12b5-4896-8323-1b49d26c1a56) |
 |-|

-Now, modify .github/Test Current.settings.json and add the two settings (useCompilerFolder and doNotPublishApps) in that one
+Merge the Pull Request and remove the temporary branch.

-| ![image](https://user-images.githubusercontent.com/10775043/232340747-6eb81ab9-0bb2-4947-9416-8af2108de834.png) |
+Now, you could modify **.github/Test Current.settings.json** and add the two settings (useCompilerFolder and doNotPublishApps) in that one
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/e17aaebc-4cb9-405e-89d7-9aee55eba66f) |
 |-|

 Which now means that your Test Current workflow, which runs every night will run all tests and other workflows will not.

+> [!NOTE]
+> While the name of the workflow specific settings file is based on the workflow title (**Test Next Major.settings.json**), the workflow schedule setting needs to be in AL-Go-Settings.json and is based on the filename of the workflow (**NextMajorSchedule**):
+> 
+> ![image](https://github.com/microsoft/AL-Go/assets/10775043/6d8f15f3-8415-43d1-b7b6-3e08c545e500)
+
 Now we know when our app gets broken and doesn't work anymore, but what about performance regressions?

 ---
--- a/Workshop/TheDevelopmentProcess.md
+++ b/Workshop/TheDevelopmentProcess.md
@ -1,4 +1,4 @@
-# The Development Process
+# FUTURE TOPIC: The Development Process

 This topic will be finalized later

--- a/Workshop/Versioning.md
+++ b/Workshop/Versioning.md
@ -1,10 +1,10 @@
 # Versioning
 Understanding how AL-Go for GitHub is doing **versioning** and **naming** is important for your day to day use of AL-Go for GitHub.

-As we saw earlier, the **artifacts** from the first successful build in my repository was called version **repo1-main-Apps-1.0.2.0**.
+As we saw earlier, the **artifacts** from the first successful build in my repository was called version **repo1-main-Apps-1.0.4.0**.
 Downloading the artifact and unpacking reveals the app inside. The app inside is using the same naming strategy as VS Code: `<publisher>_<name>_<version>`

-| ![image](https://user-images.githubusercontent.com/10775043/231545533-be33a8f6-88ea-4b05-b343-d71aaf9ee5d4.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/907ff953-6496-46ff-b3bc-fc934da7bb50) |
 |-|

 Here, the app has the same version number as the artifact, but is it always like that?
@ -15,50 +15,80 @@ As you know, the build number consists of 4 tuples: **major.minor.build.revision
 - The **build** tuple is (by default) the GITHUB_RUN_NUMBER, which is a unique number for each time the CI/CD workflow is run, starting with 1.
 - The **revision** typle is (by default) the GITHUB_RUN_ATTEMPT, which is the number of attempts, starting with 0. In my example above, I did re-run the CI/CD workflow once to end up with .1.

-In order to better understand this, select **Code** and navigate to the **app.json** file under the **app1** folder. Edit the file and change the version number to **1.2.5.6**.
+In order to better understand this, select **Code** and navigate to the **app.json** file under the **app1** folder. Edit the file and change the version number to **1.2.3.4**.

-| ![image](https://user-images.githubusercontent.com/10775043/231559564-43683818-c540-4ba3-86b4-832c67545ae4.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/df24b30b-df74-4def-9134-49f8bc8e13f1) |
 |-|

-**Commit** the changes, select **Actions** and wait for the build to complete.
+**Commit** the changes directly, select **Actions** and wait for the build to complete.

-| ![image](https://user-images.githubusercontent.com/10775043/231547295-accc7f9d-7c19-472f-80df-71d1897d91a5.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/c2c45e8d-aeb0-4da1-8b23-85eee843a25a) |
 |-|

-Select the **Update app.json** workflow, **scroll down** to the artifacts and **download** the new apps artifact.
+Select the **Update app.json** workflow, **scroll down** to the artifacts and **download** the new apps artifact and open it.

-| ![image](https://user-images.githubusercontent.com/10775043/231559045-1e071522-80c3-456c-9379-9b51a550f60a.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/f5009c5f-2cf6-45ec-9de5-c7473722e092) |
 |-|

-Now the project (in this case the repository), which really is a collection of apps, is still version **1.0** (RepoVersion never changed - is still 1.0 = default) and **app1** is **1.2** (major and minor from app.json). Build is **3** (3rd build) and revision is still **0**.
+> [!NOTE]
+> The project (in this case the repository), which really is a collection of apps, is still version **1.0** (RepoVersion never changed - is still 1.0 = default) and **app1** is **1.2** (major and minor from app.json). Build is **5** (5th build in my repo) and revision is still **0**.

 Scroll back up, locate the **Re-run all jobs** button and click it. Wait for the **2nd attempt** to complete and inspect the artifact for the re-run.

-| ![image](https://user-images.githubusercontent.com/10775043/231560877-bc9354ff-40e9-4705-91d4-6217133a1e73.png) |
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/4a20ed83-8fb7-4a0a-b030-e1c1cb392a27) |
 |-|

-Now revision became **1** as we had another attempt at building the app.
+Now revision became **1** as we had a 2nd attempt at building the app.

-Next, let's create another app in the same repo. **app2** with ID range **56000..56100** and enter **Y** in **Direct Commit**.
+Next, let's create another app, by running the **Create a new app** workflow again in the same repo and specify:

-| ![image](https://user-images.githubusercontent.com/10775043/231561391-7350981e-e20d-49a1-9479-4271a7e6ddd8.png) |
+| Name | Value |
+| :-- | :-- |
+| Use workflow from | `Branch: main` |
+| Project name | `.` |
+| Name | `app2` |
+| Publisher | `<your publisher name>` |
+| ID Range (from..to) | `56000..56100` |
+| Include Sample Code | :ballot_box_with_check: |
+| Direct Commit | :ballot_box_with_check: |
+| Use GhTokenWorkflow | :black_square_button: |
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/fc7e3131-8ac3-4054-a131-c4e8da023fec) |
 |-|

-When the **Create a new app workflow** is done, select the **CI/CD** workflow and click **Run workflow** to run the workflow manually. When the workflow is complete, download and inspect the artifacts generated
+When the **Create a new app** workflow is done, navigate to Code and modify the name of the object in the **app2/HelloWorld.al** file to **CustomerListExt2**. This will kick off another CI/CD workflow.

-| ![image](https://user-images.githubusercontent.com/10775043/231564490-b8c414a8-cf6b-4660-bd81-4c98571812a6.png) |
+> [!NOTE]
+> You might wonder why the **Create a new app** workflow with direct commit didn't kick off a new CI/CD build. This is due to a GitHub security feature that one workflow cannot by default kick off another workflow. Checking the **Use GhTokenWorkflow for PR/Commit** checkbox will allow GitHub to run CI/CD from the workflow.
+
+ When the CI/CD workflow is complete, download and inspect the artifacts generated
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/54d8ea19-d17e-4538-917f-661a921d474b) |
 |-|

-**App2** still has version **1.0** in **app.json**, hence the **1.0.4.0** version number.
+**App2** still has version **1.0** in **app.json**, hence the **1.0.6.0** version number.

-If we want to increment the version number of the project and all apps, you can run the **Increment Version Number** workflow.
+If we want to increment the version number of the project and all apps, you can run the **Increment Version Number** workflow and specify the following values

-| ![image](https://user-images.githubusercontent.com/10775043/231565483-5f92751e-ed59-40c9-ba80-c90effc9a4e3.png) |
+| Name | Value |
+| :-- | :-- |
+| Use workflow from | `Branch: main` |
+| Project name patterns | `*` |
+| Updated Version Number | `+0.1` |
+| Direct Commit | :black_square_button: |
+| Use GhTokenWorkflow | :black_square_button: |
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/dbba8aa8-6a8b-446d-8bac-42b07dc79c36) |
 |-|

-Specifying **+0.1** will add 1 to the minor version of all apps and to the repo version number. Wait for the workflow to complete, select **Pull requests** and select the **Increment Version Number by 0.1** Pull request and inspect what the workflow is trying to change for you. At this time, we will **NOT** merge the Pull request as changing version numbers like this is typically done during a release.
+> [!NOTE]
+> Specifying **+0.1** will add 1 to the minor version of all apps and to the repo version number, specifying **+1.0** will add 1 to the major version and if you specify **2.0** (without the +), it will set major.minor to 2.0 no matter what value was earlier set, but... you cannot set a version number, which is lower than was already set.

-| ![image](https://user-images.githubusercontent.com/10775043/231566085-3fd6ae4a-e88e-4dfd-be60-3ac95767d14a.png) |
+Wait for the workflow to complete, select **Pull requests** and select the **Increment Version Number by 0.1** Pull request and inspect what the workflow is trying to change for you.
+
+At this time, we will **NOT** merge the Pull request as changing version numbers like this is typically done during a release.
+
+| ![image](https://github.com/microsoft/AL-Go/assets/10775043/70f761c0-4ae6-42de-84ba-fe67d4a98264) |
 |-|

 Select **Conversation**, click **Close pull request** and **delete the branch**.
--- a/e2eTests/Test-Functions.ps1
+++ b/e2eTests/Test-Functions.ps1
@ -80,20 +80,20 @@ function Test-ArtifactsFromRun {
    foreach($type in $expectedArtifacts.Keys) {
        $expected = $expectedArtifacts."$type"
        Write-Host "Type: $type, Expected: $expected"
+        # Reason for the ? instead of \ is that the folder separator is \ on Windows and / on Linux
        if ($type -eq 'thisbuild') {
            $fileNamePattern = "thisbuild-*-Apps?*$appVersion.*.*.app"
-            Write-Host "FileNamePattern: $fileNamePattern"
-            $actual = @(Get-ChildItem -Path $path -File -Recurse | Where-Object {
-                $_.FullName.Substring($path.Length+1) -like $fileNamePattern
-            }).Count
+        }
+        elseif ($type -eq 'github-pages') {
+            $fileNamePattern = "github-pages?artifact.tar"
        }
        else {
            $fileNamePattern = "*-$type-$repoVersion.*.*?*$appVersion.*.*.app"
-            Write-Host "FileNamePattern: $fileNamePattern"
-            $actual = @(Get-ChildItem -Path $path -File -Recurse | Where-Object {
-                $_.FullName.SubString($path.Length+1) -like $fileNamePattern
-            }).Count
        }
+        Write-Host "FileNamePattern: $fileNamePattern"
+        $actual = @(Get-ChildItem -Path $path -File -Recurse | Where-Object {
+            $_.FullName.Substring($path.Length+1) -like $fileNamePattern
+        }).Count
        if ($actual -ne $expected) {
            Write-Host "::Error::Expected number of $type was $expected. Actual number of $type is $actual"
            $err = $true
--- a/e2eTests/Workflows/RunDeployReferenceDocumentation.ps1
+++ b/e2eTests/Workflows/RunDeployReferenceDocumentation.ps1
@ -0,0 +1,12 @@
+function RunDeployReferenceDocumentation {
+    Param(
+        [switch] $wait,
+        [string] $repository,
+        [string] $branch = "main"
+    )
+
+    $workflowName = 'Deploy Reference Documentation'
+    $parameters = @{
+    }
+    RunWorkflow -name $workflowName -parameters $parameters -wait:$wait -branch $branch -repository $repository
+}
--- a/e2eTests/e2eTestHelper.psm1
+++ b/e2eTests/e2eTestHelper.psm1
@ -207,11 +207,45 @@ function DownloadWorkflowLog {
    Expand-Archive -Path $tempFileName -DestinationPath $path
 }

+function CancelAllWorkflows {
+    Param(
+        [string] $repository,
+        [switch] $noDelay
+    )
+    if (-not $noDelay.IsPresent) {
+        Start-Sleep -Seconds 60
+    }
+    $runs = gh api /repos/$repository/actions/runs | ConvertFrom-Json
+    foreach($run in $runs.workflow_runs) {
+        Write-Host $run.name
+        if ($run.status -eq 'in_progress') {
+            Write-Host "Cancelling $($run.name) run $($run.id)"
+            gh api --method POST /repos/$repository/actions/runs/$($run.id)/cancel | Out-Null
+        }
+    }
+}
+
+function WaitAllWorkflows {
+    Param(
+        [string] $repository,
+        [switch] $noDelay,
+        [switch] $noError
+    )
+    if (-not $noDelay.IsPresent) {
+        Start-Sleep -Seconds 60
+    }
+    $runs = gh api /repos/$repository/actions/runs | ConvertFrom-Json
+    foreach($run in $runs.workflow_runs) {
+        WaitWorkflow -repository $repository -runid $run.id -noDelay -noError:$noError
+    }
+}
+
 function WaitWorkflow {
    Param(
        [string] $repository,
        [string] $runid,
-        [switch] $noDelay
+        [switch] $noDelay,
+        [switch] $noError
    )

    $delay = !$noDelay.IsPresent
@ -237,7 +271,7 @@ function WaitWorkflow {
    Write-Host
    Write-Host $run.conclusion
    if ($run.conclusion -ne "Success") {
-        throw "Workflow $($run.name), conclusion $($run.conclusion), url = $($run.html_url)"
+        if (-not $noError.IsPresent) { throw "Workflow $($run.name), conclusion $($run.conclusion), url = $($run.html_url)" }
    }
 }

@ -577,6 +611,7 @@ function Test-LogContainsFromRun {
 . (Join-Path $PSScriptRoot "Workflows\RunAddExistingAppOrTestApp.ps1")
 . (Join-Path $PSScriptRoot "Workflows\RunCICD.ps1")
 . (Join-Path $PSScriptRoot "Workflows\RunCreateApp.ps1")
+. (Join-Path $PSScriptRoot "Workflows\RunDeployReferenceDocumentation.ps1")
 . (Join-Path $PSScriptRoot "Workflows\RunCreateOnlineDevelopmentEnvironment.ps1")
 . (Join-Path $PSScriptRoot "Workflows\RunCreateRelease.ps1")
 . (Join-Path $PSScriptRoot "Workflows\RunCreateTestApp.ps1")
--- a/e2eTests/scenarios/ReferenceDocumentation/runtest.ps1
+++ b/e2eTests/scenarios/ReferenceDocumentation/runtest.ps1
@ -0,0 +1,127 @@
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalVars', '', Justification = 'Global vars used for local test execution only.')]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '', Justification = 'All scenario tests have equal parameter set.')]
+Param(
+    [switch] $github,
+    [string] $githubOwner = $global:E2EgithubOwner,
+    [string] $repoName = [System.IO.Path]::GetFileNameWithoutExtension([System.IO.Path]::GetTempFileName()),
+    [string] $token = ($Global:SecureE2EPAT | Get-PlainText),
+    [string] $pteTemplate = $global:pteTemplate,
+    [string] $appSourceTemplate = $global:appSourceTemplate,
+    [string] $adminCenterApiToken = ($global:SecureAdminCenterApiToken | Get-PlainText),
+    [string] $licenseFileUrl = ($global:SecureLicenseFileUrl | Get-PlainText)
+)
+
+Write-Host -ForegroundColor Yellow @'
+#  _____       __                               _____                                        _        _   _
+# |  __ \     / _|                             |  __ \                                      | |      | | (_)
+# | |__) |___| |_ ___ _ __ ___ _ __   ___ ___  | |  | | ___   ___ _   _ _ __ ___   ___ _ __ | |_ __ _| |_ _  ___  _ __
+# |  _  // _ \  _/ _ \ '__/ _ \ '_ \ / __/ _ \ | |  | |/ _ \ / __| | | | '_ ` _ \ / _ \ '_ \| __/ _` | __| |/ _ \| '_ \
+# | | \ \  __/ ||  __/ | |  __/ | | | (_|  __/ | |__| | (_) | (__| |_| | | | | | |  __/ | | | || (_| | |_| | (_) | | | |
+# |_|  \_\___|_| \___|_|  \___|_| |_|\___\___| |_____/ \___/ \___|\__,_|_| |_| |_|\___|_| |_|\__\__,_|\__|_|\___/|_| |_|
+#
+#
+# This test tests the following scenario:
+#
+#  - Create a new repository based on the PTE template with 1 app
+#  - Enable GitHub pages (set to GitHub Actions)
+#  - Run the "CI/CD" workflow
+#  - Run the Deploy Reference Documentation workflow
+#  - Check github pages website generated
+#  - Change settings to use continuous deployment of ALDoc and modify the header
+#  - Run the "CI/CD" workflow
+#  - Check that the new header is used
+#  - Set runs-on to ubuntu-latest (and use CompilerFolder)
+#  - Modify the header again
+#  - Run the "CI/CD" workflow again
+#  - Check that the new header is used
+#  - Cleanup repositories
+#
+'@
+
+$errorActionPreference = "Stop"; $ProgressPreference = "SilentlyContinue"; Set-StrictMode -Version 2.0
+Push-Location
+
+Remove-Module e2eTestHelper -ErrorAction SilentlyContinue
+Import-Module (Join-Path $PSScriptRoot "..\..\e2eTestHelper.psm1") -DisableNameChecking
+
+$repository = "$githubOwner/$repoName"
+$branch = "main"
+
+$template = "https://github.com/$pteTemplate"
+
+# Login
+SetTokenAndRepository -github:$github -githubOwner $githubOwner -token $token -repository $repository
+
+$appName = 'MyApp'
+$publisherName = 'Freddy'
+
+# Create repository1
+CreateAlGoRepository `
+    -github:$github `
+    -template $template `
+    -repository $repository `
+    -branch $branch `
+    -contentScript {
+        Param([string] $path)
+        $null = CreateNewAppInFolder -folder $path -name $appName -publisher $publisherName
+        Add-PropertiesToJsonFile -path (Join-Path $path '.github/AL-Go-Settings.json') -properties @{ "alDoc" = @{ "ContinuousDeployment" = $true; "deployToGitHubPages" = $false } }
+    }
+
+# Cancel all running workflows
+CancelAllWorkflows -repository $repository
+
+$repoPath = (Get-Location).Path
+$run = RunCICD -repository $repository -branch $branch
+
+# Wait for CI/CD workflow of repository1 to finish
+WaitWorkflow -repository $repository -runid $run.id
+
+# test artifacts generated in repository1
+Test-ArtifactsFromRun -runid $run.id -folder 'artifacts' -expectedArtifacts @{"Apps"=1;"TestApps"=0;"Dependencies"=0;"github-pages"=1} -repoVersion '1.0' -appVersion '1.0'
+
+# Set GitHub Pages in repository to GitHub Actions
+gh api --method POST /repos/$repository/pages -f build_type=workflow | Out-Null
+
+# Add setting to deploy to GitHub Pages
+Pull
+Add-PropertiesToJsonFile -path '.github/AL-Go-Settings.json' -properties @{ "alDoc" = @{ "ContinuousDeployment" = $false; "deployToGitHubPages" = $true } }
+CommitAndPush -commitMessage 'DeployToGitHubPages'
+
+# Run Deploy Reference Documentation and wait for it to finish
+RunDeployReferenceDocumentation -repository $repository -wait | Out-Null
+
+# Get Pages URL and read the content
+$pagesInfo = gh api /repos/$repository/pages | ConvertFrom-Json
+$html = (Invoke-WebRequest -Uri $pagesInfo.html_url -UseBasicParsing).Content
+$html | Should -belike "*Documentation for $repository*"
+
+# Remove downloaded artifacts
+Remove-Item -Path 'artifacts' -Recurse -Force
+
+# Set GitHubRunner and runs-on to ubuntu-latest (and use CompilerFolder)
+Pull
+Add-PropertiesToJsonFile -path '.github/AL-Go-Settings.json' -properties @{ "runs-on" = "ubuntu-latest"; "gitHubRunner" = "ubuntu-latest"; "UseCompilerFolder" = $true; "doNotPublishApps" = $true }
+CommitAndPush -commitMessage 'Shift to Linux'
+
+# Upgrade AL-Go System Files
+RunUpdateAlGoSystemFiles -directCommit -commitMessage 'Update system files' -wait -templateUrl $template -ghTokenWorkflow $token | Out-Null
+
+# Cancel all running workflows
+CancelAllWorkflows -repository $repository
+
+# Set continuous deployment of ALDoc and modify the header
+Pull
+Add-PropertiesToJsonFile -path '.github/AL-Go-Settings.json' -properties @{ "alDoc" = @{ "ContinuousDeployment" = $true; "deployToGitHubPages" = $true; "Header" = "Documentazione per {REPOSITORY}" } }
+CommitAndPush -commitMessage 'Shift to Linux'
+
+# Wait for CI/CD run after config change
+WaitAllWorkflows -repository $repository -noError
+
+# Get Pages URL and read the content
+$pagesInfo = gh api /repos/$repository/pages | ConvertFrom-Json
+$html = (Invoke-WebRequest -Uri $pagesInfo.html_url -UseBasicParsing).Content
+$html | Should -belike "*Documentazione per $repository*"
+
+Pop-Location
+
+RemoveRepository -repository $repository -path $repoPath