Skip to main content
The Update AL-Go System Files workflow synchronizes your repository’s AL-Go system files with the latest version from the template repository. This ensures you benefit from bug fixes, new features, and improvements to the AL-Go framework.

​
Overview

AL-Go system files include:
  • Workflow files in .github/workflows/
  • System scripts in .AL-Go/
  • Helper scripts and configuration files
Keeping these files updated ensures:
  • Access to new AL-Go features
  • Bug fixes and security patches
  • Performance improvements
  • Compatibility with latest Business Central versions
The CI/CD workflow automatically checks for updates and notifies you when they’re available.

​
When to Update

​
Automatic Notifications

Every CI/CD run checks for updates. You’ll see a notification if updates are available: 
Updates are available for AL-Go System Files

​
Manual Checks

Run this workflow periodically to ensure you’re on the latest version, especially:
  • Before creating releases
  • When troubleshooting issues
  • After major AL-Go announcements
  • Monthly as part of maintenance

​
Prerequisites

This workflow requires the ghTokenWorkflow secret to create pull requests.

​
Setting Up ghTokenWorkflow

1

Create Personal Access Token

Generate a GitHub Personal Access Token (PAT):
  1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. Click Generate new token (classic)
  3. Name it AL-Go Workflow Token
  4. Select scopes:
    • repo (Full control of private repositories)
    • workflow (Update GitHub Action workflows)
  5. Click Generate token and copy the token
2

Add Secret to Repository

Add the PAT as a repository secret:
  1. Go to repository Settings → Secrets and variables → Actions
  2. Click New repository secret
  3. Name: ghTokenWorkflow
  4. Value: Paste your PAT
  5. Click Add secret
The ghTokenWorkflow secret allows the workflow to create pull requests that trigger other workflows. The default GITHUB_TOKEN cannot do this due to security restrictions.

​
Triggering the Workflow

​
Manual Trigger

1

Navigate to Actions

Go to your repository and click the Actions tab.
2

Select Update AL-Go System Files

Click on Update AL-Go System Files in the workflows list.
3

Run Workflow

Click Run workflow and configure the parameters.

​
Automatic Trigger via Workflow Call

The workflow can be called from other workflows: 
jobs:
  update-system-files:
    uses: ./.github/workflows/UpdateGitHubGoSystemFiles.yaml
    with:
      downloadLatest: true
      directCommit: false

​
Workflow Parameters

​
templateUrl
string
Template Repository URLOverride the default template repository URL.
  • Leave empty to use the URL from AL-Go settings
  • Specify {owner}/{repo}@{branch} to use a different template
Example: microsoft/AL-Go-PTE@mainDefault: Uses templateUrl from .github/AL-Go-Settings.json
​
downloadLatest
boolean
default:"true"
Download latest from template repositoryWhen true, downloads the latest version from the template. When false, uses a previously cached version.Example: true
​
directCommit
boolean
default:"false"
Direct Commit?Controls how updates are applied:
  • false: Creates a pull request (recommended)
  • true: Commits directly to the branch
