Skip to main content
AL-Go for GitHub is a plug-and-play DevOps solution designed to support 100% of the functionality needed by 90% of developers working with Microsoft Dynamics 365 Business Central out-of-the-box.
Before customizing AL-Go, consider creating a feature suggestion to see if your needs can be met through existing mechanisms or if they should become part of the core AL-Go solution.

​
Customization Options

If AL-Go’s out-of-the-box functionality doesn’t meet your needs, you have three options:
  1. Customize AL-Go for GitHub - Modify your repository following the guidelines below
  2. Select another managed DevOps solution - Use an alternative platform
  3. Create your own DevOps solution from scratch - Not recommended due to the significant development and maintenance overhead
The more you customize AL-Go for GitHub, the more likely you are to be affected by future updates. You may need to update your customizations to match changes in AL-Go.

​
Customization Methods

There are three primary ways to customize AL-Go for GitHub:

Repository Customization

Add custom scripts, workflows, or jobs to individual repositories

Custom Template Repository

Create a customized template for use across multiple repositories

Fork AL-Go

Fork the AL-Go repository to create your own version (not recommended)

​
Repository Customization

​
Hide/Remove Unused Workflows

You can remove unused system files by adding the unusedALGoSystemFiles setting to your .github/AL-Go-Settings.json: 
{
  "unusedALGoSystemFiles": [
    "AddExistingAppOrTestApp.yaml",
    "CreateApp.yaml",
    "CreatePerformanceTestApp.yaml",
    "CreateTestApp.yaml",
    "cloudDevEnv.ps1"
  ]
}
Be careful not to remove critical files like _BuildALGoProject.yaml, as this will break AL-Go functionality.

​
Custom Delivery

1

Create Delivery Script

Add a PowerShell script at .github/DeliverTo<DeliveryTarget>.ps1:
Param([Hashtable] $parameters)

Get-ChildItem -Path $parameters.appsFolder | Out-Host
$context = $parameters.context | ConvertFrom-Json
Write-Host "Token Length: $($context.Token.Length)"
2

Create Context Secret

Add a context secret named <DeliveryTarget>Context containing your delivery configuration as compressed JSON.
3

Configure Settings

Update your AL-Go settings to reference the custom delivery target.
See the custom delivery documentation for more information.

​
Custom Deployment

Setup custom deployment to environment types not supported out-of-the-box: 
{
  "Environments": [
    "<EnvironmentName>"
  ],
  "DeployTo<EnvironmentName>": {
    "EnvironmentType": "<EnvironmentType>"
  }
}
Create the deployment script at .github/DeployTo<EnvironmentType>.ps1: 
Param([Hashtable] $parameters)

$parameters | ConvertTo-Json -Depth 99 | Out-Host
$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
Get-ChildItem -Path $tempPath -Filter *.app | Out-Host
$authContext = $parameters.authContext | ConvertFrom-Json
Write-Host "Token Length: $($authContext.Token.Length)"

​
Adding Custom Workflows

Custom workflows added to .github/workflows/ are left untouched by AL-Go updates: 
name: 'Create Build Tag'

on:
  workflow_run:
    workflows: [' CI/CD','CI/CD']
    types: [completed]
    branches: [ 'main' ]

run-name: "[${{ github.ref_name }}] Create build tag"

permissions: read-all

jobs:
  CreateTag:
    if: github.event.workflow_run.conclusion == 'success'
    runs-on: windows-latest
    steps:
      - name: mystep
        run: |
          Write-Host "Create tag"
Prefix your custom workflows with my, our, or your organization name to avoid conflicts with future AL-Go workflows.

​
Adding Custom Scripts

Add PowerShell scripts to customize AL-Go behavior:
  • Repository-scoped scripts: .github/ folder
  • Project-scoped scripts: .AL-Go/ folder
Specially named scripts in the .AL-Go folder can override standard functionality. See the script overrides documentation for available overrides. Example override script: 
Param([Hashtable] $parameters)

