Use Azure Boards in Microsoft Teams

Azure DevOps Services

This article describes how to use the Azure Boards and Azure DevOps apps for Microsoft Teams to create and monitor Azure Boards work items from your Teams channels.

Note

This feature is only available on Azure DevOps Services. Typically, new features are introduced in the cloud service first, and then made available on-premises in the next major version or update of Azure DevOps Server. For more information, see Azure DevOps Feature Timeline.

By using the Azure Boards app for Microsoft Teams, you can:

• Set up subscriptions to create and manage work items and work item events in your Teams channels.
• Create work items directly from channel conversations.
• Search for and share work items across channels using the messaging extension.
• View previews of work items from URLs.

Note

• Azure Boards notifications aren't supported inside Teams chat or direct messages.
• The Azure Boards app for Microsoft Teams isn't supported for O365 Government Community Cloud (GCC) customers that use an Azure Commercial subscription in conjunction with a GCC tenant.

Prerequisites

• Permissions: Be a member of the Project Administrators group or Team Administrators group for your project.
• Policies: Enable the Third party application access via OAuth policy.
• Access: Have access to a team and channel in Microsoft Teams where you can install an app.

Add the Azure Boards app to Teams

To add the Azure Boards app to your Teams channels, do the following steps.

1. In Microsoft Teams, select Apps, search for Azure Boards, and then select Azure Boards.

   

2. Select the dropdown arrow next to Open, and select Add to a team.

   

3. Select or enter your team name, and then select Set up a bot.

   

After the app installs, you see a welcome message in the Teams conversation pane.

Azure Pipelines app commands

You can use the following @azure boards commands to interact with the Azure Boards app in your Teams channel.

Command	Functionality
@azure boards sign in	Sign in to your Azure Boards organization.
@azure boards sign out	Sign out from your Azure Boards organization.
@azure boards link <project url>	Link a project to this channel to create work items and receive notifications.
@azure boards unlink	Unlink a project from this channel.
@azure boards subscriptions	Add or remove subscriptions for this channel.
@azure boards addAreapath <area path>	Add an area path from your project to this channel.
@azure boards feedback	Report a problem or suggest a feature.
@azure boards help	Get help on the commands.

Link your Azure Boards project to the app

To use the app, sign in to Azure Boards and link your Azure Boards project to your Teams channel.

1. In the Teams conversation pane, enter @azure boards signin.

2. Select Sign in and complete authentication to Azure Boards. Select Sign in with different email if your Microsoft Teams and Azure Boards are in different tenants.

3. Use the @azure boards link command to link to your Azure DevOps project URL. For example:

   @azure boards link https://dev.azure.com/myorg/myproject/
   

4. Select the Add subscription button in the linked project notification to start monitoring your project.

   

Set up subscriptions

After your project is linked, begin monitoring project work items by selecting the Add subscription button. You can add more subscriptions anytime by using the @azure boards subscriptions command.

1. Under Choose event, select the event you want to subscribe to and select Next.

   

2. Under Choose filters, select the Area path, Work item type, and optionally specify Tags or a specific string to filter on, and then select Submit.

   

Add area paths

Area paths that have subscriptions in the channel, recently accessed area paths, and area paths that you add by using the @azure boards addAreapath command appear in the Area path dropdown menu when you create a subscription. If the area path that your team works on doesn't appear in the dropdown menu, you can add it so that it's always available for creating work items and subscriptions. This feature is especially useful for teams with more than 100 area paths in their project.

Use the @azure boards addAreapath command to add area paths from your project to the Teams channel. For example:

@azure boards addAreapath 'VMdemo\Area4'

You get a success message.

If you choose the project name as your area path, you get notifications for all the area paths in the project.

Create work items

You can use the Azure Boards app to create work items from your channel by using a message action.

1. In any message in the channel, select the More actions ellipse in the actions panel, and then select Create work item.

   

2. Select the type of work item you want to create, and select Next.

3. Enter a Title and select an Area path for the work item.

