Create a release pipeline for your app

Basic Setup

When creating a release pipeline for your app using VS Code and Azure DevOps, you need an organization (see create org), a project (see create project), an app repository (see create app) and the imported task groups (see update task groups). To create a release pipeline for your app, you need to take the following steps:

  1. Right-click on the project where you want to create a release pipeline for your app and select "Create Release Pipeline"
  2. Select the app repository that you want to use
  3. Select the task group template that you want to use
  4. Select the trigger pipeline of your app that you want to use
  5. Select the release stages that you want to use
  6. Select the trigger pipeline package (artifact) that you want to use
  7. Enter the pipeline name that you want to use
  8. Add a description for your release pipeline

With that, a new release pipeline will be created. It has all the basic setup and preparation needed to setup the deployment for your app.

Configuration

SaaS deployment

Get a user with the rights to create an app registration

If there's no user in the customer tenant that has the rights to create new App Registrations you might want to create one, else you can skip the following steps:

  1. Open URL https://partner.microsoft.com/commerce/customers
  2. Find your customer in the list and open it
  3. Open "Service Management"
  4. Open "Microsoft Entra ID" (ex. "Azure Active Directory")
  5. Open "Microsoft Entra ID" (ex. "Azure Active Directory") once more on the left
    • Go to users
    • Click on "New user"
      • Select "Create user"
      • Fill in username (e.g. "bcadmin")
      • Click on "Roles" and select "Global Administrator"
      • Click on "Create"
      • Important: Continue the following steps with the newly created user
      • Please note: This step might be unnecessary if a "Global Administrator" from within the customer tenant is creating the App Registration. It's only relevant, if you do the steps in Microsoft Entra ID (ex. Azure Active Directy) with credentials from outside the customers tenant (e.g. when doing this via Partner Center). Please also note, that you'll need a user with "Global Administrator"-role later for the "Register the Microsoft Entra application"-step

Create the app registration

  1. Open "App Registrations"
  2. Click "Add new registration"
  3. Click on the newly created app
    • Open "API Permissions"
    • Click on "Add Permission"
    • Select "Dynamics 365 Business Central"
    • Select "Application Permissions"
    • Select "Automation.ReadWrite.All"
    • Click on "Add permissions"
    • Now select your newly created API Permission and click on the button "Grant admin consent for CustomerName.onmicrosoft.com"
  4. Click on "Certificates & secrets"
    • Click on "New client secret"
    • Add a description
    • Add the expiration date
    • Click on "Add"
    • Important: Copy the "value" of the secret right away! It won't be fully shown later on. This is the ClientSecret needed for the variable groups
  5. Select "Overview"
    • The "Application (client) ID" is the ClientId needed for the variable groups

Register the Microsoft Entra application in Business Central Admin Center

  1. Open the Business Central Admin Center
  2. Navigate to Microsoft Entra Apps
  3. Click on "Authorize Microsoft Entra app"
  4. Fill in the ClientId from the previous step
  5. Click on the link "Grant"
    • A page with a required Login opens
    • Use the newly created user from the previous step or another user with "Global Administrator"-role and continue
    • Accept the requested permissions and the page should close afterwards
  6. The Microsoft Entra application is now authorized for the admin center API

Register the Microsoft Entra application in Business Central

  1. Open the Business Central Webclient
  2. Search for "Microsoft Entra Applications" (ex. "AAD Applications") and open the page
  3. Click on "New"
  4. Fill in the ClientId from the step "Create the app registration"
  5. Fill in a custom description
  6. Click on the action "Grant Consent"
    • A page with a required Login opens
    • Use the newly created user from the previous step or another user with "Global Administrator"-role and continue
    • Accept the requested permissions and the page should close afterwards
  7. Look at the bottom of the Microsoft Entra application page and add the following
    • "D365 AUTOMATION"
    • "EXTEN. MGT. - ADMIN"
    • additional permission sets required by partner apps (e.g. "CCS LIC ALL" for COSMO Licensing)
  8. Your Microsoft Entra application is now fully set up!

Note: This step needs to be done for each environment you want to create a release pipeline for.

Setup the configuration in Azure DevOps

  1. Open "Pipelines/Library" in Azure DevOps
  2. Open Variable Group "D365BC Deployment"
  3. Fill in the mandatory variables
Variable Name Value
"ClientId" Shown in "ClientId & ClientSecret"
"ClientSecret" Shown in "ClientId & ClientSecret"
"TenantId" Shown in the link to the webclient you are aiming for, e.g.
"Environment.*Name*" Shown in "Environments" -> Open URL https://businesscentral.dynamics.com/**TenantId**/admin|

Finished! Now your release pipeline should be ready to go!

OnPrem Deployment

Deploying via PowerShell

