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 Azure DevOps Pipeline.
Prerequisites
- A Matrix42 Cloud Account. (https://accounts.matrix42.com)
- An Azure DevOps Repository containing the source files of a Digital Workspace Platform Configuration Package.
- Matrix42 Extensions Publishing Tools installed and configured in your Azure DevOps Organization.
(How to install and configure Matrix42 Extensions Publishing Tools for Azure DevOps)
Create your Extension
- Visit the Matrix42 DevOps Portal (https://extensions.matrix42.com/portal) and login with your Matrix42 Cloud Account.
- 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.
There are also other options to create an Extension but for now, we need an empty Extension.
- 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)
- 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.
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:
- 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.
Build the Extension
To generate the Digital Workspace Platform Extension you should use the "Build Extension" Task of the Matrix42 Extensions Publishing Tools.
Display name: The name which will be displayed when the Task is running.
Extension Manifest (package.json): The repository root relative path to the package.json of your Configuration Package. (See Configuration Package File Structure)
Optional build number: 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.Release (e.g. 1.0.3.964)
Extension 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.
Matrix42 Developer Identity: The Developer Identity used to sign the Configuration Package. You can read more about what a digital signature is and why it is needed here.
Developer Identity Password: The password for the provided Matrix42 Developer Identity.
Please be aware that the Matrix42 Developer Identity and its password are highly sensible data which should always be protected.
We recommend introducing them as secure files and importing the password from an Azure Key Vault in Azure DevOps. You can learn more about that here:
Use Azure Key Vault secrets in Azure Pipelines - Azure Pipelines | Microsoft Docs
Secure files for Azure Pipelines - Azure Pipelines | Microsoft Docs
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.
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.
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: