Advanced Settings

Advanced settings provide fine-grained control over build artifacts, versioning strategies, dependency management, code analysis, and containerless compilation. These settings are for users with knowledge of GitHub workflows, Business Central artifacts, and AL development.

These settings might require knowledge about GitHub Workflows/Actions, YAML, Docker, and PowerShell. Please only change these settings after careful consideration, as they might change in future versions.

Artifact Configuration

artifact

string

Determines the artifacts used for building and testing the app.Can be either:

Absolute pointer to Business Central artifacts: https://... (rarely used)
Search specification: <storageaccount>/<type>/<version>/<country>/<select>

If not specified, uses the latest sandbox artifacts from the country specified in the country setting.

If version is *, the application dependency from your app.json determines which artifacts to use. If select is first, you get the first matching artifacts. If latest, you get the latest artifacts with the same major.minor as your application dependency.

Example:

{
  "artifact": "bcartifacts/sandbox/21.0/us/latest"
}

additionalCountries

array

default:[]

Additional countries to compile, publish, and test your app against during workflows.Can be different in NextMajor and NextMinor workflows by specifying in workflow settings file.Example:

{
  "additionalCountries": [
    "dk",
    "de",
    "fr"
  ]
}

companyName

string

Company name selected in the database for running the CI/CD workflow.Default is to use the default company in the selected Business Central localization.Example:

{
  "companyName": "CRONUS International Ltd."
}

Versioning Strategy

versioningStrategy

number

default:0

Determines how versioning is performed. Version number format: Major.Minor.Build.RevisionMajor and Minor are read from app.json. Build and Revision are calculated:Strategy 0:

Build = GitHub run_number + runNumberOffset
Revision = GitHub run_attempt - 1

Strategy 2:

Build = current date as yyyyMMdd (UTC)
Revision = current time as hhmmss (UTC)

Strategy 3:

Build = from app.json
Revision = GitHub run_number

Strategy 15:

Build = max value
Revision = GitHub run_number
Use with caution - recommended only for non-official artifacts (PR builds, test workflows)

+16 modifier: Adding 16 to above strategies uses repoVersion instead of Major.Minor from app.json (also Build if strategy is 3+16)Example:

{
  "versioningStrategy": 2
}

runNumberOffset

number

default:0

When using versioningStrategy 0, offset applied to GitHub RUN_NUMBER.Use negative number to reset after increasing Major/Minor, or positive for starting offset.Example:

{
  "runNumberOffset": 1000
}

Dependency Management

updateDependencies

boolean

default:false

Builds your app against the first compatible Business Central build and sets dependency version numbers in app.json during build.All version numbers in the built app are set to the version used during compilation.

When enabled, application versions from BC Artifact are stamped into app.json. Not all app versions in BC Artifacts are shipped in BC SaaS, which can cause AppSource validation failures. Not recommended for AppSource deployment.

Example:

{
  "updateDependencies": false
}

generateDependencyArtifact

boolean

default:false

When true, CI/CD pipeline generates an artifact with external dependencies used for building the apps.Example:

{
  "generateDependencyArtifact": true
}

installApps

array

default:[]

Array of 3rd party dependency apps not available through appDependencyProbingPaths.Can be secure URLs or paths to folders/files relative to the project. Apps are downloaded and installed before compiling and installing your apps.

Specify ${{SECRETNAME}} in a URL to replace with the value of secret SECRETNAME.

Example:

{
  "installApps": [
    "https://example.com/dependencies/app.zip",
    "dependencies/local-app.app"
  ]
}

installTestApps

array

default:[]

Array of 3rd party test dependency apps not available through appDependencyProbingPaths.Apps are downloaded and installed before compiling and installing test apps. Parentheses around the setting indicate the test in this app will NOT be run, only installed.

Specify ${{SECRETNAME}} in a URL to replace with the value of secret SECRETNAME.

Example:

{
  "installTestApps": [
    "https://example.com/testapps/test-helper.app"
  ]
}

installOnlyReferencedApps

boolean

default:true

By default, only apps referenced in the dependency chain are installed from installApps, installTestApps, and appDependencyProbingPath.Set to false to install all apps found.Example:

{
  "installOnlyReferencedApps": false
}

runTestsInAllInstalledTestApps

boolean

default:false

PREVIEW: By default, AL-Go publishes test apps built in previous jobs but doesn’t execute the tests.Set to true to run tests in all test apps produced by previous jobs.Example:

{
  "runTestsInAllInstalledTestApps": true
}

Configuration Packages

configPackages

array

default:[]

Array of configuration packages applied to the build container before running tests.Can be relative paths within the project or: STANDARD, EXTENDED, or EVALUATION for rapidstart packages that come with Business Central.Example:

{
  "configPackages": [
    "STANDARD",
    "config/custom-data.rapidstart"
  ]
}

configPackages.<country>

array

default:[]

Country-specific configuration packages applied to the build container for the specified country.Example:

{
  "configPackages.dk": [
    "EXTENDED"
  ]
}

