Getting started with AL-Go! for GitHub

In this video, I take a first look at AL-Go! for GitHub, and set up my first app. Check it out:

https://youtu.be/XoXGbcUxw-c

In this video, Erik walks through the process of getting started with AL-Go for GitHub — a template-based approach from Microsoft for setting up a complete CI/CD pipeline for Business Central AL extensions using GitHub Actions. He covers creating a repository from the template, generating a new app, cloning it into VS Code, publishing it locally, and watching the automated build pipeline run on GitHub.

What is AL-Go for GitHub?

Starting with Business Central version 21, Microsoft introduced AL-Go for GitHub. If you’re familiar with the AL command in VS Code (used to scaffold new extension projects), AL-Go extends that concept by connecting your project to GitHub with a full CI/CD pipeline out of the box — automated builds, deployments, and more.

Step 1: Create a Repository from the Template

Everything starts on GitHub. Navigate to the AL-Go template repository:

github.com/microsoft/al-go-pte

This is a GitHub template repository specifically designed for managing a per-tenant extension (PTE) for Business Central. To use it:

  1. Make sure you’re logged into your GitHub account
  2. Click “Use this template”
  3. Give your new repository a name (e.g., al-go-for-github-testing)
  4. Set it to Private

Important security tip: Always start with a private repository until you’re sure the content is ready for public consumption. There are bots that constantly scan new public repositories looking for Azure keys, AWS keys, passwords, and other secrets. Start private, then make it public later if needed.

Step 2: Create a New App via GitHub Actions

Once the repository is generated, navigate to the Actions tab. You’ll find several pre-configured workflow actions. The one you want is “Create a new app”.

Run the workflow and fill in the required fields:

  • Project name: Your app name (e.g., “al-go-github-baby”)
  • Publisher: Your publisher name
  • ID range: Your assigned ID range (e.g., 95690 to 95780)
  • Include sample code: Yes
  • Direct commit: Yes

Click “Run workflow” and wait about a minute for it to complete. Once done, you’ll see your new app folder in the repository’s code view, complete with a Hello World sample and all the necessary project files.

Step 3: Clone into VS Code

Copy the repository URL from GitHub, then in VS Code:

  1. Run the Git: Clone command
  2. Paste the repository URL
  3. Select a local folder
  4. Open the cloned repository when prompted
  5. Open the workspace file when VS Code asks

Step 4: Set Up Your Development Environment

At this point, you have three choices for a development environment:

  • Local Dev Environment — Creates a Docker container for you (via a provided PowerShell command)
  • Cloud Dev Environment — Creates a cloud-based environment for building apps
  • Use an existing environment — If you already have a Business Central instance running

Erik opts for option three, using his existing Docker container. To do this, open the launch.json file inside your app folder and add a configuration pointing to your server:

{
  "type": "al",
  "request": "launch",
  "name": "Publish to my own server",
  "server": "http://bc21",
  "serverInstance": "BC",
  "authentication": "UserPassword"
}

Understanding the Workspace Structure

The AL-Go template uses a workspace structure, which means you can have multiple apps open simultaneously. The AL compiler in VS Code needs to know which app you’re currently working with — it determines this based on which file you have open. So make sure you have a file from your target app open (e.g., HelloWorld.al) before running commands like Download Symbols.

Step 5: Fix the Runtime Version

Erik runs into a common gotcha here: the app.json file generated by AL-Go may reference a runtime version that hasn’t been released yet. In his case, the AL extension was targeting runtime 10.1, but only 10.0 (Business Central version 21) was released.

The fix is to add or update the runtime setting in app.json to match your installed version:

{
  "runtime": "10.0"
}

Without the correct runtime setting, you’ll get errors when trying to publish. You might also encounter issues where the app specifies an application version that allows downloading symbols from a newer version while the runtime targets an older one — potentially using system application features that don’t exist in the older runtime.

Step 6: Commit and Watch the Pipeline

