settings.md

Settings

The behavior of AL-Go for GitHub is very much controlled by settings and secrets.

To learn more about the secrets used by AL-Go for GitHub, please navigate to Secrets.

Where are the settings located

Settings can be defined in GitHub variables or in various settings file. An AL-Go repository can consist of a single project (with multiple apps) or multiple projects (each with multiple apps). Settings can be applied on the project level or on the repository level. Multiple projects in a single repository are comparable to multiple repositories; they are built, deployed, and tested separately. All apps in each project (single or multiple) are built together in the same pipeline, published and tested together. If a repository is multiple projects, each project is stored in a separate folder in the root of the repository.

When running a workflow or a local script, the settings are applied by reading settings from GitHub variables and one or more settings files. Last applied settings file wins. The following lists the order of locations to search for settings:

1. ALGoOrgSettings is a GitHub variable, which can be defined on an organizational level and will apply to all AL-Go repositories in this organization.

2. .github/AL-Go-settings.json is the repository settings file. This settings file contains settings that are relevant for all projects in the repository. Special note: The repository settings file can also contains BcContainerHelper settings, which will be applied when loading BcContainerHelper in a workflow - the GitHub variables are not considered for BcContainerHelper settings. (see expert section).

3. ALGoRepoSettings is a GitHub variable, which can be defined on an repository level and can contain settings that are relevant for all projects in the repository.

4. .AL-Go/settings.json is the project settings file. If the repository is a single project, the .AL-Go folder is in the root folder of the repository. If the repository contains multiple projects, there will be a .AL-Go folder in each project folder (like project/.AL-Go/settings.json)

5. .github/<workflow>.settings.json is the workflow-specific settings file for all projects. This option is used for the Current, NextMinor and NextMajor workflows to determine artifacts and build numbers when running these workflows.

6. .AL-Go/<workflow>.settings.json is the workflow-specific settings file for a specific project.

7. .AL-Go/<username>.settings.json is the user-specific settings file. This option is rarely used, but if you have special settings, which should only be used for one specific user (potentially in the local scripts), these settings can be added to a settings file with the name of the user followed by .settings.json.

Basic Project settings

Name	Description	Default value
country	Specifies which country this app is built against.	us
repoVersion	RepoVersion is the project version number. The Repo Version number consists of <major>.<minor> only and is used for naming build artifacts in the CI/CD workflow. Build artifacts are named <project>-Apps-<repoVersion>.<build>.<revision> and can contain multiple apps. The Repo Version number is used as major.minor for individual apps if versioningStrategy is +16.	1.0
projectName	Friendly name for an AL-Go project to be used in the UI for various workflows (CICD, Pull Request Build, etc.). If not set, the name for the project will be the relative path from the root of the repository.	''
appFolders	appFolders should be an array of folders (relative to project root), which contains apps for this project. Apps in these folders are sorted based on dependencies and built and published in that order. If appFolders are not specified, AL-Go for GitHub will try to locate appFolders in the root of the project.	[ ]
testFolders	testFolders should be an array of folders (relative to project root), which contains test apps for this project. Apps in these folders are sorted based on dependencies and built, published and tests are run in that order. If testFolders are not specified, AL-Go for GitHub will try to locate testFolders in the root of the project.	[ ]
bcptTestFolders	bcptTestFolders should be an array of folders (relative to project root), which contains performance test apps for this project. Apps in these folders are sorted based on dependencies and built, published and bcpt tests are run in that order. If bcptTestFolders are not specified, AL-Go for GitHub will try to locate bcptTestFolders in the root of the project.	[ ]
pageScriptingTests	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	When true, this setting forces 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	false
restoreDatabases	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	[ ]
appDependencyProbingPaths	Array of dependency specifications, from which apps will be downloaded when the CI/CD workflow is starting. Every dependency specification consists of the following properties: repo = repository version = version (default latest) release_status = latestBuild/release/prerelease/draft (default release) projects = projects (default * = all) branch = branch (default main) AuthTokenSecret = Name of secret containing auth token (default none)	[ ]
cleanModePreprocessorSymbols	List of clean tags to be used in Clean build mode	[ ]
bcptThresholds	Structure with properties for the thresholds when running performance tests using the Business Central Performance Toolkit. DurationWarning = a warning is shown if the duration of a bcpt test degrades more than this percentage (default 10) DurationError - an error is shown if the duration of a bcpt test degrades more than this percentage (default 25) NumberOfSqlStmtsWarning - a warning is shown if the number of SQL statements from a bcpt test increases more than this percentage (default 5) NumberOfSqlStmtsError - an error is shown if the number of SQL statements from a bcpt test increases more than this percentage (default 10) Note that errors and warnings on the build in GitHub are only issued when a threshold is exceeded on the codeunit level, when an individual operation threshold is exceeded, it is only shown in the test results viewer.

