Custom AL-Go files

AL-Go for GitHub now supports updating files from your custom templates via the new customALGoFiles setting. Read more at customALGoFiles.

Set default values for workflow inputs

A new setting workflowDefaultInputs allows you to configure default values for workflow_dispatch inputs. This makes it easier to run workflows manually with consistent settings across your team.

When you add this setting to your AL-Go settings file and run the "Update AL-Go System Files" workflow, the default values will be automatically applied to the workflow YAML files in your repository.
The default values must match the input types (boolean, number, string, or choice) defined in the workflow YAML files.

Example configuration:

{
  "workflowDefaultInputs": [
    { "name": "directCommit", "value": true },
    { "name": "useGhTokenWorkflow", "value": true }
  ]
}

This setting can be used on its own in repository settings to apply defaults to all workflows with matching input names. Alternatively, you can use it within conditional settings to apply defaults only to specific workflows, branches, or other conditions.

Example using conditional settings to target specific workflows:

{
  "conditionalSettings": [
    {
      "workflows": ["Create Release"],
      "settings": {
        "workflowDefaultInputs": [
          { "name": "directCommit", "value": true },
          { "name": "releaseType", "value": "Prerelease" }
        ]
      }
    }
  ]
}

Important: When multiple conditional settings blocks match and both define workflowDefaultInputs, the arrays are merged following AL-Go's standard behavior for complex setting types (all entries are kept). If the same input name appears in multiple entries, the last matching entry takes precedence.

Read more at workflowDefaultInputs.

Issues

• Issue 2039 Error when deploy to environment: NewTemporaryFolder is not recognized
• Issue 1961 KeyVault access in PR pipeline
• Discussion 1911 Add support for reportSuppressedDiagnostics
• Discussion 1968 Parameter for settings passed to CreateDevEnv
• Issue 1945 Deploy Reference Documentation fails for CI/CD
• Use Runner_Temp instead of GetTempFolder whenever possible
• Issue 2016 Running Update AL-Go system files with branches wildcard * tries to update origin
• Issue 1960 Deploy Reference Documentation fails
• Discussion 1952 Set default values on workflow_dispatch input

Deprecations

• unusedALGoSystemFiles will be removed after October 1st 2026. Please use customALGoFiles.filesToExclude instead.

Mechanism to overwrite complex settings type

By default, AL-Go merges settings from various places (see settings levels). Basic setting types such as string and integer are overwritten, but settings with complex types such as array and object are merged.

However, sometimes it is useful to avoid merging complex types. This can be achieved by specifying overwriteSettings property on a settings object. The purpose of the property is to list settings, for which the value will be overwritten, instead of merged. Read more at overwriteSettings property

AL Code Analysis tracked in GitHub

AL-Go already supports AL code analysis, but up until now this was not tracked in GitHub. It is now possible to track code analysis issues automatically in the GitHub security tab, as well as having any new issues posted as a comment in Pull Requests.

Enable this feature by using the new setting trackALAlertsInGithub. This setting must be enabled at the repo level, but can optionally be disabled per project.

Please note that some automated features are premium and require the use of GitHub Code Security

Issues

• Discussion 1885 Conditional settings for CI/CD are not applied
• Discussion 1899 Remove optional properties from "required" list in settings.schema.json
• Issue 1905 AL-Go system files update fails (Get Workflow Multi-Run Branches action fails when there are tags with same value but different casing)
• Issue 1926 Deployment fails when using build modes
• Issue 1898 GetDependencies in localDevEnv does not fallback to github token
• Issue 1947 Project settings are ignored when loading bccontainerhelper
• Issue 1937 trackALAlertsInGitHub is failing in preview
• DeployTo settings from environment-specific AL-Go settings are not applied when deploying
• ReadSettings action outputs too much information that is mainly used for debugging

Configurable merge method for pull request auto-merge

A new setting pullRequestMergeMethod has been added to the commitOptions structure, allowing you to configure which merge method to use when pullRequestAutoMerge is enabled. Valid values are "merge" or "squash". The default value is "squash" to maintain backward compatibility.

Example

{
  "commitOptions": {
    "pullRequestAutoMerge": true,
    "pullRequestMergeMethod": "merge"
  }
}

AL-Go Telemetry

AL-Go now offers a dataexplorer dashboard to get started with AL-Go telemetry. Additionally, we've updated the documentation to include a couple of kusto queries if you would rather build your own reports.

