Skip to main content
The Create Release workflow packages your Business Central applications into versioned releases, complete with release notes, artifacts, and optional version number updates.

​
Overview

This workflow creates a GitHub release from a successful build, allowing you to:
  • Tag specific versions of your applications
  • Generate release notes automatically from commits
  • Publish artifacts to the release
  • Create release branches for hotfix support
  • Update version numbers in the main branch
  • Deliver to external targets (NuGet, Storage)

​
Triggering the Workflow

The Create Release workflow must be triggered manually.
1

Navigate to Actions

Go to your repository on GitHub and click the Actions tab.
2

Select Create Release

Click on Create release in the workflows list.
3

Run Workflow

Click Run workflow and fill in the required parameters.

​
Workflow Parameters

​
Required Parameters

​
name
string
required
Name of this releaseThe display name for the release (e.g., “Version 1.0”, “Spring 2024 Release”).Example: v1.0
​
tag
string
required
Tag of this releaseMust be a semantic version string following semver.org (e.g., 1.0.0, 2.1.3-beta).Example: 1.0.0

​
Optional Parameters

​
buildVersion
string
default:"latest"
Build version to promoteWhich build to promote to a release:
  • latest: Most recent successful build
  • 1234: Specific workflow run ID
  • Version number from a previous release
Example: latest
​
releaseType
choice
default:"Release"
Release typeOptions:
  • Release: Public, production-ready release
  • Prerelease: Beta or preview release
  • Draft: Unpublished draft for review
Example: Release
​
createReleaseBranch
boolean
default:"false"
Create Release Branch?Creates a branch from the release commit to enable hotfixes.Example: true
​
releaseBranchPrefix
string
default:"release/"
Release branch prefixPrefix for the release branch name (e.g., release/ creates release/1.0.0).Example: release/
​
updateVersionNumber
string
New Version Number in main branchHow to update the version after release:
  • Absolute: 2.0 (sets to version 2.0)
  • Incremental: +0.1 (adds 0.1 to current version)
  • Incremental: +1 (increments major version)
Example: +0.1
​
skipUpdatingDependencies
boolean
default:"false"
Skip updating dependency version numbersWhen true, only updates the version in the main app, not in dependent apps.Example: false
​
directCommit
boolean
default:"false"
Direct Commit?When true, commits version updates directly to main. When false, creates a pull request.Example: false
​
useGhTokenWorkflow
boolean
default:"false"
Use GhTokenWorkflow for PR/Commit?Use the ghTokenWorkflow secret instead of the default token. Required for triggering subsequent workflows.Example: false

​
Workflow Jobs

1

Create Release

The main job that creates the GitHub release.Actions Performed:
  1. Validates workflow inputs (tag format, version numbers)
  2. Checks for AL-Go system file updates
  3. Determines which artifacts to include
  4. Generates release notes from commit history
  5. Creates the GitHub release
  6. Tags the commit with the release version
Release Notes Generation:
  • Includes all commits since the last release
  • Lists new contributors
  • Adds link to full changelog
  • Formatted in Markdown
The release is created at the commit specified by the build version, ensuring reproducibility.
2

Upload Artifacts

Downloads and uploads artifacts to the release.Artifact Types:
  • Apps: Compiled .app files
  • Test Apps: Test application packages
  • Dependencies: Dependency app files
  • PowerPlatform: PowerPlatform solution files (if applicable)
Each artifact is:
  1. Downloaded from the build workflow run
  2. Zipped with a descriptive name
  3. Uploaded to the GitHub release
Delivery Targets: If configured, artifacts are also delivered to:
  • NuGet: As NuGet packages
  • Storage: Azure Blob Storage or similar
3

Create Release Branch

Optionally creates a release branch for hotfix support.Branch Creation:
  • Branch name: {releaseBranchPrefix}{releaseVersion}
  • Example: release/1.0.0
  • Created from the release commit
  • Allows hotfix development without affecting main
Release branches are useful for maintaining multiple versions simultaneously.
4

Update Version Number

Optionally updates version numbers in the main branch.Version Update Process:
  1. Increments version in app.json files
  2. Updates dependencies between apps (unless skipped)
  3. Either commits directly or creates a pull request
  4. Uses IncrementVersionNumber AL-Go action
It’s recommended to update the version number after each release to avoid version conflicts.
5

Post-Process

Finalizes the workflow and reports telemetry.Always runs to ensure cleanup, even if previous jobs fail.

​
Example: Creating Your First Release

1

Prerequisites

Ensure you have:
  • At least one successful CI/CD build
  • Proper permissions to create releases
  • ghTokenWorkflow secret (if using pull requests for version updates)
2

Run the Workflow

