Basic Repository Settings

Basic repository settings are configured in .github/AL-Go-settings.json and apply to all projects in the repository. These settings control repository-wide behavior like project type, GitHub runners, and deployment environments.

Repository Type

type

string

default:"PTE"

Specifies the type of repository.Allowed values:

PTE - Per-Tenant Extension
AppSource App - AppSource application

This value comes with the default repository and affects which code cops are enabled by default.Example:

{
  "type": "AppSource App"
}

Project Configuration

projects

array

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 repository root for folders containing a .AL-Go folder with a settings.json file.Example:

{
  "projects": [
    "CoreApp",
    "Extensions/AdvancedFeatures"
  ]
}

useProjectDependencies

boolean

default:false

Determines whether projects are built using multi-stage or single-stage build workflows.When set to true:

Workflows will have multiple build jobs depending on project dependencies
Number of build jobs is determined by dependency depth
You need to run “Update AL-Go System Files” for changes to take effect

If the dependency depth changes, AL-Go will warn you that updates are available and you’ll need to run the “Update AL-Go System Files” workflow.

Example:

{
  "useProjectDependencies": true
}

Power Platform Integration

powerPlatformSolutionFolder

string

Contains the name of the folder containing a Power Platform Solution (only one supported).Example:

{
  "powerPlatformSolutionFolder": "PowerPlatform/MySolution"
}

Template Configuration

templateUrl

string

Defines the URL of the template repository used to create this repository.Used for checking and downloading updates to AL-Go System files.Example:

{
  "templateUrl": "https://github.com/microsoft/AL-Go-PTE@main"
}

GitHub Runners

runs-on

string

default:"windows-latest"

Specifies which GitHub runner is used for all non-build/test jobs in all workflows (except “Update AL-Go System Files”).After changing this setting, run “Update AL-Go System Files” for it to take effect.

Setting to ubuntu-latest runs non-build/test jobs on Linux. Build jobs still run on windows-latest (or your githubRunner setting).

Example:

{
  "runs-on": "ubuntu-latest"
}

githubRunner

string

default:"windows-latest"

Specifies which GitHub runner is used for build/test jobs in workflows.This is the most time-consuming task. Takes precedence over runs-on so you can use different runners for build jobs and housekeeping jobs.Example:

{
  "githubRunner": "windows-latest"
}

Environment and Deployment Settings

environments

array

default:[]

Array of logical environment names for deployment.Environments can be specified in GitHub environments or in the repo settings file. If specified in settings, create AUTHCONTEXT secret using <environmentname>_AUTHCONTEXT.Additional environment information can be specified in DeployTo<environmentname> settings.Example:

{
  "environments": [
    "Development",
    "QA",
    "Production"
  ]
}

DeployTo<environmentname>

object

Structure with additional properties for the specified environment. <environmentName> refers to the GitHub environment name.Properties:

EnvironmentType - Type of environment (default: SaaS)
EnvironmentName - “Real” name if different from GitHub environment
Branches - Array of branch patterns allowed to deploy
Projects - Comma-separated list of project patterns (default: *)
DependencyInstallMode - install/ignore/upgrade/forceUpgrade (default: install)
includeTestAppsInSandboxEnvironment - Deploy test apps if environment is sandbox (default: false)
excludeAppIds - Array of app IDs to exclude from deployment (default: [])
Scope - Dev or PTE deployment scope
SyncMode - Add/ForceSync/Development/Clean (default: Add)
BuildMode - Specifies which buildMode to use for deployment
ContinuousDeployment - Enable continuous deployment (default: false)
runs-on - GitHub runner for deployment (default: from general settings)
shell - Shell for deployment (default: from general settings)

Example:

{
  "DeployToProduction": {
    "EnvironmentType": "SaaS",
    "Branches": ["main"],
    "Projects": "*",
    "SyncMode": "Add",
    "ContinuousDeployment": false
  }
}

DeliverTo<deliveryTarget>

object

Structure with additional properties for the delivery target specified.Properties:

Branches - Array of branch patterns allowed to deliver (default: main)
CreateContainerIfNotExist - [Storage only] Create blob container if it doesn’t exist (default: false)

Example:

{
  "DeliverToStorage": {
    "Branches": ["main", "release/*"],
    "CreateContainerIfNotExist": true
  }
}

Workflow Triggers

CICDPushBranches

array

default:["main","release/*","feature/*"]

Array of branches that trigger a CI/CD workflow on commit.Run “Update AL-Go System Files” for changes to take effect.Supported release branch formats:

releases/26, releases/26.x, releases/26x, releases/v26, releases/v26.x, releases/v26x - matches major version 26
releases/26.3 - matches major.minor version 26.3
Also works with singular release/ prefix

Example:

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

CICDPullRequestBranches

array

default:["main"]

Array of branch patterns that trigger Pull Request Build when a PR targets them.Run “Update AL-Go System Files” for changes to take effect.Example:

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

pullRequestTrigger

string

default:"pull_request"

Specifies the trigger AL-Go uses for Pull Request Builds.

pull_request - Default, secrets not available for fork PRs
pull_request_target - Secrets available but has security implications

Run “Update AL-Go System Files” for changes to take effect.Example:

{
  "pullRequestTrigger": "pull_request"
}

Build Configuration

buildModes

array

default:["Default"]

List of build modes to use when building AL-Go projects. Every project is built using each build mode.Special build modes:

Default - Apps compiled as they are in source code
Clean - For Clean Mode (use conditional settings to specify preprocessorSymbols)
Translated - TranslationFile compiler feature is enabled