Direct commit bypasses code review. Use pull requests for transparency and testing.
Example: false
​
includeBranches
string
Branches to updateComma-separated list of branches to update. Supports wildcards.
  • Leave empty to update current branch only
  • main,release/*: Update main and all release branches
  • *: Update all branches (use with caution)
Example: main,release/*Default: Current branch only

​
Workflow Jobs

1

Initialize

Determines which branches to update and which template to use.Actions Performed:
  • Reads AL-Go settings to get the template URL
  • Resolves branch patterns to actual branch names
  • Determines the template URL (from input or settings)
  • Validates configuration
Branch Resolution:
  • includeBranches parameter is expanded
  • Wildcards like release/* match all release branches
  • Each matched branch gets its own update job
2

Update AL-Go System Files (per branch)

Updates system files for each branch.Update Process:
  1. Checkout: Checks out the target branch
  2. Read Settings: Reads branch-specific AL-Go settings
  3. Read Secrets: Retrieves ghTokenWorkflow secret
  4. Download Template: Downloads latest from template repository
  5. Compare Files: Identifies differences
  6. Update Files: Updates system files
  7. Create PR or Commit: Either creates a pull request or commits directly
File Comparison: The workflow:
  • Compares your files with template files
  • Identifies new, updated, and removed files
  • Preserves your custom changes to non-system files
  • Warns about local modifications to system files
3

Finalize

Completes the workflow and reports telemetry.Always runs to ensure proper cleanup.

​
What Gets Updated

​
System Files

The workflow updates these files:

Workflow Files

Location: .github/workflows/
  • CICD.yaml
  • CreateRelease.yaml
  • PullRequestHandler.yaml
  • PublishToEnvironment.yaml
  • UpdateGitHubGoSystemFiles.yaml
  • All other workflow files from template

System Scripts

Location: .AL-Go/
  • Helper scripts
  • Configuration templates
  • Action implementations

​
Files NOT Updated

These files are never modified:
  • Your AL application code
  • AL-Go-Settings.json (only structure may be validated)
  • Custom workflow files you’ve added
  • Project-specific configuration files
  • Repository secrets and settings
If you’ve modified system files, the workflow will warn you and may revert your changes. Keep customizations in separate files when possible.

​
Update Pull Request

When directCommit is false (recommended), the workflow creates a pull request:

​
PR Contents

  • Title: Update AL-Go System Files
  • Description: Summary of changes from the template
  • Changes: All updated system files
  • Branch: update-al-go-system-files/{timestamp} or similar

​
Reviewing the PR

1

Review Changes

Examine the changes to understand what’s being updated:
  • New features or improvements
  • Bug fixes
  • Configuration changes
  • Removed deprecated files
2

Check for Conflicts

If you’ve customized system files, ensure the update doesn’t break functionality.
3

Test the Changes

The PR build workflow will run automatically. Verify it passes.
4

Merge the PR

Once satisfied, merge the pull request to apply the updates.
If the PR shows that your custom changes to system files are being reverted, consider whether those customizations are still necessary or if they can be achieved differently.

​
Multi-Branch Updates

Update multiple branches simultaneously:

​
Example: Update Main and Release Branches

1

Run Workflow

Set parameters:
  • templateUrl: (leave empty)
  • downloadLatest: true
  • directCommit: false
  • includeBranches: main,release/*
2

Review PRs

A pull request is created for each branch.
3

Merge PRs

Review and merge each PR individually.
Each branch is updated independently, allowing you to test updates on release branches before applying to main.

​
Template Repositories

AL-Go supports two template types:

Per-Tenant Extension

Template: microsoft/AL-Go-PTEFor Business Central Per-Tenant Extensions with optional PowerPlatform integration.

AppSource App

Template: microsoft/AL-Go-AppSourceFor Business Central AppSource apps with AppSource submission workflows.

​
Using a Custom Template

You can fork the AL-Go template and use your custom version:
  1. Fork the template repository
  2. Update AL-Go-Settings.json: 
    {
  "templateUrl": "https://github.com/myorg/my-al-go-template@main"
}
  3. Run the update workflow to sync with your custom template
Custom templates require maintenance. You’ll need to periodically merge updates from the official template.

​
Handling Modified System Files

If you’ve modified AL-Go system files:

​
The Problem

AL-Go doesn’t support modifications to system files and will:
  • Detect the modifications
  • Warn about them in CI/CD runs
  • Revert them when updating

​
The Solution

1

Extract Customizations

Identify what you’ve customized and why.
2

Use AL-Go Settings

Move configuration to .github/AL-Go-Settings.json when possible:
{
  "githubRunner": "ubuntu-latest",
  "runs-on": "[ self-hosted, linux ]"
}
3

Create Custom Workflows

For workflow customizations, create separate workflow files that call the system workflows.
4

Use Composite Actions

Encapsulate custom logic in composite actions in your repository.
If you absolutely need custom behavior, fork the template repository and maintain your own template.

​
Commit Options

The workflow respects commitOptions in AL-Go settings: 
{
  "commitOptions": {
    "createPullRequest": true,
    "pullRequestTitle": "Update AL-Go System Files",
    "pullRequestBody": "Automated update from template repository"
  }
}

​
Troubleshooting

ghTokenWorkflow Not Found

Ensure the secret is created with workflow scope. Check that it’s not expired.

Update Fails with Conflicts

Your system files may have custom changes. Review the conflicts and decide whether to keep or remove customizations.

PR Not Created

Verify ghTokenWorkflow secret exists and directCommit is false. Check workflow permissions.

No Updates Found

You’re already on the latest version. No action needed.

​
Update Frequency

Production Repositories

Monthly or when notified of critical updatesBalance stability with new features.

Development Repositories

Weekly or after each AL-Go releaseStay current with latest features.

​
Monitoring Updates

  • Watch the AL-Go repository for releases
  • Check CI/CD workflow outputs for update notifications
  • Review AL-Go release notes for breaking changes

​
Best Practices

1

Use Pull Requests

Always use pull requests (not direct commit) to review changes before applying.
2

Test After Updating

Run your CI/CD workflow after updating to ensure compatibility.
3

Update Dependencies Together

If updating multiple branches, update them at the same time for consistency.
4

Read Release Notes

Review AL-Go release notes to understand what changed.
5

Avoid Modifying System Files

Use AL-Go settings and custom workflows instead of modifying system files.
6

Keep ghTokenWorkflow Secure

Treat this secret as highly sensitive. Rotate it regularly.

​
Example Scenarios

​
Scenario 1: Regular Monthly Update

1

Check for Updates

Review the latest CI/CD run for update notifications.
2

Run Update Workflow

  • templateUrl: (empty)
  • downloadLatest: true
  • directCommit: false
  • includeBranches: main
3

Review and Merge PR

Review changes, run tests, and merge.

​
Scenario 2: Update All Branches

1

Run Update Workflow

  • templateUrl: (empty)
  • downloadLatest: true
  • directCommit: false
  • includeBranches: main,release/*,feature/*
2

Review PRs

Review each PR individually.
3

Merge Strategically

Merge to feature branches first, then release, then main.

​
Scenario 3: Switch Templates

1

Update Settings

Change templateUrl in .github/AL-Go-Settings.json:
{
  "templateUrl": "https://github.com/myorg/my-template@main"
}
2

Run Update Workflow

  • templateUrl: (empty, uses new setting)
  • downloadLatest: true
  • directCommit: false
  • includeBranches: (empty)
3

Review Major Changes

The PR will show all differences between templates.

​
Advanced: Workflow Integration

Call the update workflow from other workflows: 
name: Weekly Maintenance

on:
  schedule:
    - cron: '0 0 * * 0' # Every Sunday

jobs:
  update-system-files:
    uses: ./.github/workflows/UpdateGitHubGoSystemFiles.yaml
    secrets: inherit
    with:
      downloadLatest: true
      directCommit: false
This automatically creates update PRs weekly.
Automated updates help you stay current, but always review PRs before merging.

Build docs developers (and LLMs) love

Get started for freeTalk to us