Skip to main content
Matrix42 Self-Service Help Center

Build & Deploy a Configuration Package with Azure DevOps Pipeline

This is a step-by-step guide on how to use Matrix42 DevOps Services to build and deploy a Digital Workspace Platform Extension from an existing Azure DevOps Pipeline.

Prerequisites

Create your Extension

  1. Visit the Matrix42 DevOps Portal (https://extensions.matrix42.com/portal) and login with your Matrix42 Cloud Account.
  2. Click on "New Extension" and choose "Empty Extension (for Build Pipelines)"

When opening the Matrix42 DevOps Portal for the first time you will also be guided to create your first Extension.

clipboard_e43a6eea155fa70633f3a7c4d3d30257e.png

There are also other options to create an Extension but for now, we need an empty Extension.

clipboard_ec6c5789ff3d7f0376f3a125cae2d6b8c.png

  1. Choose a name and an optional description for your Extension and click on "Create Extension"

The name and description are only used for organizational purposes. (You can redefine these when publishing your Extension)

clipboard_ed7a6a53903c3025bba70dcd460f65455.png

  1. After you created your Extension you will see a prompt to copy the Extension ID of your Extension for later integration in your Build Pipeline

Copy the Extension ID and save it for later.

clipboard_e3caebf35e05da2638f553f9a1b19c83e.png

Setup your Azure DevOps Repository

Please make sure that the source files of your Digital Workspace Platform Configuration Package are all contained in the same folder in your repository in the same structure as you would expect them in the built package. (Configuration Package File Structure)

For example, you can use the following repository structure:

repo-structure

  • BasePackage: The folder "BasePackage" contains the content of the generated Configuration Packaged directly exported with the export action in the Matrix42 Digital Workspace Platform.
  • Solutions: The folder "Solutions" should contain all Visual Studio projects to build binaries that are required for the generated Configuration Package.

Currently, we do not support building Visual Studio projects with the Matrix42 Extensions Publishing Tools. Please compensate that with preceding Pipeline tasks and make sure the output binaries are copied into the right folder structure.

Configuring your Azure DevOps Pipeline

In the standard Azure DevOps Pipeline, you will first generate a Digital Workspace Platform Configuration Package (ZIP file) and then upload it to your Extension in the Matrix42 DevOps Portal. 

Generating the Configuration Package

To generate the Digital Workspace Platform Configuration Package you should use the "Generate Package" Task of the Matrix42 Extensions Publishing Tools.

azure-pipeline-01

Display name: The name which will be displayed when the Task is running.

Location of the manifest (package.json): The repository root relative path to the package.json of your Configuration Package. (See Configuration Package File Structure)

Optional BuildNumber generated by the pipeline: If specified this build number will be attached to the "Version" field in the package.json. Use this to automatically increment the Extension version per Pipeline run.

An Extension version does at least require two parts with up to a maximum of four parts. These are example version patterns you could adept:

  • Major.Minor (e.g. 1.0)
  • Major.Minor.Patch (e.g. 1.0.3)
  • Major.Minor.Patch.BuildNumber (e.g. 1.0.3.964)

Output Location: The path where the generated Configuration Package (ZIP file) is saved. You will need this path in the configuration of the "Upload Release" Task of the Matrix42 Extensions Publishing Tools.

Uploading the generated Configuration Package as an Extension Release

To upload the generated Digital Workspace Platform Configuration Package you should use the "Upload Release" Task of the Matrix42 Extensions Publishing Tools.

 azure-pipeline-02

Display name: The name which will be displayed when the Task is running.

Matrix42 Extension Gallery Connection: The service connection you want to use to upload your Release. This will also decide which Matrix42 Cloud Account will referenced as the contributor who uploaded the Release. (See Configuration of Matrix42 Extensions Publishing Tools)

The account which is configured for the service connection is required to be added as a contributor with at least the "Contributor" permission level.

Learn more about permissions

Extension Id: The Extension ID you copied when creating your empty Extension. The Extension ID specified here will decide to which Extension the Configuration Package (Release) will be mapped to.

Digital Workspace Platform Configuration Packages have a unique ID (found in the package.json). This means that once a Configuration Package was mapped to an Extension in the Matrix42 DevOps Portal following Releases can only be uploaded to that Extension.

Extension Location: The path where the generated Configuration Package was saved. (See "Generate Package" Task above)

Run your Azure DevOps Pipeline

Now that you set everything up you can run your Azure DevOps Pipeline. After a successful run, the built Digital Workspace Platform Configuration Package will be uploaded as a new Release to your Extension in the Matrix42 DevOps Portal. (https://extensions.matrix42.com/portal)  

What comes next?

After creating Releases for your Digital Workspace Platform Extension you will probably want to do one of the following:

 

  • Was this article helpful?