Package and publish an integration to the Marketplace

TFS 2018

Do you have a tool, service, or product that integrates with Azure DevOps or Team Foundation Server (TFS)? If so, help users find it by publishing it on the Visual Studio Marketplace. The Marketplace is a one-stop-shop for individuals and teams to find tools that extend and enhance the experience.

Browse the Marketplace to see examples of other integrations and extensions.

Publishing requirements

The following list of requirements must be met before you publish to the Marketplace.

• Install the extension packaging tool (TFX). Run npm install -g tfx-cli from a command prompt.
• Ensure the proper permissions are granted to use any images, for example, icons, logos, screenshots, and so on.
• Include a thorough overview.md file to describe your listing in the Marketplace.
• Include an icon for your extension, which is at least 128x128 pixels in size.
• When you refer to Microsoft products, use full names in place of abbreviations, for example, Azure DevOps vs. AzDO or - any other abbreviation.
• Refrain from using brand names in the name of your extension.

What you need

1. 128x128 pixel logo (PNG or JPEG format) representing your integration, yourself, or your company/organization
2. Minimum of one screenshot showing your integration
3. Call to action / get started URL (where users should go to get started with your integration)

Steps

Publishing to the Marketplace is an iterative process that starts with creating a manifest file that defines your integration and key discovery characteristics (like screenshots, logos, and overview content). This information is used to present your integration to users on the Marketplace, for example:

Jenkins for Azure DevOps

Note: The term, extension, is used in documentations referenced below. Extensions are another type of Marketplace item and share many similarities from a discovery standpoint as integrations.

Create a publisher

All extensions and integrations, including extensions from Microsoft, have a publisher. Anyone can create a publisher and publish extensions under it. You can also give other people access to your publisher if a team is developing the extension.

A user owns the publisher, typically the user who created it. You can also share the publisher with other users.

1. Sign in to the Visual Studio Marketplace Publishing Portal.

2. If you're not already a member of an existing publisher, + Create a publisher. Enter a name in the publisher name field. The ID field should automatically get set based on the name you entered.

   

   Note

   Make note of the ID, as you need to set it in the manifest file of your extension.

   If you're not prompted to create a publisher, scroll down to the bottom of the page and select Publish extensions below Related sites.

   • Specify an identifier for your publisher, for example: mycompany-myteam. This identifier is used as the value for the publisher attribute in your extension manifest file.
   • Specify a display name for your publisher, for example: My Team

3. Review the Marketplace Publisher Agreement, and then select Create.

   

Once the publisher's created, you're directed to manage items, but there aren't any items.

Create a folder to contain your item manifest and other assets

Before you package your integration as an extension, you'll need to create a home folder to contain some required assets, within this folder:

1. Create a folder called images to contain:
   • Logo for your integration (128x128 pixels)
   • Screenshots (1366x768 pixels)
2. Create a file called overview.md
   • Describe your integration here
   • To learn more about Markdown, see GitHub Flavored Markdown
3. Create a file called vss-integration.json
   • This file is your Marketplace listing's manifest file, it contains many properties to describe your extension in your Marketplace listing. You can browse the extension manifest reference here

Extension Manifest

1. Fill your vss-integration.json file with the following JSON:

   {
       "manifestVersion": 1,
       "id": "myservice",
       "version": "1.0.0",
       "name": "My Service",
       "publisher": "mycompany",
       "description": "Awesome tools to help you and your team do great things everyday.",
       "targets": [
           {
               "id": "Microsoft.VisualStudio.Services.Integration"
           }
       ],    
       "icons": {
           "default": "images/service-logo.png"
       },
       "categories": [
           "Plan and track"
       ],
       "tags": [
           "working",
           "people person",
           "search"
       ],
       "screenshots": [
           {
               "path": "images/screen1.png"
           },
           {
               "path": "images/screen2.png"
           }
       ],
       "content": {
           "details": {
               "path": "overview.md"
           },
           "license": {
               "path": "fabrikam-license-terms.md"
           }
       },
       "links": {
           "getstarted": {
               "uri": "https://www.mycompany.com/help/getstarted"
           },
           "learn": {
               "uri": "https://www.mycompany.com/features"
           },
           "support": {
               "uri": "https://www.mycompany.com/support"
           }
       },
       "branding": {
           "color": "rgb(34, 34, 34)",
           "theme": "dark"
       }
   }
   

2. Update the JSON using the following reference:

These properties are required:

These optional properties help users discover and learn about your extension:

Details page

• 1 - description
• 2 - icon
• 3 - categories
• 4 - screenshots
• 5 - content (details)
• 6 - links
• 7 - branding

Package your manifest and assets

Get the package tool (tfx-cli)

You can install or update the Cross-platform CLI for Azure DevOps (tfx-cli) using npm, a component of Node.js, from your command line.

npm i -g tfx-cli

Package your integration in a .vsix file

tfx extension create --manifest-globs vss-extension.json

Publish your integration to the Marketplace

Once your extension is packaged, you can upload it to the Marketplace under a publisher. The publisher identifier specified in your extension's manifest file must match the identifier of the publisher the extension is uploaded under.

1. From the management portal, select your publisher from the drop-down menu at the top of the page.

2. Select New extension > Azure DevOps.

   

3. Drag and drop your file or select it to find your VSIX file, which you created in the previous packaging step, and then choose Upload.

   

   After quick validation, your extension appears in the list of published extensions. Don't worry, the extension is only visible to you.

   

At this point, your extension isn't visible to any accounts and can't be installed until you share it.

Share your integration

Before you can install an integration into an organization in Azure DevOps or TFS, you must share it with that organization. Sharing is a requirement during development and testing of an integration, as it's the only way to run an integration.

To share an integration do the following tasks:

1. Select an integration from the list of displayed items
2. Select the Share button
3. Specify the name of the organization to make this integration visible to.
   • For example, to make an integration visible to the dev.azure.com/fabrikam-fiber-inc organization, specify fabrikam-fiber-inc.

Update an item

To change an extension that's already published, update it.

1. Select an extension from the list of displayed items.
2. Right-click and select Update for the publisher.extension-dev, for example.
3. Validate your extension.
4. Make the same updates to the production version, publisher.extension, for example.
5. Browse to the .vsix for your extension and upload it.

The updated version of your extension automatically gets installed to accounts that have it already installed. New accounts where the extension is installed in the future also receive the latest version.

Make your integration public (visible to everyone)

For information on making your integration public, visit Make your listing public.