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-TemplateRepoSettings.doNotEdit.json is the repository settings from a custom template repository (if applicable)

3. .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).

4. 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.

5. .github/AL-Go-TemplateProjectSettings.doNotEdit.json is the project settings from a custom template repository (if applicable)

6. .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)

7. .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.

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

9. .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> (or <major>.<minor>.<build> when versioningStrategy is 3 or 3+16) 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)	[ ]
preprocessorSymbols	List of preprocessor symbols to use when building the apps. This setting can be specified in workflow specific settings files or in conditional settings.	[ ]
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.
postponeProjectInBuildOrder	When this setting is enabled (true), the project will be postponed to the end of the build sequence whenever possible - specifically, when no other projects depend on it. This allows, for example, test projects to run only after all build projects have completed successfully. This setting only has effect when useProjectDependencies is also enabled, as dependency information is required to determine whether postponement is allowed.	false
projectsToTest	An array of project paths that this project depends on for testing. Setting this marks the project as a test project — it will not build any apps itself but will install the apps produced by the referenced projects and run tests against them. This lets you separate test execution from compilation so you can re-run tests without a full rebuild. The project must not contain any buildable code (appFolders, testFolders, or bcptTestFolders). A test project cannot depend on another test project. Use full project paths (e.g. "build/projects/MyApp").	[ ]

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.
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. includeTestAppsInSandboxEnvironment = deploys test apps and their dependencies if the environment type is sandbox (Default is false) excludeAppIds = array of app ids to exclude from deployment. (Default is []) 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 change to take effect. Default is [ "main", "release/*", "feature/*" ] Supported release branch naming formats: When using release branches, AL-Go supports various naming conventions for matching previous releases during upgrade testing. The following formats are recognized: • releases/26 - matches releases with major version 26 • releases/26.x - matches releases with major version 26 • releases/26x - matches releases with major version 26 • releases/v26 - matches releases with major version 26 • releases/v26.x - matches releases with major version 26 • releases/v26x - matches releases with major version 26 • releases/26.3 - matches releases with major.minor version 26.3 The same patterns work with the singular release/ prefix.
CICDPullRequestBranches	CICDPullRequestBranches can be specified as an array of branches (branch patterns). A Pull Request Build will be triggered when a PR targets a branch that matches one of the patterns in this list. You need to run the Update AL-Go System Files workflow for the change to take effect. Default is [ "main" ]
pullRequestTrigger	Setting for specifying the trigger AL-Go should use to trigger Pull Request Builds. Note that when using the default pull_request trigger, secrets are not available to the workflow for pull requests from forks. If you need secret access for fork PRs, you can set this to pull_request_target, but make sure you understand the security implications first. You need to run the Update AL-Go System Files workflow for the change to take effect. Default is pull_request
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. The following build modes have special meaning in AL-Go: Default: Apps are compiled as they are in the source code. Clean: Should be used for Clean Mode. Use Conditional Settings with buildMode set the 'Clean' to specify preprocessorSymbols for clean mode. 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' and use conditional settings to specify preprocessor symbols and other build settings for the build mode.
useGitSubmodules	If your repository is using Git Submodules, you can set the useGitSubmodules setting to "true" or "recursive" in order to use these submodules during build workflows. If useGitSubmodules is not set, git submodules are not initialized. If the submodules reside in private repositories, you need to define a gitSubmodulesToken secret. Read this for more information.
commitOptions	If you want more control over how AL-Go creates pull requests or commits changes to the repository you can define commitOptions. It 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 work items. createPullRequest : A boolean defining whether AL-Go should create a pull request or attempt to push directly in the branch. 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. pullRequestMergeMethod = A string defining which merge method to use when auto-merging pull requests. Valid values are "merge" and "squash". Default is "squash". 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. If you want different behavior in different AL-Go workflows you can add the commitOptions setting to your workflow-specific settings files.
incrementalBuilds	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 CI/CD build, newer than the defined retentionDays and only rebuild projects or apps (based on mode) which needs to be rebuilt. The structure supports the following properties: onPush = Determines whether incremental builds is enabled in CI/CD triggered by a merge/push event. Default is false. onPull_Request = Determines whether incremental builds is enabled in Pull Requests. Default is true. onSchedule = Determines whether incremental builds is enabled 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 = Specifies the mode for incremental builds. Currently, two values are supported. Use modifiedProjects when you want to rebuild all apps in all modified projects and depending projects or modifiedApps if you want to rebuild modified apps and all apps with dependencies to this app. NOTE: when running incremental builds, it is recommended to also set workflowConcurrency for the CI/CD workflow, as defined here.
workflowDefaultInputs	An array of workflow input default values. This setting allows you to configure default values for workflow_dispatch inputs, making it easier to run workflows manually with consistent settings. If a workflow also has matching workflow_call inputs, those will receive the same default values to ensure consistency in reusable workflows. Each entry should contain:   name = The name of the workflow input   value = The default value (can be string, boolean, or number) Important validation rules:   • The value type must match the input type defined in the workflow YAML file (boolean, number, string, or choice)   • For choice inputs, the value must be one of the options declared in the workflow   • Choice validation is case-sensitive Type and choice validation is performed when running the "Update AL-Go System Files" workflow to prevent configuration errors. When you run the "Update AL-Go System Files" workflow, these default values will be applied to matching workflow_dispatch inputs. If a workflow also defines workflow_call inputs with the same names, those inputs will receive the same defaults to ensure consistency between manual and programmatic workflow invocations. Usage: 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. Important: When multiple conditional settings blocks match and both define workflowDefaultInputs, the arrays are merged (all entries are kept). When the defaults are applied to workflows, the last matching entry for each input name wins. Example: "workflowDefaultInputs": [ { "name": "directCommit", "value": true }, { "name": "useGhTokenWorkflow", "value": true }, { "name": "updateVersionNumber", "value": "+0.1" } ]

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. ⚠️ Warning: When the updateDependencies setting is enabled, the application versions from the BC Artifact are stamped into the app.json. However, not all app versions available in BC Artifacts are shipped in BC SaaS, which can lead to dependency resolution failures during AppSource validation. Therefore, it is not recommended to use this setting if you intend on deploying the build to AppSource.	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 segments: 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. 3 = Build is taken from app.json (like Major and Minor) and Revision is the github run_number of the workflow run 15 = Build is max value and Revision is the github run_number of the workflow run. Note: use this strategy with caution. We recommend using it only when producing non-official artifacts (e.g. from PR builds or test workflows). +16 when adding 16 to the above versioning strategies, all builds will use repoVersion setting instead of the Major.Minor found inside app.json (and also build if versioningStrategy is 3+16)	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. Note: If you specify ${{SECRETNAME}} as part of a URL, it will be replaced by the value of the secret SECRETNAME.	[ ]
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 parentheses around the setting indicates that the test in this app will NOT be run, only installed. Note: If you specify ${{SECRETNAME}} as part of a URL, it will be replaced by the value of the secret SECRETNAME.	[ ]
runTestsInAllInstalledTestApps	PREVIEW: By default AL-Go will publish test apps built in previous jobs within the workflow but will not execute the tests. By setting this to true, AL-Go will start running tests in all the test apps produced by previous jobs	false
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. Relative paths are resolved against the project folder (the folder containing .AL-Go/settings.json).	[ ]
features	Features is an array of compiler features to enable when building. Possible values include LcgTranslationFile, TranslationFile, and GenerateCaptions.	[ ]
enableCodeAnalyzersOnTestApps	If enableCodeAnalyzersOnTestApps is set to true, the code analyzers will be enabled when building test apps as well.	false
trackALAlertsInGitHub	If trackALAlertsInGitHub is set to true, AL code analysis results will be uploaded and tracked in the GitHub security tab. Additionally, if Advanced Security is enabled in the repo, new AL code alerts will be posted in PRs that introduce them. This setting must be enabled on the repo level, but can be optionally disabled per project. Note: AL Alerts are only enabled for warnings at the moment. Support for displaying errors will come in a future release	false
failOn	Specifies what the pipeline will fail on. Allowed values are none, warning, newWarning and error. Using 'newWarning' will lead to pull requests failing if new warnings are added, while still behaving like 'error' for normal build steps.	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 (deprecated)	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
workspaceCompilation	PREVIEW: Configuration for workspace compilation. This uses the AL tool to compile all apps in the workspace in a single operation, which can improve build performance for repositories with multiple apps. Like useCompilerFolder, this is containerless compiling. enabled - Set to true to enable workspace compilation. Default: false. parallelism - The number of parallel compilation processes. Set to 0 or -1 to use all available processors. Default: 1. Note: Workspace compilation requires the artifact setting to use BC v28 or higher. Workspace compilation supports incremental builds when incrementalBuilds.mode is set to modifiedApps. In incremental mode, only modified apps and their dependents are recompiled; unmodified apps are downloaded from the baseline workflow run.	{ "enabled": false, "parallelism": 1 }
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.	[ ]
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.	LatestMatching
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.
shortLivedArtifactsRetentionDays	Number of days to keep short lived build artifacts (f.ex build artifacts from pull request builds, next minor or next major builds). 0 means use GitHub default.	1
updateALGoSystemFilesEnvironment	If specified, this is the name of the environment, which holds the GhTokenWorkflow secret. With this, you can ensure that the Update AL-Go System Files can be guarded by an approval workflow by setting this on the environment used. You need to run the Update AL-Go System Files (with the GhTokenWorkflow in place globally) this setting to take effect.