Code Analysis

enableCodeCop

boolean

default:false

Enable the CodeCop analyzer when building.Example:

{
  "enableCodeCop": true
}

enableUICop

boolean

default:false

Enable the UICop analyzer when building.Example:

{
  "enableUICop": true
}

customCodeCops

array

default:[]

Array of paths or URLs to custom Code Cop DLLs to enable when building.Example:

{
  "customCodeCops": [
    "https://example.com/codecops/custom-cop.dll",
    "codecops/local-cop.dll"
  ]
}

enableCodeAnalyzersOnTestApps

boolean

default:false

Enable code analyzers when building test apps.Example:

{
  "enableCodeAnalyzersOnTestApps": true
}

trackALAlertsInGitHub

boolean

default:false

Upload and track AL code analysis results in the GitHub security tab.If Advanced Security is enabled, new AL code alerts are posted in PRs that introduce them.

Must be enabled at repo level but can be optionally disabled per project. Currently only enabled for warnings. Error support coming in future release.

Example:

{
  "trackALAlertsInGitHub": true
}

failOn

string

default:"error"

Specifies what the pipeline will fail on.Allowed values:

none - Don’t fail on warnings or errors
warning - Fail on any warning
newWarning - Fail on new warnings in PRs, behave like error for normal builds
error - Fail on errors only

Example:

{
  "failOn": "newWarning"
}

rulesetFile

string

Filename of the custom ruleset file.Example:

{
  "rulesetFile": "custom.ruleset.json"
}

enableExternalRulesets

boolean

default:false

Allow external rule references in the ruleset.Example:

{
  "enableExternalRulesets": true
}

reportSuppressedDiagnostics

boolean

default:false

Report diagnostics suppressed in code using #pragma warning disable <id>.Useful to ensure no warnings are suppressed in your code.Example:

{
  "reportSuppressedDiagnostics": true
}

AL Language Extension

vsixFile

string

default:"default"

Determines which version of the AL Language Extension to use for building apps.Values:

default - Use AL Language Extension that ships with the BC version
latest - Always download the latest from marketplace
preview - Always download the preview from marketplace
Direct download URL pointing to the AL Language VSIX file

Example:

{
  "vsixFile": "latest"
}

Code Signing

codeSignCertificateUrlSecretName

string

default:"CodeSignCertificateUrl"

Name (NOT the secret) of the code signing certificate URL secret.

There is a new way of signing apps described in the Codesigning documentation.

Example:

{
  "codeSignCertificateUrlSecretName": "MyCodeSignCertUrl"
}

codeSignCertificatePasswordSecretName

string

default:"CodeSignCertificatePassword"

Name (NOT the secret) of the code signing certificate password secret.Example:

{
  "codeSignCertificatePasswordSecretName": "MyCodeSignCertPassword"
}

keyVaultCodesignCertificateName

string

Name of a certificate stored in your KeyVault for code signing.Requires Azure KeyVault enabled in your AL-Go project.Example:

{
  "keyVaultCodesignCertificateName": "MySigningCert"
}

trustedSigning

object

Structure for enabling Azure Trusted Signing.Properties:

