Pills: Pipeline decorators

Pipeline decorators are a really peculiar feature of Azure DevOps, because they allow you to specify a series of tasks that are run for EVERY pipeline in your organization, so they are rarely needed, but nevertheless they are a nice tool to know because there are situation when they are useful. Moreover, in latest Sprint 194 update they are expanded to support new functionalities, like running before or after specific tasks.

You have also a nice Msdn Article that explain how you can build your own decorator. That article references other tutorial so I wanted to give you a full example to go from zero to pipeline decorator with very few steps.

Before being able to create an extension you should go to https://marketplace.visualstudio.com/ and look for Publish Extension link https://marketplace.visualstudio.com/manage you need to login with a Microsoft account then request your account to be enabled for extension publishing). This step is mandatory because if you do not have an account enabled to publish on marketplace you will not be able to publish your extension.

Even if you are planning to develop a private extension (available only to your orgs) you need to have an account with publish permission on marketplace.

Once you can publish on the marketplace, it is time to author your pipeline decorator. The entire code for the decorator can be found in this simple github repository. As you can see the entire extension is really trivial, only three files are needed for the decorator to work. Readme.md is trivial, and the most important file is vss-extension.json that contains information about the addin. In that file there are some part you must change if you wanna reuse for your plugin.

• id: should be a unique value, string no space
• version: A Major.minor.build semver number, it is imperative that you always increment that value if you want to upgrade your addin.
• name and description: No need of further explanation
• publisher: Your publisher id as shown in marketplace: https://marketplace.visualstudio.com/manage/publishers/gianmariaricci
• public: false if you want this extension to be private and visible only to your orgs

The rest of the file is trivial, and you can find more detail on official documentation Msdn Article. The actual decorator you find in my repository simply declare a single decorator to run a task before all job finishes. You can change name of the files, change when your task should run and clearly change the content of the decorator. Once the extension is ready you can build with the tfx-cli utility

1

tfx extension create

This will create package file that is ready to be uploaded in marketplace. Once the extension was built, you need to upload in the marketplace so you can use in your organizations. Actually there is no simple way to avoid using marketplace, but it is really simple and probably it is the best way, because each time you upload a new version in your marketplace account every organization where you installed the extension will automatically update.

The only caveat is: if you specify public: false in vss-extension.json the extension is private, thus it is not installable by any organization unless you explicitly invite that organization to your extension. This is really nice because you can use the marketplace, but at the very same time you are also able not to release your extension publicly.

First step is creating a new extension in the marketplace.

Figure 1: Create a new extension in the Marketplace

Then you can simply drag and drop extension file generated by tfx utilities in the browser.

Figure 2: Upload the extension in the Marketplace

Now your extension will be validated and if everything is ok it will be published in the marketplace. If your extension is private, you cannot install in your orgs unless you explicitly invite them

Private extensions can be distributed in the marketplace, but you have full control on organizations that can install them.

Enabling organizations to use your private extension is simple, just invite them using the Share/Unshare button in the context menu of the extension.

Figure 3: Manage extension

Share/Unshare menu will open a dedicated section where you start listing all organization that can install your extension. Remember: if the extension is private, no organization can install it unless it is explicitly invited.

Figure 4: Sharing the extension

At this point the extension can be installed normally in all enabled organization, and as soon as you installed, decorators are immediately active. To verify that everything is ok just run any pipeline to verify that indeed at the end of the pipeline your decorator kicks in and append your task.

Figure 5: Decorator in action

With the recent update that allows a decorator to be injected only after specific tasks, decorators are a really nice and usefult tool to have in your belt when you work with Azure DevOps.

Gian Maria.