v6.0

Issues

• Issue 1184 Publish to Environment fails on 'Permission Denied'
• AL Language extension in 25.0 doesn't contain the linux executable, use dotnet to invoke the dll instead.

New Settings

• deliverTo<deliverytarget> now has an additional property called ContinuousDelivery, indicating whether or not to run continuous delivery to this deliveryTarget. Default is true.
• trustMicrosoftNuGetFeeds Unless this setting is set to false, AL-Go for GitHub will trust the NuGet feeds provided by Microsoft. The feeds provided by Microsoft contains all Microsoft apps, all Microsoft symbols and symbols for all AppSource apps.
• trustedNuGetFeeds - can be an array of NuGet feed specifications, which AL-Go for GitHub will use for dependency resolution. Every feed specification must include a URL property and can optionally include a few other properties:
  • url - The URL of the feed (examples: https://pkgs.dev.azure.com/myorg/apps/\_packaging/myrepo/nuget/v3/index.json or https://nuget.pkg.github.com/mygithuborg/index.json").
  • patterns - AL-Go for GitHub will only trust packages, where the ID matches this pattern. Default is all packages (*).
  • fingerprints - If specified, AL-Go for GitHub will only trust packages signed with a certificate with a fingerprint matching one of the fingerprints in this array.
  • authTokenSecret - If the NuGet feed specified by URL is private, the authTokenSecret must be the name of a secret containing the authentication token with permissions to search and read packages from the NuGet feed.

Support for delivering to GitHub Packages and NuGet

With this release the implementation for delivering to NuGet packages (by adding the NuGetContext secret), is similar to the functionality behind delivering to GitHub packages and the implementation is no longer in preview.

Allow GitHubRunner and GitHubRunnerShell as project settings

Previously, AL-Go required the GitHubRunner and GitHubRunnerShell settings to be set on repository level. This has now been changed such that they can be set on project level.

v5.3

Issues

• Issue 1105 Increment Version Number - repoVersion in .github/AL-Go-Settings.json is not updated
• Issue 1073 Publish to AppSource - Automated validation: failure
• Issue 980 Allow Scope to be PTE in continuousDeployment for PTE extensions in Sandbox (enhancement request)
• Issue 1079 AppSource App deployment failes with PerTenantExtensionCop Error PTE0001 and PTE0002
• Issue 866 Accessing GitHub Environment Variables in DeployToCustom Scenarios for PowerShell Scripts
• Issue 1083 SyncMode for custom deployments?
• Issue 1109 Why filter deployment settings?
• Fix issue with github ref when running reusable workflows
• Issue 1098 Support for specifying the name of the AZURE_CREDENTIALS secret by adding a AZURE_CREDENTIALSSecretName setting
• Fix placeholder syntax for git ref in PullRequestHandler.yaml
• Issue 1164 Getting secrets from Azure key vault fails in Preview

Dependencies to PowerShell modules

AL-Go for GitHub relies on specific PowerShell modules, and the minimum versions required for these modules are tracked in Packages.json file. Should the installed modules on the GitHub runner not meet these minimum requirements, the necessary modules will be installed as needed.

Support managed identities and federated credentials

All authentication context secrets now supports managed identities and federated credentials. See more here. Furthermore, you can now use https://aka.ms/algosecrets#authcontext to learn more about the formatting of that secret.

Business Central Performance Toolkit Test Result Viewer

In the summary after a Test Run, you now also have the result of performance tests.

Support Ubuntu runners for all AL-Go workflows

Previously, the workflows "Update AL-Go System Files" and "TroubleShooting" were hardcoded to always run on windows-latest to prevent deadlocks and security issues.
From now on, ubuntu-lates will also be allowed for these mission critical workflows, when changing the runs-on setting. Additionally, only the value pwsh for shell setting is allowed when using ubuntu-latest runners.

Updated AL-Go telemetry

AL-Go for GitHub now includes a new telemetry module. For detailed information on how to enable or disable telemetry and to see what data AL-Go logs, check out this article.

New Settings

• deployTo<environmentName>: is not really new, but has a new property:

  • Scope = specifies the scope of the deployment: Dev, PTE. If not specified, AL-Go for GitHub will always use the Dev Scope for AppSource Apps, but also for PTEs when deploying to sandbox environments when impersonation (refreshtoken) is used for authentication.
  • BuildMode = specifies which buildMode to use for the deployment. Default is to use the Default buildMode.
  • <custom> = custom properties are now supported and will be transferred to a custom deployment script in the hashtable.

• bcptThresholds is a JSON object with properties for the default thresholds for the Business Central Performance Toolkit

  • DurationWarning - a warning is issued if the duration of a bcpt test degrades more than this percentage (default 10)
  • DurationError - an error is issued if the duration of a bcpt test degrades more than this percentage (default 25)
  • NumberOfSqlStmtsWarning - a warning is issued if the number of SQL statements from a bcpt test increases more than this percentage (default 5)
  • NumberOfSqlStmtsError - an error is issued if the number of SQL statements from a bcpt test increases more than this percentage (default 10)

Note

Duration thresholds are subject to varying results depending on the performance of the agent running the tests. Number of SQL statements executed by a test is often the most reliable indicator of performance degredation.

v5.2

Issues

• Issue 1084 Automatic updates for AL-Go are failing when main branch requires Pull Request

New Settings

• PowerPlatformSolutionFolder: Contains the name of the folder containing a PowerPlatform Solution (only one)
• DeployTo<environment> now has two additional properties companyId is the Company Id from Business Central (for PowerPlatform connection) and ppEnvironmentUrl is the Url of the PowerPlatform environment to deploy to.

New Actions

• BuildPowerPlatform: to build a PowerPlatform Solution
• DeployPowerPlatform: to deploy a PowerPlatform Solution
• PullPowerPlatformChanges: to pull changes made in PowerPlatform studio into the repository
• ReadPowerPlatformSettings: to read settings and secrets for PowerPlatform deployment
• GetArtifactsForDeployment: originally code from deploy.ps1 to retrieve artifacts for releases or builds - now as an action to read apps into a folder.

New Workflows

• Pull PowerPlatform Changes for pulling changes from your PowerPlatform development environment into your AL-Go for GitHub repository
• Push PowerPlatform Changes for pushing changes from your AL-Go for GitHub repository to your PowerPlatform development environment

Note

PowerPlatform workflows are only available in the PTE template and will be removed if no PowerPlatformSolutionFolder is defined in settings.

New Scenarios (Documentation)

• Connect your GitHub repository to Power Platform
• How to set up Service Principal for Power Platform
• Try one of the Business Central and Power Platform samples
• Publish To AppSource

Note

PowerPlatform functionality are only available in the PTE template.

v5.1

Issues

• Issue 1019 CI/CD Workflow still being scheduled after it was disabled
• Issue 1021 Error during Create Online Development Environment action
• Issue 1022 Error querying artifacts: No such host is known. (bcartifacts-exdbf9fwegejdqak.blob.core.windows.net:443)
• Issue 922 Deploy Reference Documentation (ALDoc) failed with custom
• ContainerName used during build was invalid if project names contained special characters
• Issue 1009 by adding a includeDependencies property in DeliverToAppSource
• Issue 997 'Deliver to AppSource' action fails for projects containing a space
• Issue 987 Resource not accessible by integration when creating release from specific version
• Issue 979 Publish to AppSource Documentation
• Issue 1018 Artifact setting - possibility to read version from app.json
• Issue 1008 Allow PullRequestHandler to use ubuntu or self hosted runners for all jobs except for pregateCheck
• Issue 962 Finer control of "shell"-property
• Issue 1041 Harden the version comparison when incrementing version number
• Issue 1042 Downloading artifacts from GitHub doesn't work with branch names which include forward slashes

Better artifact selection

The artifact setting in your project settings file can now contain a * instead of the version number. This means that AL-Go for GitHub will determine the application dependency for your projects together with the applicationDependency setting and determine which Business Central version is needed for the project.

• "artifact": "//*//latest" will give you the latest Business Central version, higher than your application dependency and with the same major.minor as your application dependency.
• "artifact": "//*//first" will give you the first Business Central version, higher than your application dependency and with the same major.minor as your application dependency.

New Settings

• deliverToAppSource: a JSON object containing the following properties
  • productId must be the product Id from partner Center.
  • mainAppFolder specifies the appFolder of the main app if you have multiple apps in the same project.
  • continuousDelivery can be set to true to enable continuous delivery of every successful build to AppSource Validation. Note that the app will only be in preview in AppSource and you will need to manually press GO LIVE in order for the app to be promoted to production.
  • includeDependencies can be set to an array of file names (incl. wildcards) which are the names of the dependencies to include in the AppSource submission. Note that you need to set generateDependencyArtifact in the project settings file to true in order to include dependencies.
• Add shell as a property under DeployTo structure

Deprecated Settings

• appSourceContinuousDelivery is moved to the deliverToAppSource structure
• appSourceMainAppFolder is moved to the deliverToAppSource structure
• appSourceProductId is moved to the deliverToAppSource structure

New parameter -clean on localdevenv and clouddevenv

Adding -clean when running localdevenv or clouddevenv will create a clean development environment without compiling and publishing your apps.

v5.0

Issues

• Issue 940 Publish to Environment is broken when specifying projects to publish
• Issue 994 CI/CD ignores Deploy to GitHub Pages in private repositories

New Settings

• UpdateALGoSystemFilesEnvironment: The name of the environment that is referenced in job UpdateALGoSystemFiles in the Update AL-Go System Files workflow. See jobs.<job_id>.environment for more information. Currently, only setting the environment name is supported.

Issues

• Support release branches that start with releases/
• Issue 870 Improve Error Handling when CLI is missing
• Issue 889 CreateRelease and IncrementVersionNumber workflow did not handle wild characters in appFolders, testFolders or bcptTestFolders settings.
• Issue 973 Prerelease is not used for deployment

Build modes

AL-Go ships with Default, Translated and Clean mode out of the box. Now you can also define custom build modes in addition to the ones shipped with AL-Go. This allows you to define your own build modes, which can be used to build your apps in different ways. By default, a custom build mode will build the apps similarly to the Default mode but this behavior can be overridden in e.g. script overrides in your repository.

v4.1

New Settings

• templateSha: The SHA of the version of AL-Go currently used

New Actions

• DumpWorkflowInfo: Dump information about running workflow
• Troubleshooting : Run troubleshooting for repository

Update AL-Go System Files

Add another parameter when running Update AL-Go System Files, called downloadLatest, used to indicate whether to download latest version from template repository. Default value is true.
If false, the templateSha repository setting is used to download specific AL-Go System Files when calculating new files.

Issues

• Issue 782 Exclude '.altestrunner/' from template .gitignore
• Issue 823 Dependencies from prior build jobs are not included when using useProjectDependencies
• App artifacts for version 'latest' are now fetched from the latest CICD run that completed and successfully built all the projects for the corresponding branch.
• Issue 824 Utilize useCompilerFolder setting when creating an development environment for an AL-Go project.
• Issue 828 and 825 display warnings for secrets, which might cause AL-Go for GitHub to malfunction

New Settings

• alDoc : JSON object with properties for the ALDoc reference document generation
  • continuousDeployment = Determines if reference documentation will be deployed continuously as part of CI/CD. You can run the Deploy Reference Documentation workflow to deploy manually or on a schedule. (Default false)
  • deployToGitHubPages = Determines whether or not the reference documentation site should be deployed to GitHub Pages for the repository. In order to deploy to GitHub Pages, GitHub Pages must be enabled and set to GitHub Actions. (Default true)
  • maxReleases = Maximum number of releases to include in the reference documentation. (Default 3)
  • groupByProject = Determines whether projects in multi-project repositories are used as folders in reference documentation
  • includeProjects = An array of projects to include in the reference documentation. (Default all)
  • excludeProjects = An array of projects to exclude in the reference documentation. (Default none)-
  • header = Header for the documentation site. (Default: Documentation for...)
  • footer = Footer for the documentation site. (Default: Made with...)
  • defaultIndexMD = Markdown for the landing page of the documentation site. (Default: Reference documentation...)
  • defaultReleaseMD = Markdown for the landing page of the release sites. (Default: Release reference documentation...)
  • Note that in header, footer, defaultIndexMD and defaultReleaseMD you can use the following placeholders: {REPOSITORY}, {VERSION}, {INDEXTEMPLATERELATIVEPATH}, {RELEASENOTES}

New Workflows

• Deploy Reference Documentation is a workflow, which you can invoke manually or on a schedule to generate and deploy reference documentation using the aldoc tool, using the ALDoc setting properties described above.
• Troubleshooting is a workflow, which you can invoke manually to run troubleshooting on the repository and check for settings or secrets, containing illegal values. When creating issues on https://github.com/microsoft/AL-Go/issues, we might ask you to run the troubleshooter to help identify common problems.

Support for ALDoc reference documentation tool

ALDoc reference documentation tool is now supported for generating and deploying reference documentation for your projects either continuously or manually/scheduled.

v4.0

Removal of the InsiderSasToken

As of October 1st 2023, Business Central insider builds are now publicly available. When creating local containers with the insider builds, you will have to accept the insider EULA (https://go.microsoft.com/fwlink/?linkid=2245051) in order to continue.

AL-Go for GitHub allows you to build and test using insider builds without any explicit approval, but please note that the insider artifacts contains the insider Eula and you automatically accept this when using the builds.

Issues

• Issue 730 Support for external rulesets.
• Issue 739 Workflow specific KeyVault settings doesn't work for localDevEnv
• Using self-hosted runners while using Azure KeyVault for secrets or signing might fail with C:\Modules doesn't exist
• PullRequestHandler wasn't triggered if only .md files where changes. This lead to PRs which couldn't be merged if a PR status check was mandatory.
• Artifacts names for PR Builds were using the merge branch instead of the head branch.

New Settings

• enableExternalRulesets: set this setting to true if you want to allow AL-Go to automatically download external references in rulesets.
• deliverTo<deliveryTarget>: is not really new, but has new properties and wasn't documented. The complete list of properties is here (note that some properties are deliveryTarget specific):
  • Branches = an array of branch patterns, which are allowed to deliver to this deliveryTarget. (Default [ "main" ])
  • CreateContainerIfNotExist = [Only for DeliverToStorage] Create Blob Storage Container if it doesn't already exist. (Default false)

Deployment

Environment URL is now displayed underneath the environment being deployed to in the build summary. For Custom Deployment, the script can set the GitHub Output variable environmentUrl in order to show a custom URL.

v3.3

Issues

• Issue 227 Feature request: Allow deployments with "Schema Sync Mode" = Force
• Issue 519 Deploying to onprem environment
• Issue 520 Automatic deployment to environment with annotation
• Issue 592 Internal Server Error when publishing
• Issue 557 Deployment step fails when retried
• After configuring deployment branches for an environment in GitHub and setting Deployment Branch Policy to Protected Branches, AL-Go for GitHub would fail during initialization (trying to get environments for deployment)
• The DetermineDeploymentEnvironments doesn't work in private repositories (needs the GITHUB_TOKEN)
• Issue 683 Settings from GitHub variables ALGoRepoSettings and ALGoOrgSettings are not applied during build pipeline
• Issue 708 Inconsistent AuthTokenSecret Behavior in Multiple Projects: 'Secrets are not available'

Breaking changes

Earlier, you could specify a mapping to an environment name in an environment secret called <environmentname>_EnvironmentName, <environmentname>-EnvironmentName or just EnvironmentName. You could also specify the projects you want to deploy to an environment as an environment secret called Projects.

This mechanism is no longer supported and you will get an error if your repository has these secrets. Instead you should use the DeployTo<environmentName> setting described below.

Earlier, you could also specify the projects you want to deploy to an environment in a setting called <environmentName>_Projects or <environmentName>-Projects. This is also no longer supported. Instead use the DeployTo<environmentName> and remove the old settings.

New Actions

• DetermineDeliveryTargets: Determine which delivery targets should be used for delivering artifacts from the build job.
• DetermineDeploymentEnvironments: Determine which deployment environments should be used for the workflow.

New Settings

• projectName: project setting used as friendly name for an AL-Go project, to be used in the UI for various workflows, e.g. CICD, Pull Request Build.
• fullBuildPatterns: used by DetermineProjectsToBuild action to specify changes in which files and folders would trigger a full build (building all AL-Go projects).
• excludeEnvironments: used by DetermineDeploymentEnvironments action to exclude environments from the list of environments considered for deployment.
• deployTo<environmentName>: is not really new, but has new properties. The complete list of properties is here:
  • EnvironmentType = specifies the type of environment. The environment type can be used to invoke a custom deployment. (Default SaaS)
  • EnvironmentName = specifies the "real" name of the environment if it differs from the GitHub environment
  • Branches = an array of branch patterns, which are allowed to deploy to this environment. (Default [ "main" ])
  • Projects = In multi-project repositories, this property can be a comma separated list of project patterns to deploy to this environment. (Default *)
  • 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)
  • 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)
  • runs-on = specifies which GitHub runner to use when deploying to this environment. (Default is settings.runs-on)

