Admin API for PTE publishing/installing for BC30 and later

Actions/.Modules/settings.schema.json

@@ -985,7 +985,7 @@
                 "unpublishOldVersions": {
                     "type": "boolean",
                     "default": false,
-                    "description": "When set to true, AL-Go unpublishes old, uninstalled versions of the deployed apps from the environment after a successful deployment. Only applies to PTE deployments (Scope PTE) and is non-fatal. See https://aka.ms/ALGoSettings#deployto"
+                    "description": "Optional boolean, default false. After successful Scope PTE deployment, unpublishes only selected apps' uninstalled versions older than the currently installed version on Business Central 25.4 through 29. On BC 30 and later, Business Central manages cleanup in the background, which may be delayed; timing and retained versions are not guaranteed. This setting does not control background cleanup: AL-Go warns and skips explicit unpublish without failing deployment. Cleanup failures are warnings; does not apply to Scope Dev or custom deployments. See https://aka.ms/ALGoSettings#deployto"
                 }
             }
         }

Actions/Deploy/Deploy.ps1

@@ -193,15 +193,15 @@ else {
                 Publish-BcContainerApp @parameters -useDevEndpoint -checkAlreadyInstalled -excludeRuntimePackages -replacePackageId
             }
             else {
-                # Use automation API for production environments (Publish-PerTenantExtensionApps)
+                # The shared AL-Go publisher selects the API based on the target environment version.
                 $parameters = @{
                     "bcAuthContext" = $bcAuthContext
                     "environment" = $deploymentSettings.EnvironmentName
                     "appFiles" = $apps
                 }
                 if ($deploymentSettings.SyncMode) {
                     if (@('Add','ForceSync') -notcontains $deploymentSettings.SyncMode) {
-                        throw "Invalid SyncMode $($deploymentSettings.SyncMode) when deploying using the automation API. Valid values are Add and ForceSync."
+                        throw "Invalid SyncMode $($deploymentSettings.SyncMode) when deploying Per Tenant Extensions. Valid values are Add and ForceSync."
                     }
                     Write-Host "Using $($deploymentSettings.SyncMode)"
                     $syncMode = $deploymentSettings.SyncMode
@@ -211,11 +211,11 @@ else {
 
                 CheckInstalledApps -bcAuthContext $bcAuthContext -environment $deploymentSettings.EnvironmentName -appFiles $apps
 
-                Write-Host "Publishing apps using automation API"
-                Publish-PerTenantExtensionApps @parameters
+                Write-Host "Publishing Per Tenant Extensions"
+                PublishPTEApps @parameters
 
                 if (($deploymentSettings['unpublishOldVersions'] -is [bool]) -and $deploymentSettings['unpublishOldVersions']) {
-                    Write-Host "Unpublishing old app versions"
+                    Write-Host "Checking cleanup of old app versions"
                     UnpublishOldAppVersions -bcAuthContext $bcAuthContext -environment $deploymentSettings.EnvironmentName -appFiles $apps
                 }
             }

Actions/Deploy/README.md

@@ -2,6 +2,14 @@
 
 Deploy Apps to online environment
 
+## PTE publishing
+
+PTE deployment installs apps in dependency order and skips app versions that are already installed or superseded by a newer installed version. Deployment waits for installation to complete; installation failures fail the deployment.
+
+BC 30+ S2S deployments require `AdminCenter.ReadWrite.All` application permission, tenant admin consent, and registration in the administration center's Authorized Microsoft Entra apps. Existing AUTHCONTEXT structures stay unchanged, and environment API permissions remain necessary. See [deployment authorization](../../Workshop/ContinuousDeployment.md#pte-deployment-authorization) for full requirements.
+
+`unpublishOldVersions` is an optional boolean in `DeployTo<environment>` (default `false`). It runs only after successful Scope PTE publishing. On BC 25.4 through 29, only selected apps' uninstalled versions older than the currently installed version are unpublished. On BC 30+, Business Central manages cleanup in the background, which may be delayed; timing and retained versions are not guaranteed. The setting does not control that background cleanup: AL-Go warns and skips explicit unpublish without failing deployment. Scope Dev, custom deployments, and container behavior are unchanged.
+
 ## INPUT
 
 ### ENV variables

RELEASENOTES.md

@@ -1,3 +1,11 @@
+### Breaking changes
+
+**PTE deployment to BC 30 and later requires additional authorization.** Earlier, environment-level deployment permissions were sufficient. Existing deployments to BC 30 or later will now fail if the required administration center access has not been granted.
+
+For S2S, add the `AdminCenter.ReadWrite.All` application permission, grant tenant admin consent, and register the client ID under the Business Central administration center's **Authorized Microsoft Entra apps**. Delegated users need appropriate administration center access. Keep the existing environment permissions and AUTHCONTEXT credential structure. See [deployment authorization](Workshop/ContinuousDeployment.md#pte-deployment-authorization). Deployments to BC 29 and earlier, Scope Dev, custom deployments, and container behavior are unchanged.
+
+**Old-version cleanup changes on BC 30 and later.** Business Central manages cleanup in the background rather than AL-Go explicitly unpublishing old versions. Cleanup may be delayed; its timing and retained versions are not guaranteed. `unpublishOldVersions` does not control background cleanup: if enabled, AL-Go warns and skips explicit unpublish without failing deployment.
+
 ### Separate test execution from RunPipeline (PREVIEW)
 
 A new `useSeparateTestAction` complex setting (default `{ "enabled": false, "testType": "" }`) runs normal tests (`testFolders`) in a dedicated `RunTests` action when `enabled` is `true`. The separate action is used when tests are built and enabled and the build uses one local container. Normal tests remain in `RunPipeline` for builds with `additionalCountries`, no published apps, or test-data import callbacks that would otherwise have no remaining RunPipeline test category. BCPT and page scripting tests remain in `RunPipeline`.
@@ -9,7 +17,7 @@ The action uses AlTool by default, running each app's enabled normal tests in on
 
 ### New `unpublishOldVersions` setting for deployment
 
-The `DeployTo<environment>` setting now supports an opt-in `unpublishOldVersions` boolean (default `false`). When enabled, AL-Go unpublishes old, uninstalled versions of the deployed apps from the environment after a successful deployment, keeping Extension Management clean. This only applies to PTE deployments (Scope PTE / automation API), uses the Automation API v2.0 `Microsoft.NAV.unpublish` action, and is non-fatal (failures are reported as warnings and never fail the deployment).
+The `DeployTo<environment>` setting now supports an opt-in `unpublishOldVersions` boolean (default `false`). After successful Scope PTE deployment on BC 25.4 through 29, it removes only selected apps' uninstalled versions older than the currently installed version. Cleanup failures remain warnings. For BC 30 and later, see the cleanup behavior under **Breaking changes** above.
 
 ### Settings sources in workflow logs
 
@@ -56,7 +64,7 @@ AL-Go now supports including pre-release versions of Business Central app packag
 
 ### New `unpublishOldVersions` setting for deployment
 
-The `DeployTo<environment>` setting now supports an opt-in `unpublishOldVersions` boolean (default `false`). When enabled, AL-Go unpublishes old, uninstalled versions of the deployed apps from the environment after a successful deployment, keeping Extension Management clean. This only applies to PTE deployments (Scope PTE / automation API), uses the Automation API v2.0 `Microsoft.NAV.unpublish` action, and is non-fatal (failures are reported as warnings and never fail the deployment).
+The `DeployTo<environment>` setting now supports an opt-in `unpublishOldVersions` boolean (default `false`). After successful Scope PTE deployment on BC 25.4 through 29, it removes only selected apps' uninstalled versions older than the currently installed version. Cleanup failures remain warnings. For BC 30 and later, see the cleanup behavior under **Breaking changes** above.
 
 ### Expanded AL-Go telemetry dashboard
 

Scenarios/RegisterProductionEnvironment.md

@@ -2,6 +2,14 @@
 
 *Prerequisites: A completed ["Create a release of your application"](CreateRelease.md) scenario, an online production environment setup for S2S as specified in task 2 here: [Using Service to Service Authentication - Business Central | Microsoft Docs](https://go.microsoft.com/fwlink/?linkid=2217415&clcid=0x409), using the same Microsoft Entra application registration as scenario 3*
 
+## PTE publishing authorization
+
+Before **Scope PTE** deployment to BC 30 or later using S2S, add the **AdminCenter.ReadWrite.All** application permission under **Dynamics 365 Business Central**, grant tenant admin consent, and register the client ID on the Business Central administration center's **Authorized Microsoft Entra apps** page. Existing app registrations may need this additional authorization. Keep the existing environment API permissions and the Microsoft Entra application registration and required permission sets inside the Business Central environment. These additional permissions are not required for deployment to earlier BC versions.
+
+The **AUTHCONTEXT** credential structure is unchanged, including `TenantID`, `ClientID`, and `ClientSecret` for S2S. See [deployment authorization](../Workshop/ContinuousDeployment.md#pte-deployment-authorization) and the official [Business Central administration center API authentication documentation](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/administration-center-api).
+
+## Register the environment
+
 > [!NOTE]
 > For access to environments, environment secrets, and deployment branches in private or internal repositories, you must use GitHub Pro, GitHub Team, or GitHub Enterprise. (see [this](https://go.microsoft.com/fwlink/?linkid=2216857&clcid=0x409)). We are considering adding a secondary option for listing environments.
 

Scenarios/RegisterSandboxEnvironment.md

@@ -2,6 +2,14 @@
 
 *Prerequisites: A completed ["Add a test app to an existing project"](Scenarios/AddATestApp.md) scenario, a Microsoft Entra application registration, and an online sandbox environment called QA with the setup for S2S as specified in task 1 and 2 [here](https://go.microsoft.com/fwlink/?linkid=2217415&clcid=0x409) completed.*
 
+## PTE publishing authorization
+
+For **Scope PTE** S2S deployment to BC 30 or later, add the **AdminCenter.ReadWrite.All** application permission under **Dynamics 365 Business Central**, grant tenant admin consent, and register the application's client ID on the Business Central administration center's **Authorized Microsoft Entra apps** page. Existing app registrations may need this additional authorization. Retain the existing environment API permissions and Microsoft Entra application registration inside the environment, including the required permission sets.
+
+The **AUTHCONTEXT** credential structure below is unchanged. See [deployment authorization](../Workshop/ContinuousDeployment.md#pte-deployment-authorization) and the official [Business Central administration center API authentication documentation](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/administration-center-api). These additional permissions are not required for deployment to earlier BC versions or **Scope Dev**.
+
+## Register the environment
+
 > [!NOTE]
 > For access to environments, environment secrets, and deployment branches in private or internal repositories, you must use GitHub Pro, GitHub Team, or GitHub Enterprise. (see [this](https://go.microsoft.com/fwlink/?linkid=2216857&clcid=0x409)).
 > If you are running a free GitHub SKU, you can use the [environments](https://aka.ms/algosettings#environments) setting and a secret with a name of the environment followed by` _AuthContext` instead of GitHub environments and environment secrets.