AppSource specific basic project settings

Name	Description	Default value
appSourceCopMandatoryAffixes	This setting is only used if the type is AppSource App. The value is an array of affixes, which is used for running AppSource Cop.	[ ]
deliverToAppSource	Structure with properties for AppSource delivery from AL-Go for GitHub. The structure can contain the following properties: branches = an array of branch patterns, which are allowed to deliver to AppSource. (Default main) 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. You need to set generateDependencyArtifact in the project settings file to true in order to include dependencies. Note: You will need to define an AppSourceContext secret in order to publish to AppSource.
obsoleteTagMinAllowedMajorMinor	This setting will enable AppSource cop rule AS0105, which causes objects that are pending obsoletion with an obsolete tag version lower than the minimum set in this property are not allowed.

Basic Repository settings

The repository settings are only read from the repository settings file (.github\AL-Go-Settings.json)

Name	Description
type	Specifies the type of repository. Allowed values are PTE or AppSource App. This value comes with the default repository. Default value is PTE.
projects	Specifies the list of projects in this repository (names of folders containing AL-Go projects). If not specified, AL-Go will enumerate folders in the two levels under the root of the repository for folders containing a .AL-Go folder with a settings.json file.
powerPlatformSolutionFolder	Contains the name of the folder containing a PowerPlatform Solution (only one)
templateUrl	Defines the URL of the template repository used to create this repository and is used for checking and downloading updates to AL-Go System files.
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. You need to run the Update AL-Go System Files workflow for the schedule to take effect.
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. You need to run the Update AL-Go System Files workflow for the schedule to take effect.
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. You need to run the Update AL-Go System Files workflow for the schedule to take effect.
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. You need to run the Update AL-Go System Files workflow for the schedule to take effect.
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. After changing the runs-on setting, you need to run Update AL-Go System Files for this to take effect. You can specify a special GitHub Runner for the build job using the GitHubRunner setting. Read this for more information. 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)
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)
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.
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.
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 <environmentname>_AUTHCONTEXT. You can specify additional information about environments in a setting called DeployTo<environmentname>
DeliverTo<deliveryTarget>	Structure with additional properties for the deliveryTarget specified. Some properties are deliveryTarget specific. The structure can contain the following properties: 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)
DeployTo<environmentname>	Structure with additional properties for the environment specified. <environmentName> refers to the GitHub environment name. The structure can contain the following properties: 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. These branches can also be defined under the environment in GitHub settings and both settings are honored. If neither setting is defined, the default is the main branch only. Projects = In multi-project repositories, this property can be a comma separated list of project patterns to deploy to this environment. (Default *) DependencyInstallMode = 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 and upgrade or forceUpgrade for upgrading dependencies. Scope = Determines the mechanism for deployment to the environment (Dev or 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. 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) BuildMode = specifies which buildMode to use for the deployment. Default is to use the Default buildMode 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 runner to use when deploying to this environment. (Default is settings.runs-on) shell = specifies which shell to use when deploying to this environment, pwsh or powershell. (Default is settings.shell) companyId = Company Id from Business Central (for PowerPlatform connection) ppEnvironmentUrl = Url of the PowerPlatform environment to deploy to
alDoc	Structure with properties for the aldoc reference document generation. The structure can contain the following properties: 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 Actuibs. (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}
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. 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.
CICDPushBranches	CICDPushBranches can be specified as an array of branches, which triggers a CI/CD workflow on commit. You need to run the Update AL-Go System Files workflow for the schedule to take effect. Default is [ "main", "release/*", "feature/*" ]
CICDPullRequestBranches	CICDPullRequestBranches can be specified as an array of branches, which triggers a CI/CD workflow on a PR. You need to run the Update AL-Go System Files workflow for the schedule to take effect. Default is [ "main" ]
pullRequestTrigger	Setting for specifying the trigger AL-Go should use to trigger Pull Request Builds. You need to run the Update AL-Go System Files workflow for the schedule to take effect. Default is pull_request_target
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. You need to run the Update AL-Go System Files workflow for the schedule to take effect. Note: If you configure a CICDSchedule, AL-Go will stop triggering CICDs on push unless you have also added CICDPushBranches to your settings.
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. You need to run the Update AL-Go System Files workflow for the schedule to take effect.
buildModes	A list of build modes to use when building the AL-Go projects. Every AL-Go project will be built using each build mode. AL-Go ships with the following build modes out of the box: Default: Apps are compiled as they are in the source code. Clean: PreprocessorSymbols are enabled when compiling the apps. The values for the symbols correspond to the cleanModePreprocessorSymbols setting of the AL-Go project. Translated: TranslationFile compiler feature is enabled when compiling the apps. It is also possible to specify custom build modes by adding a build mode that is different than 'Default', 'Clean' or 'Translated'.