Support for AL-Go settings as GitHub environment variable: ALGoEnvSettings

AL-Go settings can now be defined in GitHub environment variables. To use this feature, create a new variable under your GitHub environment called ALGoEnvironmentSettings. Please note that this variable should not include your environment name.

Settings loaded this way, will only be available during the Deploy step of the CI/CD or Publish to Environment actions, but not the Build step, making it most suitable for the DeployTo setting. Settings defined in this variable will take priority over any setting defined in AL-Go repo, org or settings files.

The contents of the variable should be a JSON block, similar to any other settings file or variable. When defining the DeployTo\<EnvName> setting in this variable, it should still include the environment name. Eg:

{
  DeployToProduction {
    "Branches": [
        "*"
    ],
    "includeTestAppsInSandboxEnvironment": false,
    "excludeAppIds": [ 1234 ]
  }
}

Please note, that due to certain security limitations, the properties runs-on, shell and ContinousDeployment of the DeployTo setting will NOT be respected if defined in a GitHub environment variable. To use these properties, please keep them defined elsewhere, such as your AL-Go settings file or Org/Repo settings variables.

Issues

• Issue 1770 Wrong type of projects setting in settings schema
• Issue 1787 Publish to Environment from PR fails in private repos
• Issue 1722 Check if apps are already installed on a higher version before deploying
• Issue 1774 Increment Version Number with +0.1 can increment some version numbers twice
• Issue 1837 Deployment from PR builds fail if PR branch name includes forward slashes (e.g., feature/branch-name).
• Issue 1852 Page Scripting Tests are not added to build summary
• Issue 1829 Added custom jobs cannot be removed
• Idea 1856 Include workflow name as input for action ReadSetting

Additional debug logging functionality

We have improved how logging is handled in AL-Go, and now make better use of GitHub built-in extended debug logging functionality. Extended debug logging can be enabled when re-running actions by clicking the 'Enable debug logging' checkbox in the pop-up window. This can be done both for jobs that failed and jobs that succeeded, but did not produce the correct result.

Add custom jobs to AL-Go workflows

It is now possible to add custom jobs to AL-Go workflows. The Custom Job needs to be named CustomJob<something> and should be placed after all other jobs in the .yaml file. The order of which jobs are executed is determined by the Needs statements. Your custom job will be executed after all jobs specified in the Needs clause in your job and if you need the job to be executed before other jobs, you should add the job name in the Needs clause of that job. See https://aka.ms/algosettings#customjobs for details.

Note that custom jobs might break by future changes to AL-Go for GitHub workflows. If you have customizations to AL-Go for GitHub workflows, you should always doublecheck the pull request generated by Update AL-Go System Files.

Support for Custom AL-Go template repositories

Create an AL-Go for GitHub repository based on https://aka.ms/algopte or https://aka.ms/algoappsource, add custom workflows, custom jobs and/or settings to this repository and then use that repository as the template repository for other repositories. Using custom template repositories allows you to create and use highly customized template repositories and control the uptake of this in all repositories. See https://aka.ms/algosettings#customtemplate for details.

Removed functionality

As stated in AL-Go Deprecations, setting cleanModePreprocessorSymbols is no longer supported and will be ignored by AL-Go for GitHub.

Security

• Add top-level permissions for Increment Version Number workflow

Issues

• Issue 1697 Error in CheckForUpdates: "Internet Explorer engine is not available" when using self-hosted runners
• Issue 1685 HttpError: Resource not accessible by integration
• Issue 1757 Error when signing apps with key vault signing

Workflow input validation

Some workflow inputs are now validated early in order to avoid workflows to make modifications like creating a release, when we already should know that an error will occur later.

Test settings against a JSON schema

AL-Go for GitHub settings now has a schema. The following line is added at the beginning to any AL-Go settings files to utilize the schema:

"$schema": "https://raw.githubusercontent.com/microsoft/AL-Go-Actions/<version>/Actions/settings.schema.json"

Failing pull requests if new warnings are added

By setting failOn to 'newWarning', pull requests will fail if new warnings are introduced. This feature compares the warnings in the pull request build against those in the latest successful CI/CD build and fails if new warnings are detected.

AL-Go Telemetry

Now AL-Go telemetry also logs ActionDuration which makes it possible to track the duration of the different steps in the AL-Go workflows (e.g. RunPipeline or Sign)