Custom build modes can be specified and configured using conditional settings.Example:

{
  "buildModes": [
    "Default",
    "Clean",
    "Translated"
  ]
}

fullBuildPatterns

array

default:[]

List of important files and folders. Changes to these trigger a full Pull Request build (all projects built).Examples:

[ "Build/*" ] - Changes to Build folder trigger full build
[ "*" ] - Any changes trigger full build (equivalent to alwaysBuildAllProjects: true)

Example:

{
  "fullBuildPatterns": [
    "Build/*",
    ".github/*",
    "*.json"
  ]
}

incrementalBuilds

object

Structure defining incremental build configuration. AL-Go looks for the latest successful CI/CD build newer than retentionDays and only rebuilds changed projects/apps.Properties:

onPush - Enable for CI/CD triggered by merge/push (default: false)
onPull_Request - Enable for Pull Requests (default: true)
onSchedule - Enable for scheduled CI/CD (default: false)
retentionDays - Days a successful build is valid (default: 30)
mode - modifiedProjects or modifiedApps

When using incremental builds, it’s recommended to also set workflowConcurrency for the CI/CD workflow.

Example:

{
  "incrementalBuilds": {
    "onPush": true,
    "onPull_Request": true,
    "onSchedule": false,
    "retentionDays": 30,
    "mode": "modifiedProjects"
  }
}

Git Submodules

useGitSubmodules

string

Set to "true" or "recursive" to use Git Submodules during build workflows.If submodules reside in private repositories, define a gitSubmodulesToken secret.Example:

{
  "useGitSubmodules": "recursive"
}

Commit and Pull Request Options

commitOptions

object

Controls how AL-Go creates pull requests or commits changes to the repository.Properties:

messageSuffix - String appended to commits/PRs (useful for Azure Boards integration)
createPullRequest - Boolean: create PR or push directly to branch
pullRequestAutoMerge - Boolean: auto-complete PRs when checks pass
pullRequestMergeMethod - “merge” or “squash” (default: squash)
pullRequestLabels - Array of labels to add to PR (must exist in repo)

Can be set in workflow-specific settings files for different behavior per workflow.Example:

{
  "commitOptions": {
    "messageSuffix": "AB#12345",
    "createPullRequest": true,
    "pullRequestAutoMerge": true,
    "pullRequestMergeMethod": "squash",
    "pullRequestLabels": ["automated", "al-go"]
  }
}

Reference Documentation

alDoc

object

Structure for ALDoc reference documentation generation.Properties:

continuousDeployment - Deploy reference docs continuously in CI/CD (default: false)
deployToGitHubPages - Deploy to GitHub Pages (default: true)
maxReleases - Maximum releases to include (default: 3)
groupByProject - Use projects as folders in multi-project repos
includeProjects - Array of projects to include (default: all)
excludeProjects - Array of projects to exclude (default: none)
header - Header for documentation site
footer - Footer for documentation site
defaultIndexMD - Markdown for landing page
defaultReleaseMD - Markdown for release sites

Placeholders: , , , Example:

{
  "alDoc": {
    "continuousDeployment": false,
    "deployToGitHubPages": true,
    "maxReleases": 5,
    "groupByProject": true,
    "header": "Documentation for {REPOSITORY}",
    "footer": "Made with ALDoc"
  }
}

Artifact Retention

shortLivedArtifactsRetentionDays

integer

default:1

Number of days to keep short-lived build artifacts (e.g., from pull request builds, next minor/major builds).Set to 0 to use GitHub default.Example:

{
  "shortLivedArtifactsRetentionDays": 7
}

Environment Exclusions

excludeEnvironments

array

default:[]

Array of GitHub Environments to exclude from deployment consideration.github-pages is automatically added and cannot be used for deployment.Example:

{
  "excludeEnvironments": [
    "test-environment",
    "deprecated-env"
  ]
}

Update AL-Go System Files

updateALGoSystemFilesEnvironment

string

Name of the environment holding the GhTokenWorkflow secret.Allows guarding “Update AL-Go System Files” with an approval workflow.Run “Update AL-Go System Files” (with GhTokenWorkflow in place globally) for this setting to take effect.Example:

{
  "updateALGoSystemFilesEnvironment": "ALGoSystemUpdates"
}

For project-level settings, see Basic Project Settings. For advanced configuration options, see Advanced Settings.

Configuration

Secrets Management

Repository Type

Project Configuration

Power Platform Integration

Template Configuration

GitHub Runners

Environment and Deployment Settings

Workflow Triggers

Build Configuration

Git Submodules

Commit and Pull Request Options

Reference Documentation

Artifact Retention

Environment Exclusions

Update AL-Go System Files

Build docs developers (and LLMs) love

Configuration

Secrets Management

​Repository Type

​Project Configuration

​Power Platform Integration

​Template Configuration

​GitHub Runners

​Environment and Deployment Settings

​Workflow Triggers

​Build Configuration

​Git Submodules

​Commit and Pull Request Options

​Reference Documentation

​Artifact Retention

​Environment Exclusions

​Update AL-Go System Files

​Related Settings

Build docs developers (and LLMs) love

Repository Type

Project Configuration

Power Platform Integration

Template Configuration

GitHub Runners

Environment and Deployment Settings

Workflow Triggers

Build Configuration

Git Submodules

Commit and Pull Request Options

Reference Documentation

Artifact Retention

Environment Exclusions

Update AL-Go System Files

Related Settings