Although deployment via Automation API is preferred and much more secure (see next section you can also install a Build Agent directly on the target machine like described in the docs. Please use a separate Agent Pool for the Build Agent and set this Pool within your release pipeline.

When creating new release pipeline, choose the option "COSMO Deploy App (D365BC OnPrem)"

  1. Install and configure the Build Agent on the target machine. It will then be available in the Azure DevOps Pool.

    Build Agent in Azure DevOps Pool

    Note: It is recommended to set up a maintenance job for the Build Agent to clean up the agent's work directory. This can be done by adding a maintenance job to the agent pool like described in the docs.

  2. Replace the agent pool in the created release pipline with the pool where the Build Agent is located.

    Build Agent in Release Pipeline

Setup the configuration in Azure DevOps
  1. Open "Pipelines/ Library" in Azure DevOps
  2. Open Variable Group "D365BC Deployment"
  3. Fill in the mandatory variables
Variable Name Value
"serverInstance.*Name*" The Name of the ServerInstance

Finished! Now your release pipeline should be ready to go!

Deploying via Automation API (OAuth or Basic Auth)

When creating new release pipeline, choose the option "COSMO Deploy App (D365BC OnPrem API)"

Now you need to enable the Automation API for your OnPrem environment:

  1. In Windows PowerShell install ExternalDeployer:

    Install-Module ALOps.ExternalDeployer -Force 
Import-Module ALOps.ExternalDeployer 
Install-ALOpsExternalDeployer -ServerInstance <Your Server Instance>

  2. Restart Server Instance (as indicated when the scripts are executed)

  3. Generate Web Service Access Key (Password) for the User which should be used to access the Automation API

    Generate Web Service Access Key

  4. The API should be reachable from external ("https://Url/ServerInstance/api/microsoft/automation/v1.0/companies")

    • Important : If errors occur, you need to contact local or global IT to open the appropriate port and to enable authentication.
Setup the configuration in Azure DevOps
  1. Open "Pipelines/ Library" in Azure DevOps
  2. Open Variable Group "D365BC Deployment"
  3. Fill in the mandatory variables
Variable Name Value
"Username" The user which is used to access the Automation API"
"Password" The Web Service Access Key (Password) of the user which is used to access the Automation API"
"Endpoint.*Name*" The URL including the Name of the ServerInstance

Finished! Now your release pipeline should be ready to go!

Advanced

Schedule

Azure Devops allows to configure a schedule for a specified stage as a pre-deployment condition, which triggers the deployment of the release at a specific time. This is useful for example for deploymens to a production environment, which should be done at a specific time, e.g. during the night.

To configure a schedule for a stage:

  1. Open the release pipeline
  2. Select the stage you want to configure the schedule for
  3. Click on the "Pre-deployment conditions" tab
  4. Select "Triggers"
  5. Select "Schedule"
  6. Configure the schedule by specifying the time and days when the deployment should be triggered.

Configure Release Stage Schedule

Be aware when combining the schedule with other pre-deployment conditions, e.g. approvals, as the stage will only be triggered/actived if the schedule is met. This means that approval checks and notifications will be sent out at the time of the schedule, what you might not expect or want.

Find more information in the official documentation.

Multiple Schedules

Since Azure DevOps does only support one schedule per stage, it is difficult to configure multiple schedules for one stage. However, it is possible to create duplicate stages for the same environment and configure a different schedule for each stage. To simplify this configration, we provide an API endpoint, which can be invoked as a gate for the stage. This means the API call represents a "schedule gate".

To configure the API call as a gate:

  1. Open the release pipeline

  2. Select the stage you want to configure the schedule for

  3. Click on the "Pre-deployment conditions" tab

  4. Select "Gates"

  5. Add a new Gate and select "Invoke REST API"

  6. Give the gate a display name

  7. Select connection type "Generic"

  8. Select the COSMO Alpaca service connection (named like "COSMO Azure DevOps & Docker Self-Service backend for project...")

  9. Select method "POST"

  10. Provide the valid hours for the schedule in the body: (e.g. for 9 and 21 o'clock, which actually means the time windows between 9-10 and 21-22 o'clock are valid)

    [ 9,12 ]

  11. Set the URL suffix and parameters to:

    automation/0.11/Release/validateHour?tzOffset=1

    The tzOffset parameter is optional and can be used to adjust the time zone offset. The value is the time zone offset in hours. For example, if the time zone is UTC+1, the value is 1. If the time zone is UTC-5, the value is -5.

  12. Configure time between the re-evaluation of the gate under "Evaluation options" as needed (e.g. 15 minutes)

Configure Release Stage Schedule Part 1 Configure Release Stage Schedule Part 2

Known Issues

In case your (OnPrem API) Release Pipeline fails with the following error:

COSMO OnPremAPI Publish Error supported MIME type Microsoft.OData.ODataMediaType

If you’re running BC22 or higher, check if the BC service parameter “ManagementApiServicesEnabled” is set to true or not. If not, set it to true.

Set-NavServerConfiguration -ServerInstance [Servicename] -Keyname "ManagementApiServicesEnabled" -KeyValue $true

This will be set automatically in the installation process of the ALOps.ExternalDeployer in a version higher than "1.59". You may need to update the ALOps.ExternalDeployer too. You should follow these instructions to do so:

  1. In Windows PowerShell uninstall ExternalDeployer:
Import-Module ALOps.ExternalDeployer
# Remove all currently installed AlOps Services:
Remove-ALOpsExternalDeployer -ServiceName ‘ALOpsExternalDeployer$[Servicename]’
Uninstall-Module ALOps.ExternalDeployer
  1. Check if the Module is completely deleted
    • Open the following Directory: "C:\Program Files\WindowsPowerShell\Modules"
    • You should'nt see a folder named "ALOps.ExternalDeployer". If you do, you may delete it manually.
  2. Install ExternalDeployer again, follow "normal" installation instructions (see above)