Package and publish an integration to the Marketplace

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

This article explains how to publish your tool, service, or product that integrates with Azure DevOps on the Visual Studio Marketplace. Publishing on the Marketplace helps users discover solutions that extend and enhance their Azure DevOps experience. The Marketplace serves as the central hub for individuals and teams to find integrations and extensions.

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

Prerequisites

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

Gather required assets

• At least one screenshot of your integration.
• Call-to-action or get started URL for users.

Create a publisher account

Every extension or integration, including those from Microsoft, must have a publisher. Anyone can create a publisher and publish extensions under it. You can also share publisher access with other users, such as your development team.

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

2. If you aren't part of an existing publisher, select + Create a publisher.
   Enter a publisher name; the ID field autofills based on your entry.

   

   Note

   • Ensure your publisher name is within 16 characters for multibyte characters.
   • Save the publisher ID—you need it in your extension's manifest file.

   If you aren't prompted to create a publisher, scroll to Publish extensions under Related sites.

   • Set a unique publisher identifier, such as mycompany-myteam. Use this value for the publisher attribute in your manifest.
   • Set a display name, such as My Team.

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

   

After you create the publisher, you can manage items, although no items appear until you publish.

Organize your manifest and assets

To organize your manifest and assets, do the following steps:

1. Create a home folder to store required assets.
2. Create an images folder for:
   • Your integration logo (128x128 pixels)
   • Screenshots (1366x768 pixels)
3. Create an overview.md file to describe your integration. For more information, see GitHub Flavored Markdown.
4. Create a vss-integration.json file, which is your Marketplace listing's manifest file. For more information, see the extension manifest reference.

Complete the extension manifest

Publishing to the Marketplace starts with creating a manifest file that defines your integration and its key discovery details (screenshots, logos, overview content). This information is used to present your integration to users on the Marketplace.

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 references:

The following properties are required:

The following optional properties help users discover and learn about your extension:

Understand the details page

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

Package your manifest and assets

Install the package tool (tfx-cli)

Install or update the cross-platform CLI for Azure DevOps (tfx-cli) using npm:

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. To make it visible to others, you need to share the extension.

Share your integration

Before installing an integration in an Azure DevOps organization, share it with that organization. Sharing is required for development and testing, as it's the only way to run an integration during these stages.

To share an integration do the following steps:

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 update an extension you already published, do the following steps:

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

Azure DevOps automatically installs the updated version for all accounts that already have the extension. New installations also receive the latest version.

Make your integration public

For information on making your integration visible to everyone, see Make your listing public.