Settings Reference

AL-Go for GitHub behavior is controlled by settings defined in various locations. This guide covers all available settings and where to configure them.

Settings Location Hierarchy

Settings are applied in order, with later settings overriding earlier ones:

Organizational settings

ALGoOrgSettings GitHub variable (organization level) - applies to all AL-Go repositories in the organization

Template repository settings

.github/AL-Go-TemplateRepoSettings.doNotEdit.json - settings from custom template repository

Repository settings

.github/AL-Go-settings.json - repository-wide settings for all projects

Repository variables

ALGoRepoSettings GitHub variable (repository level) - repository-wide settings

Template project settings

.github/AL-Go-TemplateProjectSettings.doNotEdit.json - project settings from template

Project settings

.AL-Go/settings.json - project-specific settings

Single project: .AL-Go/settings.json in repository root
Multiple projects: <project>/.AL-Go/settings.json in each project folder

Workflow-specific settings

All projects: .github/<workflow>.settings.json
Specific project: .AL-Go/<workflow>.settings.json

User-specific settings

.AL-Go/<username>.settings.json - rarely used, for local scripts

The repository settings file (.github/AL-Go-settings.json) can also contain BcContainerHelper settings, applied when loading BcContainerHelper in workflows.

Basic Project Settings

Core Configuration

{
  "country": "us",
  "repoVersion": "1.0",
  "projectName": "My AL Project",
  "appFolders": ["App", "BaseApp"],
  "testFolders": ["App.Test"],
  "bcptTestFolders": ["Performance.Test"]
}

Setting	Description	Default
`country`	Country/localization for the app	`us`
`repoVersion`	Project version number (major.minor)	`1.0`
`projectName`	Friendly name for the project in UI	`''`
`appFolders`	Array of folders containing apps	Auto-detected
`testFolders`	Array of folders containing test apps	Auto-detected
`bcptTestFolders`	Array of folders containing performance test apps	Auto-detected

Testing Configuration

{
  "pageScriptingTests": [
    "recordings/*.yml",
    "recordings/my*.yml",
    "recordings/test.yml"
  ],
  "doNotRunpageScriptingTests": false
}

Setting	Description	Default
`pageScriptingTests`	Array of page scripting test file specifications	`[]`
`doNotRunpageScriptingTests`	Skip page scripting tests	`false`
`restoreDatabases`	Events that trigger database restore	`[]`
`bcptThresholds`	Performance test threshold configuration	See above

Dependencies

{
  "appDependencyProbingPaths": [
    {
      "repo": "owner/repository",
      "version": "latest",
      "release_status": "release",
      "projects": "*",
      "branch": "main",
      "AuthTokenSecret": "GhTokenWorkflow"
    }
  ]
}

Setting	Description	Default
`appDependencyProbingPaths`	Array of dependency sources to download from	`[]`
`installApps`	Third-party apps to install before compilation	`[]`
`installTestApps`	Third-party test apps to install (parentheses = don’t run tests)	`[]`
`installOnlyReferencedApps`	Only install referenced apps from dependencies	`true`

In installApps and installTestApps, use ${{SECRETNAME}} to insert secret values into URLs.

Preprocessor and Build Modes

{
  "preprocessorSymbols": ["CLEAN", "DEBUG"]
}

AppSource-Specific Settings

{
  "type": "AppSource App",
  "appSourceCopMandatoryAffixes": ["MyPrefix", "MyCompany"],
  "obsoleteTagMinAllowedMajorMinor": "1.0"
}

Setting	Description	Default
`appSourceCopMandatoryAffixes`	Required affixes for AppSource Cop	`[]`
`obsoleteTagMinAllowedMajorMinor`	Minimum allowed obsolete tag version (enables AS0105)	-
`deliverToAppSource`	AppSource delivery configuration	-

AppSource delivery requires an AppSourceContext secret. See Secrets documentation.

Repository Settings

These settings are only read from .github/AL-Go-Settings.json:

{
  "type": "PTE",
  "templateUrl": "https://github.com/microsoft/AL-Go-PTE"
}