After making your changes (updating HelloWorld.al, adding the launch configuration, and fixing the runtime in app.json), commit and push to GitHub. As soon as the push hits the repository, an automated build pipeline is triggered.

Navigate to the Actions tab on GitHub to watch the pipeline in action. The workflow goes through several stages:

  1. Initialization
  2. Check for updates
  3. Build — This is where the heavy lifting happens:
    • Checking container helper version
    • Creating a build container
    • Resolving dependencies
    • Compiling the app
    • Publishing the app
    • Copying build artifacts
    • Removing the container
  4. Deliver and Deploy
  5. Post Process

You may see some warnings about deprecated set-output commands and Node.js 12 actions — these are GitHub Actions platform deprecations that will be addressed in future updates to the template.

Comparing to Custom Build Pipelines

For context, here’s an example of a custom build configuration (using Erik’s ALBuild tool) that achieves similar goals but with a completely manual setup:

{
  "Project": "Point of Sale",
  "Report": "Email",
  "ReportDestination": "erik@hougaard.com",
  "Tasks": [
    {
      "Type": "DeployBasicDocker",
      "Settings": {
        "AppFile": "c:\\projects\\albuild\\testrunner\\Hougaard_ALBuild TestRunner_1.0.0.0.app",
        "BaseURL": "http://bc20:7049/BC/",
        "User": "demo",
        "Password": "demo",
        "SchemaUpdateMode": "forcesync"
      }
    },
    {
      "Type": "Git",
      "Settings": {
        "Path": "c:\\projects\\youtube\\point of sale",
        "Command": "pull"
      }
    },
    {
      "Type": "UpdateVersion",
      "Settings": {
        "AppPath": "c:\\projects\\youtube\\point of sale",
        "VersionPartToIncrement": 4,
        "Increment": 1,
        "DateInVersionPartNo": 3
      }
    },
    {
      "Type": "DownloadSymbolsDocker",
      "Settings": {
        "AppPath": "%APPPATH%",
        "BaseURL": "http://bc20:7049/BC/",
        "User": "demo",
        "Password": "demo"
      }
    },
    {
      "Type": "Compile",
      "Settings": {
        "AppPath": "%APPPATH%"
      }
    },
    {
      "Type": "Copy",
      "Settings": {
        "From": "%APPPATH%\\%PUBLISHER%_%NAME%_%VERSION%.app",
        "To": "C:\\Projects\\youtube\\ALbuild\\Release\\%PUBLISHER%_%NAME%_%VERSION%.app"
      }
    },
    {
      "Type": "Git",
      "Settings": {
        "Path": "%APPPATH%",
        "Command": "commit -a -m \"ALBuild Version %VERSION%\""
      }
    },
    {
      "Type": "Git",
      "Settings": {
        "Path": "%APPPATH%",
        "Command": "push"
      }
    }
  ]
}

This custom pipeline handles git pulls, version incrementing, symbol downloads, compilation, translation, artifact copying, and git commits/pushes — all tasks that AL-Go for GitHub handles automatically through its GitHub Actions workflows. The difference is that AL-Go gives you all of this with essentially zero configuration.

Where to Learn More

The full documentation and all available scenarios are found at github.com/microsoft/al-go. The README covers numerous user scenarios beyond what was demonstrated here:

  • Adding a test app
  • Registering customer sandbox environments for continuous deployment
  • Setting up service authentication
  • Creating a release of your application
  • Registering a customer production environment for manual deployment
  • Updating AL-Go system files
  • Managing secrets with KeyVault

Each scenario is well documented in the repository.

Summary

Getting started with AL-Go for GitHub is surprisingly straightforward — far less scary than you might expect. In just a few minutes, you can go from zero to a fully functional CI/CD pipeline for your Business Central extension. The key steps are: create a repo from the template, run the “Create a new app” action, clone it locally, fix the runtime version if needed, and push your changes to trigger automated builds. From there, the possibilities expand into multi-app projects, automated deployments, release management, and more.

Picture of hougaard

hougaard