Account - Name of your trusted signing account
Endpoint - Endpoint URL (e.g., https://weu.codesigning.azure.net)
CertificateProfile - Certificate profile in your account

Your Azure_Credentials secret (Microsoft Entra ID App or Managed identity) needs the Trusted Signing Certificate Profile Signer role in the Trusted Signing Account.

Example:

{
  "trustedSigning": {
    "Account": "MyTrustedSigningAccount",
    "Endpoint": "https://weu.codesigning.azure.net",
    "CertificateProfile": "MyProfile"
  }
}

Application Insights

applicationInsightsConnectionStringSecretName

string

default:"applicationInsightsConnectionString"

Name (NOT the secret) of a secret containing the Application Insights connection string for the apps.Example:

{
  "applicationInsightsConnectionStringSecretName": "AppInsightsConnStr"
}

Storage and Delivery

storageContextSecretName

string

default:"StorageContext"

Name (NOT the secret) of a secret containing storage account context.Should contain JSON with StorageAccountName, ContainerName, BlobName, and StorageAccountKey or SAS Token. If exists, AL-Go uploads builds to this storage account for every successful build.Use New-ALGoStorageContext from BcContainerHelper to create the JSON structure.Example:

{
  "storageContextSecretName": "MyStorageContext"
}

NuGet Feeds

trustMicrosoftNuGetFeeds

boolean

default:true

Unless set to false, AL-Go trusts NuGet feeds provided by Microsoft.Microsoft feeds contain all Microsoft apps, symbols, and symbols for all AppSource apps.Example:

{
  "trustMicrosoftNuGetFeeds": true
}

trustedNuGetFeeds

array

default:[]

Array of NuGet feed specifications for dependency resolution.Each feed specification includes:

url - Feed URL (required)
authTokenSecret - Secret name containing auth token for private feeds
patterns - Package ID patterns to trust (default: *)
fingerprints - Array of certificate fingerprints for signed packages

Example:

{
  "trustedNuGetFeeds": [
    {
      "url": "https://pkgs.dev.azure.com/myorg/apps/_packaging/myrepo/nuget/v3/index.json",
      "authTokenSecret": "AzureDevOpsToken",
      "patterns": ["MyOrg.*"],
      "fingerprints": []
    }
  ]
}

nuGetFeedSelectMode

string

default:"LatestMatching"

Select mode when finding BC app packages from NuGet feeds based on app.json dependency version.Options:

Earliest - Earliest version of the package
EarliestMatching - Earliest version also compatible with BC version
Exact - Exact version of the package
Latest - Latest version of the package
LatestMatching - Latest version also compatible with BC version

Example:

{
  "nuGetFeedSelectMode": "LatestMatching"
}

Container Settings

assignPremiumPlan

boolean

default:false

Create build container with AssignPremiumPlan set, giving auto-created user Premium Plan.Needed if your tests require premium plan enabled.Example:

{
  "assignPremiumPlan": true
}

enableTaskScheduler

boolean

default:false

Create build container with Task Scheduler running.Example:

{
  "enableTaskScheduler": true
}

memoryLimit

string

default:"8G"

Specifies the memory limit for the build container.By default, left to BcContainerHelper (currently 8G).Example:

{
  "memoryLimit": "16G"
}

cacheImageName

string

default:"my"

When using self-hosted runners, specifies the prefix for the Docker image created for increased performance.Example:

{
  "cacheImageName": "bcartifacts"
}

cacheKeepDays

number

default:3

When using self-hosted runners, specifies days Docker images are cached before cleanup.

Setting to 0 flushes cache before every build and causes other running builds on the same host to fail.

Example:

{
  "cacheKeepDays": 7
}

Containerless Compilation

useCompilerFolder

boolean

default:false

Use containerless compiling.Unless doNotPublishApps is also true, no performance advantage since AL-Go still needs a container for publishing and testing.

When using this setting, sign apps using the new signing mechanism described in the Codesigning documentation.

Example:

{
  "useCompilerFolder": true
}

Upgrade Settings

skipUpgrade

boolean

default:false

Signal to the pipeline to NOT run upgrade and ignore previous releases of the app.Example:

{
  "skipUpgrade": true
}

AppSource-Specific Advanced Settings

appSourceContextSecretName

string

default:"AppSourceContext"

Name (NOT the secret) of a secret containing AppSource context.Should contain JSON with ClientID, TenantID, and ClientSecret or RefreshToken. If exists, AL-Go can upload builds to AppSource validation.Example:

{
  "appSourceContextSecretName": "AppSourceContext"
}

keyVaultCertificateUrlSecretName

string

For AppSource App KeyVault access - name of secret containing certificate URL.

keyVaultCertificatePasswordSecretName

string

For AppSource App KeyVault access - name of secret containing certificate password.

keyVaultClientIdSecretName

string

For AppSource App KeyVault access - name of secret containing client ID.

Expert-Level Settings

repoName

string

The name of the repository (defaults to GitHub repository name).Example:

{
  "repoName": "my-custom-repo-name"
}

applicationDependency

string

default:"18.0.0.0"

Lowest Business Central version supported by your app.Build fails early if artifacts are lower than this. Calculated by reading app.json but cannot be lower than this setting.Example:

{
  "applicationDependency": "20.0.0.0"
}

BcContainerHelperVersion

string

default:"latest"

Specific version of BcContainerHelper to use.Values:

latest - Latest released version
preview - Latest preview version
dev - Dev branch of containerhelper
Specific version (e.g., “3.0.8”)

Example:

{
  "BcContainerHelperVersion": "preview"
}

Conditional Settings - Apply settings based on conditions
Secrets Overview - Configure secrets for AL-Go
Azure KeyVault - Use Azure KeyVault for secrets

Configuration

Secrets Management

Artifact Configuration

Versioning Strategy

Dependency Management

Configuration Packages

Code Analysis

AL Language Extension

Code Signing

Application Insights

Storage and Delivery

NuGet Feeds

Container Settings

Containerless Compilation

Upgrade Settings

AppSource-Specific Advanced Settings

Expert-Level Settings

Build docs developers (and LLMs) love

Configuration

Secrets Management

​Artifact Configuration

​Versioning Strategy

​Dependency Management

​Configuration Packages

​Code Analysis

​AL Language Extension

​Code Signing

​Application Insights

​Storage and Delivery

​NuGet Feeds

​Container Settings

​Containerless Compilation

​Upgrade Settings

​AppSource-Specific Advanced Settings

​Expert-Level Settings

​Related Pages

Build docs developers (and LLMs) love

Artifact Configuration

Versioning Strategy

Dependency Management

Configuration Packages

Code Analysis

AL Language Extension

Code Signing

Application Insights

Storage and Delivery

NuGet Feeds

Container Settings

Containerless Compilation

Upgrade Settings

AppSource-Specific Advanced Settings

Expert-Level Settings

Related Pages