Issues

• Issue 1678 Test summary is showing too many status icons
• Issue 1640 AL1040 error due to app folder within the artifacts cache being incorrectly recognized as an app folder
• Issue 1630 Error when downloading a release, when the destination folder already exists.
• Issue 1540 and 1649 Apps with dependencies to Microsft__EXCLUDE_ apps fails deployment
• Issue 1547 Dependencies will be installed even if DependencyInstallMode is ignore, but dependencies will never be installed on production environments
• Issue 1654 GithubPackageContext does not work together with private trustedNuGetFeeds
• Issue 1627 AL-Go should throw an error or a warning if you create a release, which is older than the latest release
• Issue 1657 When no files modified on Git, deployment fails
• Issue 1530 Dependency Field Service Integration does not get published in container while Installing apps
• Issue 1644 Support for AppAuth when using a private Template repository from another organization
• Issue 1669 GitHub App authentication to download dependencies from private repositories
• Issue 1478 Rate Limit Exceeded when running Update AL-Go System files

Issues

• Issue 1519 Submitting to AppSource WARNING: AuthContext.Scopes is .. should be
• Issue 1521 Dependencies not installed for multi project incremental PR build
• Issue 1522 Strange warnings in Deploy job post update to AL-Go 6.4
• BcContainerHelper settings were only read from .github/AL-Go-Settings.json, not allowing global settings in ALGoOrgSettings for TrustedNuGetFeeds, MemoryLimit and other things that should be possible to define globally
• Issue 1526 When updating AL-Go system files, the update process (creating a PR or directly pushing to the branch) fails when there is a file or directory in the repo with the same name as the branch that is to be updated
• Legacy code signing stopped working

Page Scripting visualizer

Page scripting tests have been available for AL-Go for GitHub for a while but required manual inspection of the Page scripting artifact to see the results. It is now possible to get a quick overview in the job summary section of a CICD build, similar to how regular and bcpt test results are displayed.

No new settings are required. Test results will automatically be displayed if tests are enabled via the existing setting pageScriptingTests.

Support for deploying to sandbox environments from a pull request

AL-Go for GitHub now supports deploying from a PR. When using the 'Publish To Environment' workflow, it is now possible to input 'PR_X' as the App version, where 'X' is the PR Id. This will deploy the artifacts from the latest PR build to the chosen environment, if that build is completed and successful.

All apps, which were not built by the PR build will be deployed from the last known good build. You can find a notification on the PR build explaining which build is used as the last known good build.

Deprecations

• alwaysBuildAllProjects will be removed after October 1st 2025. Please set the onPull_Request property of the incrementalBuilds setting to false to force full builds in Pull Requests.
• <workflow>Schedule will be removed after October 1st 2025. The old setting, where the setting key was a combination of the workflow name and Schedule (dynamic setting key name) is deprecated. Instead you need to use a setting called workflowSchedule and either use Conditional Settings or place the setting in a workflow specific settings file.

Issues

• Issue 1433 Publish to Environment - DependencyInstallMode not found
• Issue 1440 Create Release fails due to recent changes to the AL-Go
• Issue 1330 CompilerFolder doesn't transfer installed Apps to NuGet resolution
• Issue 1268 Do not throw an un-understandable error during nuGet download
• Performance test sample code in 25.4 contains objects with ID 149201 and 149202, which are not renumbered
• Issue 798 Publish To Environment breaks CI/CD pipelines
• Issue 1182 Runs-on setting type is ambiguous - string or array
• Issue 1502 NuGet dependency version is always LatestMatching

New Workflow specific settings

• workflowSchedule - can be structure with a property named cron, which must be a valid crontab, defining the CRON schedule for when the specified workflow should run. Default is no scheduled runs, only manual triggers. Build your crontab string here: https://crontab.guru. You need to run the Update AL-Go System Files workflow for the schedule to take effect.
  Note: If you configure a WorkflowSchedule for the CI/CD workflow, AL-Go will stop triggering CICDs on push unless you have also added CICDPushBranches to your settings.
  Note also: If you define a schedule for Update AL-Go System Files, it uses direct Commit instead of creating a PR.
