Hero Image

Notifying Microsoft Teams in Jenkins pipelines


You can use Jenkins pipelines to programmatically notify Microsoft Teams channels during build steps.

In Microsoft Teams

  1. In Microsoft Teams, select the channel to be notified and then Connectors Manage channel
  2. Search for Jenkins and click Add Jenkins connector
  3. After that, configure the connector by giving it a unique name. Connector name
  4. Copy the Webhook URL. Webhook URL
  5. Click on Done

In Jenkins

  1. Below Manage Jenkins > Manage Plugins > Available search for Office 365 Connector and install the plug-in. Office365Connector plug-in
  2. Add a new credential with the webhook URL you have copied previously below Manage Jenkins > Manage Credentials > Jenkins scope (System) > Add credentials. As ID use something like MICROSOFT_TEAMS_NOTIFICATION_WEBHOOK.
  3. Use the following Jenkins pipeline definition:
def myWebhookUrl = 'unconfigured'

// inject credentials from Jenkins' credentials store.
withCredentials([string(credentialsId: 'MICROSOFT_TEAMS_NOTIFICATION_WEBHOOK', variable: 'INJECTED_TOKEN')]) {
    myWebhookUrl = INJECTED_TOKEN
}

pipeline {
    agent any

    options {
        office365ConnectorWebhooks([[
            startNotification: true,
            // see below; this is basically an security issue. You should consider to send custom notifications for the build events instead of setting the build configuration options.
            url: myWebhookUrl
        ]])
    }

    stages {
        stage('Send Microsoft Teams message') {
            steps {
                office365ConnectorSend webhookUrl: myWebhookUrl,
                    message: 'Hello world',
                    status: 'Info'
            }
        }

        stage('Send Microsoft Teams success message') {
            steps {
                office365ConnectorSend webhookUrl: myWebhookUrl,
                    message: 'This is a success message',
                    status: 'Success',            
                    color: '#00ff00'
            }
        }

        stage('Send Microsoft Teams failure message') {
            steps {
                office365ConnectorSend webhookUrl: myWebhookUrl,
                    message: 'This is a failure message',
                    status: 'Failure',
                    color: '#ff0000'
            }
        }

        stage('Send Microsoft Teams message with facts') {
            steps {
                office365ConnectorSend webhookUrl: myWebhookUrl,
                    // You can also send a message combined with facts
                    // message: 'facts',
                    // Facts and messages can be formatted with Markdown as described in https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format
                    factDefinitions: [[name: "row1", template: "content of __row1__ [test](https://google.com)"],
                    [name: "row2", template: "content of *row2*"]]            
            }
        }
    }
}

Notes

  • Mentioning Microsoft Teams users in a message (e.g. the original committer responsible for triggering the build) is not implemented.
  • Custom card actions are not implemented, see #237 and #258.
  • The webhook's URL is basically a secret. Everyone with knowledge of that URL can send messages to the Microsoft Teams channel. For custom messages when using the withCredentials([string...]) method, this is not a problem. But when using the normal build notifications (notify on starting or when a build failure occurred), through

    options {
        office365ConnectorWebhooks([[
          url: MY_URL
        ]])
    }

    the MY_URL parameter gets exposed to the Jenkins build configuration itself. Everyone with access to the build configuration has access to that token, too. There is an PR for this issue, but is has not been merged yet.