Use Azure Pipelines with Microsoft Teams

Azure DevOps Services

The Azure Pipelines app for Microsoft Teams lets you monitor events for your pipelines. You can set up and get notifications in your Teams channel for releases, pending approvals, completed builds, and so on. You can also approve releases from within your Teams channel.

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. To learn more, see Azure DevOps Feature Timeline.

Prerequisites

  • You must have an Azure DevOps project. For more information, see Create a project.
  • To set up pipeline subscriptions, you must be a Project Administrator.

Set up the Azure Pipelines app

  1. In Microsoft Teams, go to the Apps store, search for Azure Pipelines, and then select Azure Pipelines.

    Screenshot of selecting the Apps button, then Azure Pipelines button.

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

    Screenshot of selecting Open button and then Add to a team button.

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

    Selecting the Set up a bot button.

  4. In the Teams conversation pane, enter @azurePipelines signin.

  5. Select Sign in and complete authentication to Azure Pipelines.

Use commands

Use the following commands to monitor all pipelines in a project or only specific pipelines.

  • Monitor all pipelines in a project. The URL can be to any page within your project, except URLs to pipelines. For example, @azure pipelines subscribe https://dev.azure.com/myorg/myproject/.

    @azure pipelines subscribe [project url]
    
  • Monitor a specific pipeline: The pipeline URL can be to any page within your pipeline that has a definitionId or buildId/releaseId present in the URL. For example, @azure pipelines subscribe https://dev.azure.com/myorg/myproject/_build?definitionId=123.

    @azure pipelines subscribe [pipeline url]
    

    Another example of a release pipeline that's subscribed to the Release deployment started, Release deployment completed, and Release deployment approval pending notifications is @azure pipelines subscribe https://dev.azure.com/myorg/myproject/_release?definitionId=123&view=mine&_a=releases.

Note

  • We don't support deployment approvals that have applied the Revalidate identity of approver before completing the approval policy.
  • Enable 'Third party application access via OAuth' to receive notifications for the organization in Azure DevOps.

Manage subscriptions

When you subscribe to a pipeline, a few subscriptions get created by default without any filters applied. You might want to customize these subscriptions. For example, you might want to get notified only when builds fail or when deployments get pushed to a production environment. The Azure Pipelines app supports filters to customize what you see in your channel. To manage your subscriptions, complete the following steps.

  1. Run the @azure pipelines subscriptions command.

  2. Select View all subscriptions. In the list of subscriptions, if there's a subscription you don't want, select Remove. View of list of subscriptions.

  3. Scroll down and select Add subscription.

  4. Select the required pipeline and event.

  5. Select the appropriate filters, and then Save.

    Example 1: Get notifications for failed builds.

    Visual of build failures in Teams.

    Example 2: Get notifications only if the deployments get pushed to the production environment.

    Visual of failure notification.

    Note

    • Team Administrators can't remove or modify subscriptions that are created by Project Administrators.
    • Notifications aren't supported inside chat/direct messages.

Approve deployments from your channel

You can approve deployments from within your channel without going to the Azure Pipelines portal. Subscribe to the Release deployment approval pending notification for classic Releases or the Run stage waiting for approval notification for YAML pipelines. Both of these subscriptions get created by default when you subscribe to the pipeline.

In Teams, notice ready for approval.

Whenever the running of a stage is pending for approval, a notification card with options to approve or reject the request gets posted in the channel. Approvers can review the details of the request in the notification and take appropriate action. In the following example, the deployment was approved and the approval status shows on the card.

Card showing approved deployment.

The Azure Pipelines app supports all of the checks and approval scenarios present in the Azure Pipelines portal. You can approve requests as an individual or for a team.

Search and share pipeline information using compose extension

To help users search and share information about pipelines, Azure Pipelines app for Microsoft Teams supports compose extension. You can now search for pipelines by pipeline ID or by pipeline name. For compose extension to work, users must sign in to the Azure Pipelines project that they're interested in either by running @azure pipelines signin command or by signing in to the compose extension directly.