• workflowConcurrency - is used to control concurrency of workflows. Like with the workflowSchedule setting, this setting should be applied in workflow specific settings files or conditional settings. By default, all workflows allows for concurrency, except for the Create Release workflow. If you are using incremental builds in CI/CD it is also recommented to set WorkflowConcurrency to:
  [ "group: ${{ github.workflow }}-${{ github.ref }}", "cancel-in-progress: true" ]
  in order to cancel prior incremental builds on the same branch.
  Read more about workflow concurrency here.

New Repository Settings

• nuGetFeedSelectMode determines the select mode when finding Business Central app packages from NuGet feeds, based on the dependency version specified in app.json. Options are: Earliest for earliest version of the package, EarliestMatching for earliest version of the package also compatible with the Business Central version used, Exact for the exact version of the package, Latest for the latest version of the package, LatestMatching for the latest version of the package also compatible with the Business Central version used.
• deployTo<environment> now has two additional properties:
  • includeTestAppsInSandboxEnvironment, which deploys test apps and their dependencies to the specified sandbox environment if set to true. Deployment will fail if used on a Prod environment or if the test app has a dependency on Tests-TestLibraries. Default value is false.
  • excludeAppIds, which is an array of app ids which will be excluded from deployment. Default value is []
• incrementalBuilds - is a structure defining how you want AL-Go to handle incremental builds. When using incremental builds for a build, AL-Go will look for the latest successful build, newer than the defined retentionDays and only rebuild projects or apps (based on mode) which needs to be rebuilt. Properties in the structure includes:
  • onPush - set this property to true in order to enable incremental builds in CI/CD triggered by a merge/push event. Default is false.
  • onPull_Request - set this property to false in order to disable incremental builds in Pull Request workflows. Default is true.
  • onSchedule - set this property to true in order to enable incremental builds in CI/CD when running on a schedule. Default is false.
  • retentionDays - number of days a successful build is good (and can be used for incremental builds). Default is 30.
  • mode - defines the mode for incremental builds. Currently, two values are supported. Use modifiedProjects when you want to rebuild all apps in modified projects and depending projects or modifiedApps if you only want to rebuild modified apps and depending apps.

Run "Update AL-Go System Files" on multiple branches

Update AL-Go System Files has a new input to specify a list of branches to be updated in a single workflow run.
When running the workflow on a schedule, you can now also specify includeBranches in workflowSchedule setting, which allows you to update the specified branches. Read more at https://aka.ms/algosettings#workflowSchedule.

Support for incremental builds

AL-Go for GitHub now supports incremental builds, which means that unchanged projects or apps will be reused from the previous good build. Read this to learn more.

Support for GitHub App authentication

AL-Go for GitHub now supports using a GitHub App specification as the GhTokenWorkflow secret for a more secure way of allowing repositories to run Update AL-Go System Files and other workflows which are creating commits and pull requests. See this description to learn how to use GitHub App authentication.

Support for embedded secrets in installApps and installTestApps settings

If your installApps or installTestApps are secure URL, containing a secret token, you can now use a GitHub secret specification as part of or as the full URL of apps to install. An example could be:

"installApps": [ "https://www.dropbox.com/${{SECRETNAME}}&dl=1" ]

Which would hide the secret part of your URL instead of exposing it in clear text.

Deprecations

• cleanModePreprocessorSymbols will be removed after April 1st 2025. Use Conditional Settings instead, specifying buildModes and the preprocessorSymbols setting. Read this for more information.

Issues

• It is now possible to skip the modification of dependency version numbers when running the Increment Version number workflow or the Create Release workflow

New Repository Settings

• shortLivedArtifactsRetentionDays determines the number of days to keep short lived build artifacts (f.ex build artifacts from pull request builds, next minor or next major builds). 1 is default. 0 means use GitHub default.
• preProcessorSymbols is a list of preprocessor symbols to use when building the apps. This setting can be specified in workflow specific settings files or in conditional settings.

New Versioning Strategy

Setting versioning strategy to 3 will allow 3 segments of the version number to be defined in app.json and repoVersion. Only the 4th segment (Revision) will be defined by the GitHub run_number for the CI/CD workflow. Increment version number and Create Release now also supports the ability to set a third segment to the RepoVersion and appversion in app.json.

Change in published artifacts

When using useProjectDependencies in a multi-project repository, AL-Go for GitHub used to generate short lived build artifacts called thisBuild-<projectnaame>-<type>-.... This is no longer the case. Instead, normal build artifacts will be published and used by depending projects. The retention period for the short lived artifacts generated are controlled by a settings called shortLivedArtifactsRetentionDays.