Custom Deployment

By specifying a custom EnvironmentType in the DeployTo structure for an environment, you can now add a script in the .github folder called DeployTo<environmentType>.ps1. This script will be executed instead of the standard deployment mechanism with the following parameters in a HashTable:

Parameter	Description	Example
$parameters.type	Type of delivery (CD or Release)	CD
$parameters.apps	Apps to deploy	/home/runner/.../GHP-Common-main-Apps-2.0.33.0.zip
$parameters.EnvironmentType	Environment type	SaaS
$parameters.EnvironmentName	Environment name	Production
$parameters.Branches	Branches which should deploy to this environment (from settings)	main,dev
$parameters.AuthContext	AuthContext in a compressed Json structure	{"refreshToken":"mytoken"}
$parameters.BranchesFromPolicy	Branches which should deploy to this environment (from GitHub environments)	main
$parameters.Projects	Projects to deploy to this environment
$parameters.ContinuousDeployment	Is this environment setup for continuous deployment	false
$parameters."runs-on"	GitHub runner to be used to run the deployment script	windows-latest

Status Checks in Pull Requests

AL-Go for GitHub now adds status checks to Pull Requests Builds. In your GitHub branch protection rules, you can set up "Pull Request Status Check" to be a required status check to ensure Pull Request Builds succeed before merging.