$script = Join-Path $PSScriptRoot "../../../scripts/NewBcContainer.ps1" -Resolve
. $script -parameters $parameters
Script overrides may break in future AL-Go versions, especially when the underlying implementation changes from BcContainerHelper to GitHub actions.

​
Adding Custom Jobs

Add custom jobs to existing AL-Go workflows by prefixing them with CustomJob: 
CustomJob-CreateBuildTag:
  name: Create Build Tag
  needs: [ Initialization, Build ]
  if: (!cancelled()) && (needs.Build.result == 'success')
  runs-on: [ ubuntu-latest ]
  steps:
    - name: Create Tag
      run: |
        Write-Host "Create Tag"

PostProcess:
  needs: [ Initialization, Build2, Build1, Build, Deploy, Deliver, DeployALDoc, CustomJob-CreateBuildTag ]
  if: (!cancelled())
  runs-on: [ windows-latest ]
  steps:
    ...
Custom jobs are moved to the end of the workflow file during updates, but dependencies are maintained.

​
Custom Template Repositories

For customizations across multiple repositories, create a custom template repository:
1

Create Custom Template

Start with an AL-Go repository (PTE or AppSource template) and apply your customizations.
2

Set as Template

Mark the repository as a template in GitHub settings.
3

Configure Repositories

Point your repositories to the custom template by:
  • Creating a repository from the official AL-Go template
  • Adding a GhTokenWorkflow secret
  • Running “Update AL-Go System Files” with your custom template URL
Keep your custom template repository up-to-date with the latest AL-Go for GitHub changes to avoid compatibility issues.
Private custom templates are supported. AL-Go uses the GhTokenWorkflow secret to access private template repositories.

​
Custom Template Files

Control which files sync from your template using the customALGoFiles setting: 
{
  "customALGoFiles": {
    "filesToInclude": [
      {
        "sourceFolder": ".github/customScripts",
        "filter": "*.ps1",
        "destinationFolder": ".AL-Go/scripts",
        "perProject": true
      }
    ],
    "filesToExclude": [
      {
        "sourceFolder": ".github/customScripts",
        "filter": "DoNotPropagate.ps1"
      }
    ]
  }
}

​
File Configuration Properties

filesToInclude:
  • sourceFolder - Path in template (relative to root)
  • filter - File pattern with wildcards (*.ps1, file.ps1)
  • destinationFolder - Target path in repository
  • perProject - Boolean; if true, applies to all AL-Go projects
filesToExclude:
  • sourceFolder - Path in template
  • filter - File pattern to exclude

​
File Sync Behavior

File in RepoIn filesToIncludeIn filesToExcludeResult
Yes/NoYesNoFile is created/updated
YesYesYesFile is removed
YesNoYesFile is not removed
NoYes/NoYesFile is not created

​
Forking AL-Go for GitHub

Forking AL-Go gives maximum customization but requires the most maintenance. Customizations in public forks are visible to everyone.
You can fork either:
  1. Template repositories (AL-Go-PTE or AL-Go-AppSource) - Simpler but limited
  2. Main AL-Go repository (AL-Go) - Full development capabilities
When forking template repositories, include all branches to access both latest and preview versions of AL-Go.

​
Fork Maintenance

If you fork AL-Go:
  • Keep changes minimal
  • Stay up-to-date with upstream changes
  • Regularly merge Microsoft’s updates
  • Consider contributing your changes back to AL-Go
Microsoft continuously develops and maintains AL-Go, ensuring the latest GitHub action versions and avoiding third-party dependencies. Staying on the mainstream version helps you benefit from these updates.

​
Update Management

AL-Go repositories can be updated manually or on a schedule:
  • You’ll be notified when updates are available
  • Keep repositories up-to-date at all times
  • Manual modifications to AL-Go System Files (except as documented) will be removed during updates
If an AL-Go update causes issues, file an issue on GitHub with detailed logs, then revert to the previous version until resolved.

Build docs developers (and LLMs) love

Get started for freeTalk to us