Preprocessor symbols

It is now possible to define preprocessor symbols, which will be used when building your apps using the preProcessorSymbols setting. This setting can be specified in workflow specific settings file or it can be used in conditional settings.

Issues

• Issue 1296 Make property "appFolders" optional
• Issue 1344 Experimental feature "git submodules" seems to be a breaking change
• Issue 1305 Extra telemetry Property RepositoryOwner and RepositoryName¨
• Add RunnerEnvironment to Telemetry
• Output a notice, not a warning, when there are no available updates for AL-Go for GitHub

New Repository Settings

• useGitSubmodules can be either true or recursive if you want to enable Git Submodules in your repository. If your Git submodules resides in a private repository, you need to create a secret called gitSubmodulesToken containing a PAT with access to the submodule repositories. Like with all other secrets, you can also create a setting called gitSubmodulesTokenSecretName and specify the name of another secret, with these permissions (f.ex. ghTokenWorkflow).
• commitOptions - is a structure defining how you want AL-Go to handle automated commits or pull requests coming from AL-Go (e.g. for Update AL-Go System Files). The structure contains the following properties
  • messageSuffix : A string you want to append to the end of commits/pull requests created by AL-Go. This can be useful if you are using the Azure Boards integration (or similar integration) to link commits to workitems.
  • pullRequestAutoMerge : A boolean defining whether you want AL-Go pull requests to be set to auto-complete. This will auto-complete the pull requests once all checks are green and all required reviewers have approved.
  • pullRequestLabels : A list of labels to add to the pull request. The labels need to be created in the repository before they can be applied.

Support for Git submodules

In v6.1 we added experimental support for Git submodules - this did however only work if the submodules was in a public repository. In this version, you can use the useGitSubmodules setting to control whether you want to use Git Submodules and the gitSubmodulesToken secret to allow permission to read these repositories.

Issues

• Issue 1241 Increment Version Number might produce wrong app.json
• When auto discovering appFolders, testFolders and bcptTestFolders - if a BCPT Test app has a dependency to a test framework app, it is added to testFolders as well as bcptTestFolders and will cause a failure.

New Project Settings

• pageScriptingTests should be an array of page scripting test file specifications, relative to the AL-Go project. Examples of file specifications: recordings/my*.yml (for all yaml files in the recordings subfolder matching my*.yml), recordings (for all *.yml files in the recordings subfolder) or recordings/test.yml (for a single yml file)
• doNotRunPageScriptingTests can force the pipeline to NOT run the page scripting tests specified in pageScriptingTests. Note this setting can be set in a workflow specific settings file to only apply to that workflow
• restoreDatabases should be an array of events, indicating when you want to start with clean databases in the container. Possible events are: BeforeBcpTests, BeforePageScriptingTests, BeforeEachTestApp, BeforeEachBcptTestApp, BeforeEachPageScriptingTest

New Repository Settings

• trustedSigning is a structure defining Account, EndPoint and CertificateProfile if you want to use trusted signing. Note that your Azure_Credentials secret (Microsoft Entra ID App or Managed identity) still needs to provide access to your azure subscription and be assigned the Trusted Signing Certificate Profile Signer role in the Trusted Signing Account.
• deployTo<environment> now has an additional property called DependencyInstallMode, which determines how dependencies are deployed if GenerateDependencyArtifact is true. Default value is install to install dependencies if not already installed. Other values are ignore for ignoring dependencies, upgrade for upgrading dependencies if possible and forceUpgrade for force upgrading dependencies.

Support for Azure Trusted Signing

Read https://learn.microsoft.com/en-us/azure/trusted-signing/ for more information about Trusted Signing and how to set it up. After setting up your trusted signing account and certificate profile, you need to create a setting called trustedSigning for AL-Go to sign your apps using Azure Trusted Signing.

Support for Page Scripting Tests

Page Scripting tests are now supported as part of CI/CD. By specifying pageScriptingTests in your project settings file, AL-Go for GitHub will automatically run these page scripting tests as part of your CI/CD workflow, generating the following build artifacts:

• PageScriptingTestResults is a JUnit test results file with all results combined.
• PageScriptingTestResultDetails are the detailed test results (including videos) when any of the page scripting tests have failures. If the page scripting tests succeed - the details are not published.

Experimental support for Git submodule

Git submodule is now supported as part of CI/CD on your project.