Workflow specific settings

The following settings are only allowed in workflow specific settings files or in conditional settings, specifying the workflows for which is should be enabled. The workflow specific settings file can be created in .github\\<workflowName>.settings.json

Name	Description
workflowSchedule	The value should be a structure with a property named cron, containing a valid crontab, which is 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. The structure can also contain includeBranches, an array of branches to support when running the workflow on multiple branches. Currently, only "Update AL-Go System Files" is supported to run on multiple branches. 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	A setting 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.

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
• buildModes settings will be applied when building with these buildModes
• 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
• triggers settings will be applied when GITHUB_EVENT_NAME matches values (for example push, pull_request, schedule, workflow_dispatch)

Note: You can use workflowDefaultInputs within conditional settings to apply workflow input defaults only when certain conditions are met. For example, you could set different default values for specific workflows or branches.

You could imagine that you could have an 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.

Workflow Name Sanitization

When matching workflow names for conditional settings, AL-Go sanitizes the actual workflow name before comparison. Sanitization removes invalid filename characters such as leading spaces, quotes, colons, slashes, and other special characters. For example, a workflow named " CI/CD" would be sanitized to "CICD" for matching purposes.

Expert level

The settings and functionality in the expert section might require knowledge about GitHub Workflows/Actions, YAML, docker and PowerShell. Please only change these settings and use this functionality after careful consideration as these things might change in the future and will require you to modify the functionality you added based on this.