Navigate to Actions → Create release → Run workflowFill in the parameters:
  • name: v1.0
  • tag: 1.0.0
  • buildVersion: latest
  • releaseType: Release
  • updateVersionNumber: +0.1
3

Wait for Completion

The workflow will:
  1. Create the release
  2. Upload artifacts
  3. Create a version update PR
4

Review and Merge PR

Review the version update pull request and merge it to update the main branch version.
After merging the version update PR, the CI/CD workflow will automatically run and may deploy to environments.

​
Release Notes

Release notes are automatically generated and include:
  • Summary: Description of changes since last release
  • What’s Changed: List of commits with links
  • New Contributors: First-time contributors
  • Full Changelog: Link to compare view

​
Customizing Release Notes

After the release is created, you can edit it:
  1. Go to the Releases page
  2. Click Edit on your release
  3. Modify the description
  4. Save changes
Consider adding upgrade notes, breaking changes, and migration guides to release notes.

​
Release Artifacts

Each release includes downloadable artifacts:

Application Files

-Apps-.zipContains all .app files for the release.

Test Applications

-TestApps-.zipTest apps for validation and testing.

Dependencies

-Dependencies-.zipAll dependency apps required for installation.

Source Code

Source code (zip/tar.gz)Automatically generated by GitHub.

​
Version Number Updates

​
Understanding Version Increments

AL-Go supports flexible version number updates:
InputCurrent VersionNew VersionDescription
+11.0.0.02.0.0.0Increment major
+0.11.0.0.01.1.0.0Increment minor
2.01.0.0.02.0.0.0Set absolute version
3.51.2.0.03.5.0.0Set absolute version

​
Version Strategy

Configure versioning strategy in .github/AL-Go-Settings.json: 
{
  "versioningStrategy": 2
}
Strategies:
  • 0: Major.Minor (e.g., 1.0)
  • 1: Major.Minor.Build (e.g., 1.0.0)
  • 2: Major.Minor.Build.Revision (e.g., 1.0.0.0)
  • 3: Use all four version fields independently

​
Delivery Targets

​
NuGet Delivery

To deliver releases to NuGet:
  1. Configure NuGet Context Secret: Secret name: nuGetContext Secret value: 
    {
  "serverUrl": "https://api.nuget.org/v3/index.json",
  "token": "your-nuget-api-key"
}
  2. Artifacts are automatically packaged as NuGet packages and pushed

​
Storage Delivery

To deliver releases to Azure Storage:
  1. Configure Storage Context Secret: Secret name: storageContext Secret value: 
    {
  "storageAccountName": "mystorageaccount",
  "containerName": "releases",
  "sasToken": "your-sas-token"
}
  2. Artifacts are uploaded to the specified container

​
Release Branches and Hotfixes

Release branches enable hotfix workflows:
1

Create Release with Branch

When creating a release, check Create Release Branch?
2

Develop Hotfix

Create a hotfix branch from the release branch:
git checkout release/1.0.0
git checkout -b hotfix/1.0.1
3

Create Hotfix Release

Run Create Release again:
  • buildVersion: Use the hotfix build
  • tag: 1.0.1
  • name: v1.0.1 Hotfix
4

Merge Back

Merge the hotfix back to main and the release branch.

​
Required Secrets

TokenForPush

Purpose: Create releases and push tagsType: Personal Access Token with repo scopeUsed for creating GitHub releases.

ghTokenWorkflow

Purpose: Trigger subsequent workflowsType: Personal Access Token with workflow scopeRequired when useGhTokenWorkflow is true.

nuGetContext

Purpose: Deliver to NuGetType: JSON with NuGet server URL and API keyOptional, for NuGet delivery.

storageContext

Purpose: Deliver to StorageType: JSON with storage account detailsOptional, for Storage delivery.

​
Troubleshooting

Tag Already Exists

Choose a different tag name. Git tags must be unique. Delete the old tag if necessary.

No Artifacts Found

Ensure the build version exists and completed successfully. Check the workflow runs.

Version Update Fails

Verify the version number format. Use +0.1 for incremental or 2.0 for absolute versions.

PR Not Created

Ensure ghTokenWorkflow secret is configured. The default token cannot trigger workflows.

​
Best Practices

1

Use Semantic Versioning

Follow semver.org for version tags: MAJOR.MINOR.PATCH
2

Always Update Version

After each release, increment the version in main to avoid conflicts.
3

Create Release Branches for Production

Enable hotfix support by creating release branches for production releases.
4

Use Prereleases for Testing

Mark releases as “Prerelease” during testing phases.
5

Document Breaking Changes

Edit release notes to highlight breaking changes and migration steps.

Build docs developers (and LLMs) love

Get started for freeTalk to us