Secrets in AL-Go for GitHub

In v3.2 of AL-Go for GitHub, all secrets requested by AL-Go for GitHub were available to all steps in a job one compressed JSON structure in env:Secrets.
With this update, only the steps that actually requires secrets will have the secrets available.

v3.2

Issues

Issue 542 Deploy Workflow fails
Issue 558 CI/CD attempts to deploy from feature branch
Issue 559 Changelog includes wrong commits
Publish to AppSource fails if publisher name or app name contains national or special characters
Issue 598 Cleanup during flush if build pipeline doesn't cleanup properly
Issue 608 When creating a release, throw error if no new artifacts have been added
Issue 528 Give better error messages when uploading to storage accounts
Create Online Development environment workflow failed in AppSource template unless AppSourceCopMandatoryAffixes is defined in repository settings file
Create Online Development environment workflow didn't have a project parameter and only worked for single project repositories
Create Online Development environment workflow didn't work if runs-on was set to Linux
Special characters are not supported in RepoName, Project names or other settings - Use UTF8 encoding to handle special characters in GITHUB_OUTPUT and GITHUB_ENV

Issue 555

AL-Go contains several workflows, which create a Pull Request or pushes code directly.
All (except Update AL-Go System Files) earlier used the GITHUB_TOKEN to create the PR or commit.
The problem using GITHUB_TOKEN is that is doesn't trigger a pull request build or a commit build.
This is by design: https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#triggering-a-workflow-from-a-workflow
Now, you can set the checkbox called Use GhTokenWorkflow to allowing you to use the GhTokenWorkflow instead of the GITHUB_TOKEN - making sure that workflows are triggered