Please read the release notes carefully when installing new versions of AL-Go for GitHub.

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 (deprecated)	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.	[ ]
reportSuppressedDiagnostics	If this setting is set to true, the AL compiler will report diagnostics which are suppressed in the code using the pragma #pragma warning disable <id>. This can be useful if you want to ensure that no warnings are suppressed in your code.	false
customALGoFiles	An object to configure custom AL-Go files, that will be updated during "Update AL-Go System Files" workflow. The object can contain properties filesToInclude and filesToExclude. Read more at Customizing AL-Go.	{ "filesToInclude": [], "filesToExclude": [] }

Overwrite settings

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.

Example: Say, ALGoOrgSettings contains the following values

{
    "country": "de"
    "buildModes": ["Default"]
}

and .github\AL-Go-Settings.json contains the following values:

{
    "country": "dk"
    "buildModes": ["Clean"]
}

then, after merging, the result settings object will contain the following values:

{
    "country": "dk"
    "buildModes": ["Default", "Clean"]
}

In order to change this behavior, you can specify 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.

Example: Say, ALGoOrgSettings contains the following values:

{
    "country": "de"
    "buildModes": ["Default"]
}

and .github\AL-Go-Settings.json contains the following values

{
    "overwriteSettings": ["buildModes"]
    "country": "dk"
    "buildModes": ["Clean"]
}

then, after merging, the result settings object will contain the following values:

{
    "country": "dk"
    "buildModes": ["Clean"]
}

Note: overwriteSettings isn't a setting on its own and it isn't available in the output of ReadSetting action, for example. It's merely used to control the settings merging mechanism and allow overwriting complex settings types. The value of overwriteSettings should only contain settings of types array or object and all the settings in overwriteSettings should be present with the new value.

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<DeliveryTarget>.ps1 in the .github folder. The following example will spin up a delivery job to SharePoint on CI/CD and Release. Beside the script, you also need to create a secret called <DeliveryTarget>Context, formatted as compressed json, containing delivery information for your delivery target.

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 "Delivery Context: $($parameters.context)"
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

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)" }

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.

