From 92f935a726a3ba209e7f85d5dffeb5ef69172b3d Mon Sep 17 00:00:00 2001 From: Jeffrey Bulanadi Date: Tue, 21 Apr 2026 20:11:47 +0800 Subject: [PATCH 1/2] docs: clarify versioningStrategy 0 uses current workflow run_number Strategy 0 documentation stated the build number is the run_number 'for the CI/CD workflow'. In practice, \ resolves to the run_number of the currently executing workflow -- which is the CI/CD workflow when CI/CD triggers the build, but is the Test Next Major, Test Next Minor, or other workflow's own run_number when those workflows trigger a build instead. Add an explicit note in the strategy 0 description and update the runNumberOffset setting description to say 'current workflow run' rather than 'CI/CD workflow', so users are not surprised when non-CI/CD builds produce a version number based on a different run_number sequence. Fixes #2155 --- Scenarios/settings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Scenarios/settings.md b/Scenarios/settings.md index 6a54b92c4..861e40267 100644 --- a/Scenarios/settings.md +++ b/Scenarios/settings.md @@ -97,7 +97,7 @@ The repository settings are only read from the repository settings file (.github | updateDependencies | Setting updateDependencies to true causes AL-Go to build your app against the first compatible Business Central build and set the dependency version numbers in the app.json accordingly during build. All version numbers in the built app will be set to the version number used during compilation.
⚠️ **Warning:** When the `updateDependencies` setting is enabled, the application versions from the BC Artifact are stamped into the `app.json`. However, not all app versions available in BC Artifacts are shipped in BC SaaS, which can lead to dependency resolution failures during AppSource validation. Therefore, it is not recommended to use this setting if you intend on deploying the build to AppSource. | false | | generateDependencyArtifact | When this repository setting is true, CI/CD pipeline generates an artifact with the external dependencies used for building the apps in this repo. | false | | companyName | Company name selected in the database, used for running the CI/CD workflow. Default is to use the default company in the selected Business Central localization. | | -| versioningStrategy | The versioning strategy determines how versioning is performed in this project. The version number of an app consists of 4 segments: **Major**.**Minor**.**Build**.**Revision**. **Major** and **Minor** are read from the app.json file for each app. **Build** and **Revision** are calculated. Currently 3 versioning strategies are supported:
**0** = **Build** is the **github [run_number](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** for the CI/CD workflow, increased by the **runNumberOffset** setting value (if specified). **Revision** is the **github [run_attempt](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** subtracted 1.
**2** = **Build** is the current date as **yyyyMMdd**. **Revision** is the current time as **hhmmss**. Date and time are always **UTC** timezone to avoid problems during daylight savings time change. Note that if two CI/CD workflows are started within the same second, this could yield to identical version numbers from two different runs.
**3** = **Build** is taken from **app.json** (like Major and Minor) and **Revision** is the **github [run_number](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** of the workflow run
**15** = **Build** is max value and **Revision** is the **github [run_number](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** of the workflow run. **Note**: use this strategy with caution. We recommend using it only when producing non-official artifacts (e.g. from PR builds or test workflows).

**+16** when adding 16 to the above versioning strategies, all builds will use **repoVersion** setting instead of the *Major.Minor* found inside app.json (and also *build* if versioningStrategy is 3+16) | 0 | +| versioningStrategy | The versioning strategy determines how versioning is performed in this project. The version number of an app consists of 4 segments: **Major**.**Minor**.**Build**.**Revision**. **Major** and **Minor** are read from the app.json file for each app. **Build** and **Revision** are calculated. Currently 3 versioning strategies are supported:
**0** = **Build** is the **github [run_number](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** of the current workflow run, increased by the **runNumberOffset** setting value (if specified). **Revision** is the **github [run_attempt](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** subtracted 1. Note: when workflows other than CI/CD trigger a build (e.g. Test Next Major), the run_number of that workflow is used, not the CI/CD run_number.
**2** = **Build** is the current date as **yyyyMMdd**. **Revision** is the current time as **hhmmss**. Date and time are always **UTC** timezone to avoid problems during daylight savings time change. Note that if two CI/CD workflows are started within the same second, this could yield to identical version numbers from two different runs.
**3** = **Build** is taken from **app.json** (like Major and Minor) and **Revision** is the **github [run_number](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** of the workflow run
**15** = **Build** is max value and **Revision** is the **github [run_number](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** of the workflow run. **Note**: use this strategy with caution. We recommend using it only when producing non-official artifacts (e.g. from PR builds or test workflows).

**+16** when adding 16 to the above versioning strategies, all builds will use **repoVersion** setting instead of the *Major.Minor* found inside app.json (and also *build* if versioningStrategy is 3+16) | 0 | | additionalCountries | This property can be set to an additional number of countries to compile, publish and test your app against during workflows. Note that this setting can be different in NextMajor and NextMinor workflows compared to the CI/CD workflow, by specifying a different value in a workflow settings file. | [ ] | | keyVaultName | When using Azure KeyVault for the secrets used in your workflows, the KeyVault name needs to be specified in this setting if it isn't specified in the AZURE_CREDENTIALS secret. Read [this](UseAzureKeyVault.md) for more information. | | | licenseFileUrlSecretName | Specify the name (**NOT the secret**) of the LicenseFileUrl secret. Default is LicenseFileUrl. AL-Go for GitHub will look for a secret with this name in GitHub Secrets or Azure KeyVault to use as LicenseFileUrl. A LicenseFileUrl is required when building AppSource apps for Business Central prior to version 22. Read [this](SetupCiCdForExistingAppSourceApp.md) for more information. | LicenseFileUrl | @@ -231,7 +231,7 @@ Please read the release notes carefully when installing new versions of AL-Go fo | Name | Description | Default value | | :-- | :-- | :-- | | repoName | the name of the repository | name of GitHub repository | -| runNumberOffset | when using **VersioningStrategy** 0, the CI/CD workflow uses the GITHUB RUN_NUMBER as the build part of the version number as described under VersioningStrategy. The RUN_NUMBER is ever increasing and if you want to reset it, when increasing the Major or Minor parts of the version number, you can specify a negative number as runNumberOffset. You can also provide a positive number to get a starting offset. Read about RUN_NUMBER [here](https://go.microsoft.com/fwlink/?linkid=2217059&clcid=0x409) | 0 | +| runNumberOffset | when using **VersioningStrategy** 0, the current workflow run uses the GITHUB RUN_NUMBER as the build part of the version number as described under VersioningStrategy. The RUN_NUMBER is ever increasing and if you want to reset it, when increasing the Major or Minor parts of the version number, you can specify a negative number as runNumberOffset. You can also provide a positive number to get a starting offset. Read about RUN_NUMBER [here](https://go.microsoft.com/fwlink/?linkid=2217059&clcid=0x409) | 0 | | applicationDependency | Application dependency defines the lowest Business Central version supported by your app (Build will fail early if artifacts used are lower than this). The value is calculated by reading app.json for all apps, but cannot be lower than the applicationDependency setting which has a default value of 18.0.0.0 | 18.0.0.0 | | installTestRunner | Determines whether the test runner will be installed in the pipeline. If there are testFolders in the project, this setting will be true. | calculated | | installTestFramework | Determines whether the test framework apps will be installed in the pipeline. If the test apps in the testFolders have dependencies on the test framework apps, this setting will be true | calculated | From a94b475fc7455ed86b805b8e052ee3666e651f3b Mon Sep 17 00:00:00 2001 From: Jeffrey Bulanadi Date: Thu, 23 Apr 2026 10:41:34 +0800 Subject: [PATCH 2/2] docs: address Copilot review comments on versioningStrategy and runNumberOffset - versioningStrategy: replace 'Currently 3 versioning strategies are supported' with 'The following versioning strategies are supported' to avoid a hardcoded count that is inconsistent with the four documented strategies (0, 2, 3, 15) plus the +16 modifier. - runNumberOffset: extend the applicable strategies from '0' to '0, 3, or 15' to match the actual behavior in ReadSettings.ps1 where runNumberOffset is applied to GITHUB_RUN_NUMBER for all three strategies. --- Scenarios/settings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Scenarios/settings.md b/Scenarios/settings.md index 861e40267..3ec2c429c 100644 --- a/Scenarios/settings.md +++ b/Scenarios/settings.md @@ -97,7 +97,7 @@ The repository settings are only read from the repository settings file (.github | updateDependencies | Setting updateDependencies to true causes AL-Go to build your app against the first compatible Business Central build and set the dependency version numbers in the app.json accordingly during build. All version numbers in the built app will be set to the version number used during compilation.
⚠️ **Warning:** When the `updateDependencies` setting is enabled, the application versions from the BC Artifact are stamped into the `app.json`. However, not all app versions available in BC Artifacts are shipped in BC SaaS, which can lead to dependency resolution failures during AppSource validation. Therefore, it is not recommended to use this setting if you intend on deploying the build to AppSource. | false | | generateDependencyArtifact | When this repository setting is true, CI/CD pipeline generates an artifact with the external dependencies used for building the apps in this repo. | false | | companyName | Company name selected in the database, used for running the CI/CD workflow. Default is to use the default company in the selected Business Central localization. | | -| versioningStrategy | The versioning strategy determines how versioning is performed in this project. The version number of an app consists of 4 segments: **Major**.**Minor**.**Build**.**Revision**. **Major** and **Minor** are read from the app.json file for each app. **Build** and **Revision** are calculated. Currently 3 versioning strategies are supported:
**0** = **Build** is the **github [run_number](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** of the current workflow run, increased by the **runNumberOffset** setting value (if specified). **Revision** is the **github [run_attempt](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** subtracted 1. Note: when workflows other than CI/CD trigger a build (e.g. Test Next Major), the run_number of that workflow is used, not the CI/CD run_number.
**2** = **Build** is the current date as **yyyyMMdd**. **Revision** is the current time as **hhmmss**. Date and time are always **UTC** timezone to avoid problems during daylight savings time change. Note that if two CI/CD workflows are started within the same second, this could yield to identical version numbers from two different runs.
**3** = **Build** is taken from **app.json** (like Major and Minor) and **Revision** is the **github [run_number](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** of the workflow run
**15** = **Build** is max value and **Revision** is the **github [run_number](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** of the workflow run. **Note**: use this strategy with caution. We recommend using it only when producing non-official artifacts (e.g. from PR builds or test workflows).

**+16** when adding 16 to the above versioning strategies, all builds will use **repoVersion** setting instead of the *Major.Minor* found inside app.json (and also *build* if versioningStrategy is 3+16) | 0 | +| versioningStrategy | The versioning strategy determines how versioning is performed in this project. The version number of an app consists of 4 segments: **Major**.**Minor**.**Build**.**Revision**. **Major** and **Minor** are read from the app.json file for each app. **Build** and **Revision** are calculated. The following versioning strategies are supported:
**0** = **Build** is the **github [run_number](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** of the current workflow run, increased by the **runNumberOffset** setting value (if specified). **Revision** is the **github [run_attempt](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** subtracted 1. Note: when workflows other than CI/CD trigger a build (e.g. Test Next Major), the run_number of that workflow is used, not the CI/CD run_number.
**2** = **Build** is the current date as **yyyyMMdd**. **Revision** is the current time as **hhmmss**. Date and time are always **UTC** timezone to avoid problems during daylight savings time change. Note that if two CI/CD workflows are started within the same second, this could yield to identical version numbers from two different runs.
**3** = **Build** is taken from **app.json** (like Major and Minor) and **Revision** is the **github [run_number](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** of the workflow run
**15** = **Build** is max value and **Revision** is the **github [run_number](https://go.microsoft.com/fwlink/?linkid=2217416&clcid=0x409)** of the workflow run. **Note**: use this strategy with caution. We recommend using it only when producing non-official artifacts (e.g. from PR builds or test workflows).

**+16** when adding 16 to the above versioning strategies, all builds will use **repoVersion** setting instead of the *Major.Minor* found inside app.json (and also *build* if versioningStrategy is 3+16) | 0 | | additionalCountries | This property can be set to an additional number of countries to compile, publish and test your app against during workflows. Note that this setting can be different in NextMajor and NextMinor workflows compared to the CI/CD workflow, by specifying a different value in a workflow settings file. | [ ] | | keyVaultName | When using Azure KeyVault for the secrets used in your workflows, the KeyVault name needs to be specified in this setting if it isn't specified in the AZURE_CREDENTIALS secret. Read [this](UseAzureKeyVault.md) for more information. | | | licenseFileUrlSecretName | Specify the name (**NOT the secret**) of the LicenseFileUrl secret. Default is LicenseFileUrl. AL-Go for GitHub will look for a secret with this name in GitHub Secrets or Azure KeyVault to use as LicenseFileUrl. A LicenseFileUrl is required when building AppSource apps for Business Central prior to version 22. Read [this](SetupCiCdForExistingAppSourceApp.md) for more information. | LicenseFileUrl | @@ -231,7 +231,7 @@ Please read the release notes carefully when installing new versions of AL-Go fo | Name | Description | Default value | | :-- | :-- | :-- | | repoName | the name of the repository | name of GitHub repository | -| runNumberOffset | when using **VersioningStrategy** 0, the current workflow run uses the GITHUB RUN_NUMBER as the build part of the version number as described under VersioningStrategy. The RUN_NUMBER is ever increasing and if you want to reset it, when increasing the Major or Minor parts of the version number, you can specify a negative number as runNumberOffset. You can also provide a positive number to get a starting offset. Read about RUN_NUMBER [here](https://go.microsoft.com/fwlink/?linkid=2217059&clcid=0x409) | 0 | +| runNumberOffset | when using **VersioningStrategy** 0, 3, or 15, the current workflow run uses the GITHUB RUN_NUMBER as the build part of the version number as described under VersioningStrategy. The RUN_NUMBER is ever increasing and if you want to reset it, when increasing the Major or Minor parts of the version number, you can specify a negative number as runNumberOffset. You can also provide a positive number to get a starting offset. Read about RUN_NUMBER [here](https://go.microsoft.com/fwlink/?linkid=2217059&clcid=0x409) | 0 | | applicationDependency | Application dependency defines the lowest Business Central version supported by your app (Build will fail early if artifacts used are lower than this). The value is calculated by reading app.json for all apps, but cannot be lower than the applicationDependency setting which has a default value of 18.0.0.0 | 18.0.0.0 | | installTestRunner | Determines whether the test runner will be installed in the pipeline. If there are testFolders in the project, this setting will be true. | calculated | | installTestFramework | Determines whether the test framework apps will be installed in the pipeline. If the test apps in the testFolders have dependencies on the test framework apps, this setting will be true | calculated |