New Settings

• keyVaultCodesignCertificateName: With this setting you can delegate the codesigning to an Azure Key Vault. This can be useful if your certificate has to be stored in a Hardware Security Module
• PullRequestTrigger: With this setting you can set which trigger to use for Pull Request Builds. By default AL-Go will use pull_request_target.

New Actions

• DownloadProjectDependencies: Downloads the dependency apps for a given project and build mode.

Settings and Secrets in AL-Go for GitHub

In earlier versions of AL-Go for GitHub, all settings were available as individual environment variables to scripts and overrides, this is no longer the case.
Settings were also available as one compressed JSON structure in env:Settings, this is still the case.
Settings can no longer contain line breaks. It might have been possible to use line breaks earlier, but it would likely have unwanted consequences.
Use $settings = $ENV:Settings | ConvertFrom-Json to get all settings in PowerShell.

In earlier versions of AL-Go for GitHub, all secrets requested by AL-Go for GitHub were available as individual environment variables to scripts and overrides, this is no longer the case.
As described in bug 647, all secrets available to the workflow were also available in env:_Secrets, this is no longer the case.
All requested secrets were also available (base64 encoded) as one compressed JSON structure in env:Secrets, this is still the case.
Use $secrets = $ENV:Secrets | ConvertFrom-Json to get all requested secrets in PowerShell.
You cannot get to any secrets that weren't requested by AL-Go for GitHub.