Note that changes to AL-Go for GitHub or Run-AlPipeline functionality in the future might break the usage of these overrides.

Override	Description
PipelineInitialize.ps1	Initialize the pipeline
DockerPull.ps1	Pull the image specified by the parameter $imageName
NewBcContainer.ps1	Create the container using the parameters transferred in the $parameters hashtable
NewBcCompilerFolder.ps1	Create the compilerFolder 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
GetBcContainerEventLog.ps1	Get the eventlog based on the $parameters hashtable
RemoveBcContainer.ps1	Cleanup based on the $parameters hashtable
RemoveBcCompilerFolder.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
PreNewBcCompilerFolder	Hook script to run before creating the compiler folder. The script should accept a hashtable of the parameters ([hashtable] $parameters) that will be passed to New-BcCompilerFolder. The script can modify the hashtable in-place to customize the compiler folder creation. Note: This hook is only called when workspace compilation is enabled.
PostNewBcCompilerFolder	Hook script to run after creating the compiler folder. The script should accept the parameters hashtable ([hashtable] $parameters) and the path to the created compiler folder ([string] $compilerFolder). Note: This hook is only called when workspace compilation is enabled.
PreCompileApp	Custom script to run before compiling an app. The script should accept the type of the app ([string] $appType) and a reference to the compilation parameters ([ref] $compilationParams). Possible values for $appType are: app, testApp, bcptApp.
PostCompileApp	Custom script to run after compiling an app. The script should accept the file path of the produced .app file ([string] $appFilePath), the type of the app ([string] $appType), and a hashtable of the compilation parameters ([hashtable] $compilationParams). Possible values for $appType are: app, testApp, bcptApp.
InstallMissingDependencies	Install missing dependencies
PipelineFinalize.ps1	Finalize the pipeline

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

Note that changes to AL-Go for GitHub or Run-AlPipeline functionality in the future might break the usage of these overrides.

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	{ }

Custom jobs in AL-Go for GitHub workflows

Adding a custom job to any AL-Go for GitHub workflow is done by adding a job with the name CustomJob<something> to the end of an AL-Go for GitHub workflow, like this:

  CustomJob-PrepareDeploy:
    name: My Job
    needs: [ Build ]
    runs-on: [ ubuntu-latest ]
    defaults:
      run:
        shell: pwsh
    steps:
      - name: This is my job
        run: |
          Write-Host "This is my job"

In the needs property, you specify which jobs should be complete before this job is run. If you require this job to run before other AL-Go for GitHub jobs are complete, you can add the name of this job in the needs property of that job, like:

  Deploy:
    needs: [ Initialization, Build, CustomJob-PrepareDeploy ]
    if: always() && needs.Build.result == 'Success' && needs.Initialization.outputs.environmentCount > 0
    strategy: ${{ fromJson(needs.Initialization.outputs.environmentsMatrixJson) }}

Custom jobs will be preserved when running Update AL-Go System Files.

Note that installing apps from the GitHub marketplace might require you to add custom jobs or steps to some of the workflows to get the right integration. In custom jobs, you can use any actions from the GitHub marketplace.

Custom template repositories

If you are utilizing script overrides, custom jobs, custom delivery or like in many repositories, you might want to take advantage of the custom template repository feature.

A custom template repository is an AL-Go for GitHub repository (without any apps), which is used as a template for the remaining AL-Go for GitHub repositories. As an example, if you are using a custom delivery script, which you want to have in all your repositories, you can create an empty AL-Go for GitHub repository, place the delivery script in the .github folder and use that repository as a template when running Update AL-Go system files in your other repositories.

This would make sure that all repositories would have this script (and updated versions of the script) in the future.

The items, which are currently supported from custom template repositories are:

• Repository script overrides in the .github folder
• Project script overrides in the .AL-Go folder
• Custom workflows in the .github/workflows folder
• Custom jobs in any AL-Go for GitHub workflow
• Changes to repository settings in .github/AL-Go-settings.json
• Changes to project settings in .AL-Go/settings.json

Note that an AL-Go for GitHub custom template repository can be private or public.

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.

---

back