Advanced settings

Name	Description	Default value
artifact	Determines the artifacts used for building and testing the app. This setting can either be an absolute pointer to Business Central artifacts (https://... - rarely used) or it can be a search specification for artifacts (<storageaccount>/<type>/<version>/<country>/<select>). If not specified, the artifacts used will be the latest sandbox artifacts from the country specified in the country setting. Note: if version is set to *, then the application dependency from the apps in your project will determine which artifacts to use. If select is first, then you will get the first artifacts matching your application dependency. If select is latest then you will get the latest artifacts with the same major.minor as your application dependency.
updateDependencies	Setting updateDependencies to true causes AL-Go to build your app against the first compatible Business Central build and set the dependency version numbers in the app.json accordingly during build. All version numbers in the built app will be set to the version number used during compilation.	false
generateDependencyArtifact	When this repository setting is true, CI/CD pipeline generates an artifact with the external dependencies used for building the apps in this repo.	false
companyName	Company name selected in the database, used for running the CI/CD workflow. Default is to use the default company in the selected Business Central localization.
versioningStrategy	The versioning strategy determines how versioning is performed in this project. The version number of an app consists of 4 tuples: Major.Minor.Build.Revision. Major and Minor are read from the app.json file for each app. Build and Revision are calculated. Currently 3 versioning strategies are supported: 0 = Build is the github run_number for the CI/CD workflow, increased by the runNumberOffset setting value (if specified). Revision is the github run_attempt subtracted 1. 2 = Build is the current date as yyyyMMdd. Revision is the current time as hhmmss. Date and time are always UTC timezone to avoid problems during daylight savings time change. Note that if two CI/CD workflows are started within the same second, this could yield to identical version numbers from two different runs. +16 use repoVersion setting as appVersion (Major and Minor) for all apps	0
additionalCountries	This property can be set to an additional number of countries to compile, publish and test your app against during workflows. Note that this setting can be different in NextMajor and NextMinor workflows compared to the CI/CD workflow, by specifying a different value in a workflow settings file.	[ ]
keyVaultName	When using Azure KeyVault for the secrets used in your workflows, the KeyVault name needs to be specified in this setting if it isn't specified in the AZURE_CREDENTIALS secret. Read this for more information.
licenseFileUrlSecretName	Specify the name (NOT the secret) of the LicenseFileUrl secret. Default is LicenseFileUrl. AL-Go for GitHub will look for a secret with this name in GitHub Secrets or Azure KeyVault to use as LicenseFileUrl. A LicenseFileUrl is required when building AppSource apps for Business Central prior to version 22. Read this for more information.	LicenseFileUrl
ghTokenWorkflowSecretName	Specifies the name (NOT the secret) of the GhTokenWorkflow secret. Default is GhTokenWorkflow. AL-Go for GitHub will look for a secret with this name in GitHub Secrets or Azure KeyVault to use as Personal Access Token with permission to modify workflows when running the Update AL-Go System Files workflow. Read this for more information.	GhTokenWorkflow
adminCenterApiCredentialsSecretName	Specifies the name (NOT the secret) of the adminCenterApiCredentials secret. Default is adminCenterApiCredentials. AL-Go for GitHub will look for a secret with this name in GitHub Secrets or Azure KeyVault to use when connecting to the Admin Center API when creating Online Development Environments. Read this for more information.	AdminCenterApiCredentials
installApps	An array of 3rd party dependency apps, which you do not have access to through the appDependencyProbingPaths. The setting should be an array of either secure URLs or paths to folders or files relative to the project, where the CI/CD workflow can find and download the apps. The apps in installApps are downloaded and installed before compiling and installing the apps.	[ ]
installTestApps	An array of 3rd party dependency apps, which you do not have access to through the appDependencyProbingPaths. The setting should be an array of either secure URLs or paths to folders or files relative to the project, where the CI/CD workflow can find and download the apps. The apps in installTestApps are downloaded and installed before compiling and installing the test apps. Adding a parantheses around the setting indicates that the test in this app will NOT be run, only installed.	[ ]
configPackages	An array of configuration packages to be applied to the build container before running tests. Configuration packages can be the relative path within the project or it can be STANDARD, EXTENDED or EVALUATION for the rapidstart packages, which comes with Business Central.	[ ]
configPackages.country	An array of configuration packages to be applied to the build container for country country before running tests. Configuration packages can be the relative path within the project or it can be STANDARD, EXTENDED or EVALUATION for the rapidstart packages, which comes with Business Central.	[ ]
installOnlyReferencedApps	By default, only the apps referenced in the dependency chain of your apps will be installed when inspecting the settings: InstallApps, InstallTestApps and appDependencyProbingPath. If you change this setting to false, all apps found will be installed.	true
enableCodeCop	If enableCodeCop is set to true, the CI/CD workflow will enable the CodeCop analyzer when building.	false
enableUICop	If enableUICop is set to true, the CI/CD workflow will enable the UICop analyzer when building.	false
customCodeCops	CustomCodeCops is an array of paths or URLs to custom Code Cop DLLs you want to enable when building.	[ ]
enableCodeAnalyzersOnTestApps	If enableCodeAnalyzersOnTestApps is set to true, the code analyzers will be enabled when building test apps as well.	false
failOn	Specifies what the pipeline will fail on. Allowed values are none, warning and error	error
rulesetFile	Filename of the custom ruleset file
enableExternalRulesets	If enableExternalRulesets is set to true, then you can have external rule references in the ruleset	false
vsixFile	Determines which version of the AL Language Extension to use for building the apps. This can be: default to use the AL Language Extension which ships with the Business Central version you are building for latest to always download the latest AL Language Extension from the marketplace preview to always download the preview AL Language Extension from the marketplace. or a direct download URL pointing to the AL Language VSIX file to use for building the apps. By default, AL-Go uses the AL Language extension, which is shipped with the artifacts used for the build.	default
codeSignCertificateUrlSecretName codeSignCertificatePasswordSecretName	When developing AppSource Apps, your app needs to be code signed. Note there is a new way of signing apps, which is described here. Using the old mechanism, you need a certificate .pfx file and password and you need to add secrets to GitHub secrets or Azure KeyVault, specifying the secure URL from which your codesigning certificate pfx file can be downloaded and the password for this certificate. These settings specifies the names (NOT the secrets) of the code signing certificate url and password. Default is to look for secrets called CodeSignCertificateUrl and CodeSignCertificatePassword. Read this for more information.	CodeSignCertificateUrl CodeSignCertificatePassword
keyVaultCodesignCertificateName	When developing AppSource Apps, your app needs to be code signed. Name of a certificate stored in your KeyVault that can be used to codesigning. To use this setting you will also need enable Azure KeyVault in your AL-Go project. Read this for more information
applicationInsightsConnectionStringSecretName	This setting specifies the name (NOT the secret) of a secret containing the application insights connection string for the apps.	applicationInsightsConnectionString
storageContextSecretName	This setting specifies the name (NOT the secret) of a secret containing a json string with StorageAccountName, ContainerName, BlobName and StorageAccountKey or SAS Token. If this secret exists, AL-Go will upload builds to this storage account for every successful build. The BcContainerHelper function New-ALGoStorageContext can create a .json structure with this content.	StorageContext
alwaysBuildAllProjects	This setting only makes sense if the repository is setup for multiple projects. Standard behavior of the CI/CD workflow is to only build the projects, in which files have changes when running the workflow due to a push or a pull request	false
fullBuildPatterns	Use this setting to list important files and folders. Changes to any of these files and folders would trigger a full Pull Request build (all AL-Go projects will be built). Examples: 1. Specifying fullBuildPatterns as [ "Build/*" ] means that any changes from a PR to the Build folder would trigger a full build. 2. Specifying fullBuildPatterns as [ "*" ] means that any changes from a PR would trigger a full build and it is equivalent to setting alwaysBuildAllProjects to true.	[ ]
skipUpgrade	This setting is used to signal to the pipeline to NOT run upgrade and ignore previous releases of the app.	false
cacheImageName	When using self-hosted runners, cacheImageName specifies the prefix for the docker image created for increased performance	my
cacheKeepDays	When using self-hosted runners, cacheKeepDays specifies the number of days docker image are cached before cleaned up when running the next pipeline. Note that setting cacheKeepDays to 0 will flush the cache before every build and will cause all other running builds using agents on the same host to fail.	3
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
enableTaskScheduler	Setting enableTaskScheduler to true in your project setting file, causes the build container to be created with the Task Scheduler running.	false
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. Note when using UseCompilerFolder you need to sign apps using the new signing mechanism described here.	false
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.	[ ]
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.	true
trustedNuGetFeeds	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"). 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. 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.	[ ]
trustedSigning	Structure defining the properties needed for enabling trusted Signing. Please read this to setup your Azure Trusted Signing Account and Certificate Profile and then provide these properties in this setting: Account must be the name of your trusted signing account. Endpoint must point to the endpoint of your trusted signing account (ex. https://weu.codesigning.azure.net). CertificateProfile must be the CertificateProfile in your trusted signing account you want to use for signing. Please note that your Azure_Credentials secret (Microsoft Entra ID App or Managed identity) needs to provide access to your azure subscription and be assigned the Trusted Signing Certificate Profile Signer role in the Trusted Signing Account.

AppSource specific advanced settings

Name	Description	Default value
appSourceContextSecretName	This setting specifies the name (NOT the secret) of a secret containing a json string with ClientID, TenantID and ClientSecret or RefreshToken. If this secret exists, AL-Go will can upload builds to AppSource validation.	AppSourceContext
keyVaultCertificateUrlSecretName keyVaultCertificatePasswordSecretName keyVaultClientIdSecretName	If you want to enable KeyVault access for your AppSource App, you need to provide 3 secrets as GitHub Secrets or in the Azure KeyVault. The names of those secrets (NOT the secrets) should be specified in the settings file with these 3 settings. Default is to not have KeyVault access from your AppSource App. Read this for more information.

Conditional Settings

In any of the settings files, you can add conditional settings by using the ConditionalSettings setting.

Example, adding this:

    "ConditionalSettings": [
        {
            "branches": [
                "feature/*"
            ],
            "settings": {
                "doNotPublishApps": true,
                "doNotSignApps": true
            }
        }
    ]

to your project settings file will ensure that all branches matching the patterns in branches will use doNotPublishApps=true and doNotSignApps=true during CI/CD. Conditions can be:

• repositories settings will be applied to repositories matching the patterns
• projects settings will be applied to projects matching the patterns
• branches settings will be applied to branches matching the patterns
• workflows settings will be applied to workflows matching the patterns
• users settings will be applied for users matching the patterns

You could imagine that you could have and organizational settings variable containing:

    "ConditionalSettings": [
        {
            "repositories": [
                "bcsamples-*"
            ],
            "branches": [
                "features/*"
            ],
            "settings": {
                "doNotSignApps": true
            }
        }
    ]

Which will ensure that for all repositories named bcsamples-* in this organization, the branches matching features/* will not sign apps.

Note

You can have conditional settings on any level and all conditional settings which has all conditions met will be applied in the order of settings file + appearance.

Expert settings (rarely used)

Name	Description	Default value
repoName	the name of the repository	name of GitHub repository
runNumberOffset	when using VersioningStrategy 0, the CI/CD workflow uses the GITHUB RUN_NUMBER as the build part of the version number as described under VersioningStrategy. The RUN_NUMBER is ever increasing and if you want to reset it, when increasing the Major or Minor parts of the version number, you can specify a negative number as runNumberOffset. You can also provide a positive number to get a starting offset. Read about RUN_NUMBER here	0
applicationDependency	Application dependency defines the lowest Business Central version supported by your app (Build will fail early if artifacts used are lower than this). The value is calculated by reading app.json for all apps, but cannot be lower than the applicationDependency setting which has a default value of 18.0.0.0	18.0.0.0
installTestRunner	Determines whether the test runner will be installed in the pipeline. If there are testFolders in the project, this setting will be true.	calculated
installTestFramework	Determines whether the test framework apps will be installed in the pipeline. If the test apps in the testFolders have dependencies on the test framework apps, this setting will be true	calculated
installTestLibraries	Determines whether the test libraries apps will be installed in the pipeline. If the test apps in the testFolders have dependencies on the test library apps, this setting will be true	calculated
installPerformanceToolkit	Determines whether the performance test toolkit apps will be installed in the pipeline. If the test apps in the testFolders have dependencies on the performance test toolkit apps, this setting will be true	calculated
enableAppSourceCop	Determines whether the AppSourceCop will be enabled in the pipeline. If the project type is AppSource App, then the AppSourceCop will be enabled by default. You can set this value to false to force the AppSourceCop to be disabled	calculated
enablePerTenantExtensionCop	Determines whether the PerTenantExtensionCop will be enabled in the pipeline. If the project type is PTE, then the PerTenantExtensionCop will be enabled by default. You can set this value to false to force the PerTenantExtensionCop to be disabled	calculated
doNotBuildTests	This setting forces the pipeline to NOT build and run the tests and performance tests in testFolders and bcptTestFolders	false
doNotRunTests	This setting forces the pipeline to NOT run the tests in testFolders. Tests are still being built and published. Note this setting can be set in a workflow specific settings file to only apply to that workflow	false
doNotRunBcptTests	This setting forces the pipeline to NOT run the performance tests in testFolders. Performance tests are still being built and published. Note this setting can be set in a workflow specific settings file to only apply to that workflow	false
memoryLimit	Specifies the memory limit for the build container. By default, this is left to BcContainerHelper to handle and will currently be set to 8G	8G
BcContainerHelperVersion	This setting can be set to a specific version (ex. 3.0.8) of BcContainerHelper to force AL-Go to use this version. latest means that AL-Go will use the latest released version. preview means that AL-Go will use the latest preview version. dev means that AL-Go will use the dev branch of containerhelper.	latest (or preview for AL-Go preview)
unusedALGoSystemFiles	An array of AL-Go System Files, which won't be updated during Update AL-Go System Files. They will instead be removed. Use this setting with care, as this can break the AL-Go for GitHub functionality and potentially leave your repo no longer functional.	[ ]

Expert level

Custom Delivery

You can override existing AL-Go Delivery functionality or you can define your own custom delivery mechanism for AL-Go for GitHub, by specifying a PowerShell script named DeliverTo*.ps1 in the .github folder. The following example will spin up a delivery job to SharePoint on CI/CD and Release.

DeliverToSharePoint.ps1

Param(
    [Hashtable]$parameters
)

Write-Host "Current project path: $($parameters.project)"
Write-Host "Current project name: $($parameters.projectName)"
Write-Host "Delivery Type (CD or Release): $($parameters.type)"
Write-Host "Folder containing apps: $($parameters.appsFolder)"
Write-Host "Folder containing test apps: $($parameters.testAppsFolder)"
Write-Host "Folder containing dependencies (requires generateDependencyArtifact set to true): $($parameters.dependenciesFolder)"

Write-Host "Repository settings:"
$parameters.RepoSettings | Out-Host
Write-Host "Project settings:"
$parameters.ProjectSettings | Out-Host

Note

You can override existing AL-Go for GitHub delivery functionality by creating a script called f.ex. DeliverToStorage.ps1 in the .github folder.

Here are the parameters to use in your custom script:

Parameter	Description	Example
$parametes.project	The current AL-Go project	Root/AllProjects/MyProject
$parameters.projectsName	The name of the current AL-Go project	Root_AllProjects_MyProject
$parameters.type	Type of delivery (CD or Release)	CD
$parameters.appsFolder	The folder that contains the build artifacts from the default build of the non-test apps in the AL-Go project	AllProjects_MyProject-main-Apps-1.0.0.0
$parameters.testAppsFolder	The folder that contains the build artifacts from the default build of the test apps in the AL-Go project	AllProjects_MyProject-main-TestApps-1.0.0.0
$parameters.dependenciesFolder	The folder that contains the dependencies of the the AL-Go project for the default build	AllProjects_MyProject-main-Dependencies-1.0.0.0
$parameters.appsFolders	The folders that contain the build artifacts from all builds (from different build modes) of the non-test apps in the AL-Go project	AllProjects_MyProject-main-Apps-1.0.0.0, AllProjects_MyProject-main-CleanApps-1.0.0.0
$parameters.testAppsFolders	The folders that contain the build artifacts from all builds (from different build modes) of the test apps in the AL-Go project	AllProjects_MyProject-main-TestApps-1.0.0.0, AllProjects_MyProject-main-CleanTestApps-1.0.0.0
$parameters.dependenciesFolders	The folders that contain the dependencies of the AL-Go project for all builds (from different build modes)	AllProjects_MyProject-main-Dependencies-1.0.0.0, AllProjects_MyProject-main-CleanDependencies-1.0.0.0

Custom Deployment

You can override existing AL-Go Deployment functionality or you can define your own custom deployment mechanism for AL-Go for GitHub. By specifying a PowerShell script named DeployTo<EnvironmentType>.ps1 in the .github folder. Default Environment Type is SaaS, but you can define your own type by specifying EnvironmentType in the DeployTo<EnvironmentName> setting. The following example will create a script, which would be called by CI/CD and Publish To Environment, when EnvironmentType is set to OnPrem.

DeployToOnPrem.ps1

Param(
    [Hashtable]$parameters
)

Write-Host "Deployment Type (CD or Release): $($parameters.type)"
Write-Host "Apps to deploy: $($parameters.apps)"
Write-Host "Environment Type: $($parameters.EnvironmentType)"
Write-Host "Environment Name: $($parameters.EnvironmentName)"

$tempPath = Join-Path ([System.IO.Path]::GetTempPath()) ([GUID]::NewGuid().ToString())
New-Item -ItemType Directory -Path $tempPath | Out-Null
Copy-AppFilesToFolder -appFiles $parameters.apps -folder $tempPath | Out-Null
$appsList = @(Get-ChildItem -Path $tempPath -Filter *.app)
if (-not $appsList -or $appsList.Count -eq 0) {
    Write-Host "::error::No apps to publish found."
    exit 1
}
Write-Host "Apps:"
$appsList | ForEach-Object { Write-Host "- $($_.Name)" }

Note

You can override existing AL-Go for GitHub deployment functionality by creating a script called f.ex. DeployToSaas.ps1 in the .github folder, as the default deployment type is Saas.

Here are the parameters to use in your custom script:

Parameter	Description	Example
$parameters.type	Type of delivery (CD or Release)	CD
$parameters.apps	Apps to deploy. This can either be an array of .zip files or .app files, or it can be an array of folders, containing apps or .zip files. Publish-BcContainerApp supports this array directly, but you should use Copy-AppFilesToFolder -appFiles $parameters.apps -folder $tempFolder to extract and copy all apps to a temp folder, if you are to handle the apps yourself.	/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.Scope	Identifies the scope for the deployment, Dev or PTE	PTE
$parameters.SyncMode	Is the SyncMode to use for the deployment: ForceSync or Add. If deploying to the dev scope, it can also be Development or Clean	Add
$parameters.BuildMode	Is the buildMode used for the deployment	Clean
$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
$parameters."shell"	Shell used to run the deployment script, pwsh or powershell	powershell

Run-AlPipeline script override

AL-Go for GitHub utilizes the Run-AlPipeline function from BcContainerHelper to perform the actual build (compile, publish, test etc). The Run-AlPipeline function supports overriding functions for creating containers, compiling apps and a lot of other things.

This functionality is also available in AL-Go for GitHub, by adding a file to the .AL-Go folder, you automatically override the function.

Override	Description
DockerPull.ps1	Pull the image specified by the parameter $imageName
NewBcContainer.ps1	Create the container using the parameters transferred in the $parameters hashtable
ImportTestToolkitToBcContainer.ps1	Import the test toolkit apps specified by the $parameters hashtable
CompileAppInBcContainer.ps1	Compile the apps specified by the $parameters hashtable
GetBcContainerAppInfo.ps1	Get App Info for the apps specified by the $parameters hashtable
PublishBcContainerApp.ps1	Publish apps specified by the $parameters hashtable
UnPublishBcContainerApp.ps1	UnPublish apps specified by the $parameters hashtable
InstallBcAppFromAppSource.ps1	Install apps from AppSource specified by the $parameters hashtable
SignBcContainerApp.ps1	Sign apps specified by the $parameters hashtable
ImportTestDataInBcContainer.ps1	If this function is provided, it is expected to insert the test data needed for running tests
RunTestsInBcContainer.ps1	Run the tests specified by the $parameters hashtable
GetBcContainerAppRuntimePackage.ps1	Get the runtime package specified by the $parameters hashtable
RemoveBcContainer.ps1	Cleanup based on the $parameters hashtable
InstallMissingDependencies	Install missing dependencies
BackupBcContainerDatabases	Backup Databases in container for subsequent restore(s)
RestoreDatabasesInBcContainer	Restore Databases in container
InstallMissingDependencies	Install missing dependencies

BcContainerHelper settings

The repo settings file (.github\AL-Go-Settings.json) can contain BcContainerHelper settings. Some BcContainerHelper settings are machine specific (folders and like), and should not be set in the repo settings file.

Settings, which might be relevant to set in the settings file includes

Setting	Description	Default
baseUrl	The Base Url for the online Business Central Web Client. This should be changed when targetting embed apps.	https://businesscentral.dynamics.com
apiBaseUrl	The Base Url for the online Business Central API endpoint. This should be changed when targetting embed apps.	https://api.businesscentral.dynamics.com
PartnerTelemetryConnectionString	The Telemetry Connection String for partner telemetry for DevOps telemetry.
SendExtendedTelemetryToMicrosoft	Set this value to true if you agree to emit extended DevOps telemetry to Microsoft.	false
ObjectIdForInternalUse	BcContainerHelper will use this Object ID for internal purposes. Change if the default Object ID is in use.	88123
TreatWarningsAsErrors	A list of AL warning codes, which should be treated as errors	[ ]
DefaultNewContainerParameters	A list of parameters to be added to all container creations in this repo	{ }

Your own version of AL-Go for GitHub

For experts only, following the description here you can setup a local fork of AL-Go for GitHub and use that as your templates. You can fetch upstream changes from Microsoft regularly to incorporate these changes into your version and this way have your modified version of AL-Go for GitHub.

Note

Our goal is to never break repositories, which are using AL-Go for GitHub as their template. We almost certainly will break you if you create local modifications to scripts and pipelines.

---

back