v3.1

Issues

Issue #446 Wrong NewLine character in Release Notes
Issue #453 DeliverToStorage - override fails reading secrets
Issue #434 Use gh auth token to get authentication token instead of gh auth status
Issue #501 The Create New App action will now use 22.0.0.0 as default application reference and include NoImplicitwith feature.

New behavior

The following workflows:

• Create New App
• Create New Test App
• Create New Performance Test App
• Increment Version Number
• Add Existing App
• Create Online Development Environment

All these actions now uses the selected branch in the Run workflow dialog as the target for the Pull Request or Direct COMMIT.

New Settings

• 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.
• vsixFile: vsixFile should be a direct download URL to the version of the AL Language extension you want to use for building the project or repo. By default, AL-Go will use the AL Language extension that comes with the Business Central Artifacts.

New Workflows

• _BuildALGoProject is a reusable workflow that unites the steps for building an AL-Go projects. It has been reused in the following workflows: CI/CD, Pull Request Build, NextMinor, NextMajor and Current.
  The workflow appears under the Actions tab in GitHub, but it is not actionable in any way.

New Actions

• DetermineArtifactUrl is used to determine which artifacts to use for building a project in CI/CD, PullRequestHandler, Current, NextMinor and NextMajor workflows.

License File

With the changes to the CRONUS license in Business Central version 22, that license can in most cases be used as a developer license for AppSource Apps and it is no longer mandatory to specify a license file in AppSource App repositories.
Obviously, if you build and test your app for Business Central versions prior to 21, it will fail if you don't specify a licenseFileUrl secret.