Setting	Description	Default
`type`	Repository type: `PTE` or `AppSource App`	`PTE`
`projects`	List of project folders (auto-detected if not specified)	-
`templateUrl`	URL of template repository for updates	-
`runs-on`	GitHub runner for non-build jobs	`windows-latest`
`githubRunner`	GitHub runner for build/test jobs	`windows-latest`
`shell`	Default shell for all jobs	`powershell`
`githubRunnerShell`	Shell for build jobs	Same as `shell`

Environments and Deployment

{
  "environments": ["QA", "PROD"],
  "excludeEnvironments": ["github-pages"]
}

Workflow Triggers

{
  "CICDPushBranches": ["main", "release/*", "feature/*"],
  "CICDPullRequestBranches": ["main"]
}

Setting	Description	Default
`CICDPushBranches`	Branches that trigger CI/CD on push	`["main", "release/", "feature/"]`
`CICDPullRequestBranches`	Branches that trigger PR builds	`["main"]`
`pullRequestTrigger`	PR trigger type: `pull_request` or `pull_request_target`	`pull_request`

Using pull_request_target exposes secrets to fork PRs. Understand the security implications before using.

Supported Release Branch Formats

AL-Go supports various release branch naming conventions:

releases/26 - matches major version 26
releases/26.x or releases/26x - matches major version 26
releases/v26 or releases/v26.x - matches major version 26
releases/26.3 - matches major.minor version 26.3
release/* - same patterns with singular prefix

Advanced Settings

Artifacts and Versioning

{
  "artifact": "",
  "updateDependencies": false,
  "generateDependencyArtifact": true
}

Setting	Description	Default
`artifact`	BC artifacts search specification	Latest sandbox for country
`updateDependencies`	Update dependencies during build	`false`
`generateDependencyArtifact`	Generate dependency artifacts	`false`
`versioningStrategy`	Version calculation method (0, 2, 3, 15, or +16 variants)	`0`

Using updateDependencies: true can cause AppSource validation failures, as not all BC artifact versions are shipped in SaaS.

Versioning Strategies

Strategy	Build Number	Revision Number
`0`	`run_number` + `runNumberOffset`	`run_attempt` - 1
`2`	Current date (yyyyMMdd)	Current time (hhmmss)
`3`	From app.json	`run_number`
`15`	Maximum value	`run_number`
`+16`	Uses `repoVersion` instead of app.json major.minor	-

Code Analysis

{
  "enableCodeCop": true,
  "enableUICop": true,
  "customCodeCops": [
    "https://example.com/customcop.dll"
  ],
  "enableCodeAnalyzersOnTestApps": false,
  "rulesetFile": "custom.ruleset.json",
  "enableExternalRulesets": false
}

Setting	Description	Default
`enableCodeCop`	Enable CodeCop analyzer	`false`
`enableUICop`	Enable UICop analyzer	`false`
`customCodeCops`	URLs/paths to custom analyzers	`[]`
`enableCodeAnalyzersOnTestApps`	Run analyzers on test apps	`false`
`failOn`	Fail on: `none`, `error`, `warning`, `newWarning`	`error`
`trackALAlertsInGitHub`	Upload alerts to GitHub Security	`false`

Code Signing

{
  "trustedSigning": {
    "Account": "my-signing-account",
    "Endpoint": "https://weu.codesigning.azure.net",
    "CertificateProfile": "my-cert-profile"
  }
}

See Code Signing documentation for detailed setup instructions.

NuGet Feeds

{
  "trustMicrosoftNuGetFeeds": true,
  "nuGetFeedSelectMode": "LatestMatching",
  "trustedNuGetFeeds": [
    {
      "url": "https://nuget.pkg.github.com/myorg/index.json",
      "authTokenSecret": "NUGET_TOKEN",
      "patterns": ["MyCompany.*"],
      "fingerprints": ["ABCD1234..."]
    }
  ]
}

Setting	Description	Default
`trustMicrosoftNuGetFeeds`	Trust Microsoft NuGet feeds	`true`
`nuGetFeedSelectMode`	Package selection: `Earliest`, `EarliestMatching`, `Exact`, `Latest`, `LatestMatching`	`LatestMatching`
`trustedNuGetFeeds`	Array of custom NuGet feed configurations	`[]`

Performance and Caching

{
  "cacheImageName": "my",
  "cacheKeepDays": 3
}

When using incrementalBuilds, set workflowConcurrency to cancel in-progress builds on the same branch.

AL Compiler

{
  "vsixFile": "default",
  "useCompilerFolder": false
}

Setting	Description	Default
`vsixFile`	AL Language version: `default`, `latest`, `preview`, or URL	`default`
`useCompilerFolder`	Use containerless compilation	`false`

When using useCompilerFolder, you must use the new signing mechanism described in the Code Signing documentation.

Conditional Settings

Apply settings based on conditions:

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

Conditions available:

repositories - Repository name patterns
projects - Project name patterns
buildModes - Build mode names
branches - Branch name patterns
workflows - Workflow name patterns (see name sanitization)
users - Username patterns

Multiple conditional settings blocks can match. All matching settings are applied in order.

Workflow Name Sanitization

Workflow names are sanitized before matching:

Leading spaces removed
Invalid filename characters removed (quotes, colons, slashes, etc.)
Example: " CI/CD" becomes "CICD"

Workflow-Specific Settings

Some settings are only allowed in workflow-specific files or conditional settings:

{
  "workflowSchedule": {
    "cron": "0 2 * * 1",
    "includeBranches": ["main", "release/*"]
  }
}

Setting	Description
`workflowSchedule`	CRON schedule for workflow runs
`workflowConcurrency`	Concurrency control for workflows
`workflowDefaultInputs`	Default values for workflow inputs

Build your CRON expressions at crontab.guru. Run Update AL-Go System Files after changing schedules.

Secret Name Indirection

Many settings allow you to specify custom secret names:

{
  "licenseFileUrlSecretName": "MY_LICENSE",
  "ghTokenWorkflowSecretName": "MY_GH_TOKEN",
  "adminCenterApiCredentialsSecretName": "MY_ADMIN_CREDS",
  "applicationInsightsConnectionStringSecretName": "MY_APPINSIGHTS",
  "storageContextSecretName": "MY_STORAGE"
}

This pattern works for all secrets: <secretName>SecretName points to the actual secret name.

Next Steps

Secrets Reference

Learn about authentication and secret management

Workflows

Explore available workflows and their configuration

Scenarios

View common setup scenarios and use cases

Troubleshooting

Get help with common issues

Getting Started

Setup & Configuration

Core Workflows

Development

Deployment

AppSource Publishing

Advanced Topics

Migration

Settings Location Hierarchy

Basic Project Settings

Core Configuration

Testing Configuration

Dependencies

Preprocessor and Build Modes

AppSource-Specific Settings

Repository Settings

Environments and Deployment

Workflow Triggers

Supported Release Branch Formats

Advanced Settings

Artifacts and Versioning

Versioning Strategies

Code Analysis

Code Signing

NuGet Feeds

Performance and Caching

AL Compiler

Conditional Settings

Workflow Name Sanitization

Workflow-Specific Settings

Secret Name Indirection

Next Steps

Secrets Reference

Workflows

Scenarios

Troubleshooting

Build docs developers (and LLMs) love

Getting Started

Setup & Configuration

Core Workflows

Development

Deployment

AppSource Publishing

Advanced Topics

Migration

​Settings Location Hierarchy

​Basic Project Settings

​Core Configuration

​Testing Configuration

​Dependencies

​Preprocessor and Build Modes

​AppSource-Specific Settings

​Repository Settings

​Environments and Deployment

​Workflow Triggers

​Supported Release Branch Formats

​Advanced Settings

​Artifacts and Versioning

​Versioning Strategies

​Code Analysis

​Code Signing

​NuGet Feeds

​Performance and Caching

​AL Compiler

​Conditional Settings

​Workflow Name Sanitization

​Workflow-Specific Settings

​Secret Name Indirection

​Next Steps

Secrets Reference

Workflows

Scenarios

Troubleshooting

Build docs developers (and LLMs) love

Settings Location Hierarchy

Basic Project Settings

Core Configuration

Testing Configuration

Dependencies

Preprocessor and Build Modes

AppSource-Specific Settings

Repository Settings

Environments and Deployment

Workflow Triggers

Supported Release Branch Formats

Advanced Settings

Artifacts and Versioning

Versioning Strategies

Code Analysis

Code Signing

NuGet Feeds

Performance and Caching

AL Compiler

Conditional Settings

Workflow Name Sanitization

Workflow-Specific Settings

Secret Name Indirection

Next Steps