4. The text of the message becomes the work item Description or Repro Steps, depending on work item type, or you can edit this text. Select Create.

   

The new work item appears in Azure Boards and contains a link back to the Teams item that generated the work item.

Manage Azure Boards subscriptions

To view, add, and remove subscriptions for a channel, use the @azure boards subscriptions command. This command lists all the current subscriptions for the channel. You can add new subscriptions and remove existing ones. When you add a subscription, you can customize notifications by using filters.

Note

Team Administrators can't remove or modify subscriptions that Project Administrators created.

Use the compose extension

To help you search for and share work items, the Azure Boards app for Microsoft Teams supports the compose extension. You can search for work items by work item ID, title, or supported functional command. For a list of supported commands, see Functional work item search.

To use the compose extension, be signed in to the Azure Boards project in the Teams channel. Select the + symbol in the message field, select Azure Boards, and then search for a work item. You can also select Create work item to create a new work item.

Preview work items

To support collaboration around work items you discuss in a channel, the Azure Boards app displays a preview of work items you reference. When you paste in a work item URL or select a work item from the compose extension, the app shows a preview similar to the following image. This URL unfurling feature works for all channels in the team.

Unlink a project from a channel

A Teams channel can link to only one Azure Boards project at a time. To link to a different project, you must first unlink the current project by using @azure boards unlink.

Unlinking a project deletes all the project subscriptions and added area paths from the channel. If the channel has no subscriptions, any user can unlink a project. If the channel has subscriptions, only Project Administrators can unlink the project.

Expand and collapse threads

A Teams channel collapses posts in threads to logically link and reduce related posts in the channel. All replies to a particular post are linked together.

To expand the thread, select the compacted thread link.

To return to the channel and collapse the thread, select Go to channel.

Configure Azure DevOps tabs

To bring your project dashboard or Kanban board into Teams, you can install the Azure DevOps app in a tab in your Teams channel. The Azure DevOps app lets you insert content from the app in messages, and get notifications from the app in your channels.

1. In Teams, select the + symbol on the top navigation of your channel or select Apps from the left menu.

2. Search for if necessary, and then select Azure DevOps.

   

3. Select and sign in to your Azure DevOps organization.

4. On the Azure DevOps screen, select a Project, and whether to add a Dashboard or a Kanban board to the tab. Select other configurations depending on your choice, and select whether you want to post to the channel about adding the tab.

   

5. Select Save. The new tab and board appear in your channel.

Connect different tenants

If you use different emails or tenants for Microsoft Teams and Azure DevOps, follow these steps to sign in and connect based on your settings.

Microsoft Teams	Azure DevOps	Sign in action
email1@abc.com (tenant1)	email1@abc.com (tenant1)	Select Sign in
email1@abc.com (tenant1)	email2@abc.com (tenant2)	1. Sign in to Azure DevOps. 2. In the same browser, start a new tab and go to https://teams.microsoft.com/. 3. Run the sign in command and select Sign in.
email1@abc.com (tenant1)	email2@pqr.com (tenant2)	1. Select Sign in with different email address. 2. In the email ID picker, use the email2 to sign in.
email1@abc.com (tenant1)	email2@pqr.com (nondefault tenant3)	Not supported.

Troubleshoot authentication issues

If you receive the error Configuration failed. Please make sure that the organization '{organization name}' exists and that you have sufficient permissions, try the following steps to resolve the error.

1. In the same browser, start a new tab and sign in to https://teams.microsoft.com/.

2. In this tab, go to the channel where the Azure Boards app for Microsoft Teams is installed and run the @azure boards signout command and then the @azure boards signin command.

3. Select the Sign in button, and complete the sign-in process. Ensure that the directory shown is the same one you chose in the previous step.

If these steps don't resolve your authentication issue, reach out to the Developer Community.

Related articles

• Define area paths and assign to a team
• Use Azure Pipelines with Microsoft Teams
• Use Azure Repos with Microsoft Teams