Compose extension.

Previews of pipeline URLs

When you add a pipeline URL to Teams, you see a preview similar to the following images. The preview helps to keep pipeline-related conversations relevant and up-to-date. You can choose between compact and expanded cards.

Example 1: Build URL preview

Build URL unfurling.

Example 2: Release URL preview

Release URL unfurling.

Once you're signed in, this feature works for all channels in a team in Microsoft Teams.

Unsubscribe from a pipeline channel

Use the following command to unsubscribe from all pipelines within a project.

@azure pipelines unsubscribe all [project url]

Example: Unsubscribe all with URL

@azure pipelines unsubscribe all https://dev.azure.com/myorg/myproject

This command deletes all the subscriptions related to any pipeline in the project and removes the pipelines from the channel.

Important

Only Project Administrators can run this command.

Link a set of related notifications to reduce the space occupied by notifications in a channel. All notifications linked to a particular run of a pipeline get linked together.

Example 1: Compact view of linked notifications.

Compact thread

Example 2: Expanded view of linked notifications.

Expanded thread

Use commands in Azure Pipelines app

See the following commands supported by the Azure Pipelines app:

Slash command Functionality
@azure pipelines subscribe [pipeline url/ project url] Subscribe to a pipeline or all pipelines in a project to receive notifications
@azure pipelines subscriptions Add or remove subscriptions for this channel
@azure pipelines feedback Report a problem or suggest a feature
@azure pipelines help Get help on the slash commands
@azure pipelines signin Sign in to your Azure Pipelines account
@azure pipelines signout Sign out from your Azure Pipelines account
@azure pipelines unsubscribe all [project url] Remove all pipelines (belonging to a project) and their associated subscriptions from a channel

Connect multi-tenants

If you're using a different email or tenant for Microsoft Teams and Azure DevOps, do the following steps to sign in and connect based on your use case.

Use case Email ID & tenant in Microsoft Teams Email ID & tenant in Azure DevOps Sign in action
1 email1@abc.com (tenant 1) email1@abc.com (tenant 1) Select Sign in
2 email1@abc.com (tenant 1) email2@pqr.com (tenant 2) - Sign in to Azure DevOps.
- In the same browser, start a new tab and go to https://teams.microsoft.com/.
- Run the sign in command and select Sign in.
3 email1@abc.com (tenant 1) email2@pqr.com (tenant 2) - Select Sign in with different email address.
- In the email ID picker, use the email2 to sign in.
4 email1@abc.com (tenant 1) email2@pqr.com (non-default tenant 3) Currently not supported.

Troubleshoot

Sorry, something went wrong. Please try again.

The Azure Pipelines app uses the OAuth authentication protocol, and requires Third-party application access via OAuth for the organization to be enabled. To enable this setting, navigate to Organization Settings > Security > Policies, and set the Third-party application access via OAuth for the organization setting to On.

Enable the Third-party application access via OAuth for the organization setting

Configuration failed. Please make sure that the organization '{organization name}' exists and that you have sufficient permissions.

Sign out of Azure DevOps by navigating to https://aka.ms/VsSignout using your browser.

Open an In private or incognito browser window and navigate to https://aex.dev.azure.com/me and sign in. In the dropdown under the profile icon to the left, select the directory that contains the organization containing the pipeline for which you wish to subscribe.

Select the directory that contains the organization that contains the pipeline

In the same browser, start a new tab and sign in to https://teams.microsoft.com/. Run the @Azure Pipelines signout command and then run the @Azure Pipelines signin command in the channel where the Azure Pipelines app for Microsoft Teams is installed.

Select the Sign in button and you get redirected to a consent page like the one in the following example. Ensure that the directory shown beside the email is same as what you chose in the previous step. Accept and complete the sign in process.

Consent to the requested app permissions

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