Jenkins Integration with Microsoft Teams

CI/CD is an essential tool for modern software development teams. Automated pipelines hosted by servers such as Jenkins perform consistent tests, security analysis, and deployments each time your code changes. However, a common challenge with CI/CD is a lack of visibility into the pipeline’s status, which can leave you manually checking whether builds have completed.

Integrating your continuous integration environment with your collaboration platform can notify you as soon as build failures, new deployments, and test reports are available. In this article, you’ll learn how to integrate Jenkins with Microsoft Teams by setting up the Office 365 Connector plugin. We’ll assume you’ve already got access to a Jenkins server and Microsoft Teams account.

Setting Up Teams

Begin by creating a new Teams channel to receive your Jenkins alerts. This step is optional; feel free to skip it and use an existing channel if you prefer.

Create a new channel by clicking the three-dots icon next to your team’s name, then selecting Add channel from the menu:

Use the dialog box that appears to name your channel and choose its privacy level:

After you’ve created your channel, click the Apps button at the bottom of the Teams sidebar. Use the search bar that appears in the top left to find the Incoming Webhook app. Webhooks are URLs that external applications like Jenkins can use to send data to Teams:

Click the result that appears and then press the Add to a team button:

Use the dropdown to select the channel you created earlier, then press the Set up a connector button in the bottom right:

The connector creates a new webhook URL for your Teams channel (make sure to keep this URL secured as anyone having this url can send messages to your teams account). Name your connector in the dialog box that appears, then click the purple Create button at the bottom:

Copy the webhook URL that’s displayed on the following screen—this will be used to set up Jenkins in the next step:

Press the Done button to complete the webhook setup.

Setting Up Jenkins

Log in to your Jenkins server and click the Manage Jenkins link in the left sidebar:

Choose the Manage Plugins tile on the following screen:

Switch to the Available Plugins page from the menu on the left, then use the search bar to find the Office 365 Connector plugin. Select its checkbox and press Install without restart at the bottom of the screen:

After the plugin has installed, return to Dashboard > Manage Jenkins and press the Configure System tile:

Scroll down until you find the Office 365 Connector heading. This is where you provide the plugin’s default settings. Paste the webhook URL you copied from Teams into the URL input here. You can optionally name your connector using the Name input:

These values can be overridden on a per-project basis. Setting up defaults here ensures Teams integration will be automatically enabled, even when you don’t manually configure your projects.

Running a Test Build

Return to the Jenkins home screen. Click the New Item button in the top left to create a new empty project for testing your integration:

Select the Freestyle project item type and enter a name, then press the blue OK button at the bottom of the screen:

The Configure page will appear. Scroll down to the Office 365 Connector heading and press the Add Webhook button to enable the Teams integration:

You can use the default webhook URL you set above or enter a different value for this job:

Next, scroll down to the Build Steps header near the bottom of the page. Click the Add build step button and choose Execute shell from the menu:

Enter a simple command for your job to run, such as a basic echo “Job complete”:

Finally, press the blue Save button at the bottom of the screen. You’ll be taken to your project’s overview page. Click the Build Now link in the menu on the left:

After a few seconds, the Build History panel in the bottom left should update to report a successful job. You’ll also receive a message in your Microsoft Teams channel:

Setting the Build Statuses That Send Messages

By default, you’ll receive a Teams message for the failed, successful, unstable, and “back to normal” build statuses. You can customize this selection by pressing the Advanced button when you’re configuring webhook settings for a job:

Use the checkboxes to choose the build statuses that will trigger a notification. You’ll get a message in Teams each time the job transitions into one of the selected statuses. The following options are available:

• Notify Build Start – A new run has begun.
• Notify Aborted – A run has been canceled.
• Notify Failure – The run failed.
• Notify Not Built – The run did not produce any build output.
• Notify Success – The run completed successfully, creating a new build.
• Notify Unstable – The build became unstable.
• Notify Back To Normal – A new run completed successfully after a previous failure.
• Notify Repeated Failure – Multiple failures have occurred in succession.

Press the Save button at the bottom of the screen once you’ve finished making changes.

Configuring Connectors in a Groovy Pipeline

You can configure the connector within your pipeline scripts. Here’s a simple pipeline that sends a message for successful and failed builds:

pipeline {

	agent any

	options {
		office365ConnectorWebhooks([[
			name: "My Connector",
			startNotification: true,
			url: "https://outlook.office.com/webhook/...",
			notifyFailure: true,
			notifySuccess: true
		]])
	}

	stages {
		stage("Build") {
			steps {
				echo "Complete!"
			}
		}
	}

}

Add your own webhook URL to the url field in the pipeline. Omitting the field will use the global value set in your plugin’s configuration.

Try copying the example into a new Jenkins pipeline. Click New Item on your dashboard, add a Pipeline item, and then switch to its Configure > Pipeline screen. Paste in the script and press the Save button:

Back on the pipeline’s overview page, click Build Now to run the script:

You’ll receive another message in your Teams channel:

Sending Custom Messages to Teams

The connector can also be used to send arbitrary messages to your Teams channel. use the office365ConnectorSend function in your pipeline to immediately send a new notification:

pipeline {

	agent any

	stages {
		stage("Build") {
			steps {
				office365ConnectorSend webhookUrl: "https://outlook.office.com/webhook/...",
					message: "Job ${env.JOB_NAME} completed!",
					status: "Success"
			}
		}
	}

}

The message parameter sets the text that will be shown in Teams. You can reference Jenkins variables within it, as shown by the job name reference in the example above:

The office365ConnectorSend function can be configured to send to a specific channel by setting its webhookUrl parameter. Omitting the parameter will result in the use of the closest available webhook, either at the pipeline or global level.

Conclusion

The Office 365 Connector plugin lets you send messages to Microsoft Teams as jobs change status on your Jenkins server. This provides visibility into CI/CD activity so you can work more efficiently, without manually checking for failed and successful builds. You can configure the connector for the build statuses you’re interested in, or send custom messages as part of your pipeline scripts.