Implementing Build Notifications
1. Configuring Email Notifications
| Property | Value | Description |
|---|---|---|
| mailer.host | smtp.example.com |
SMTP server host for sending emails |
| mailer.port | 587 |
SMTP server port (typically 587 for TLS) |
| mailer.username | jenkins@example.com |
Username for SMTP authentication |
| mailer.password | secret |
Password for SMTP authentication |
| mailer.useTls | true |
Enable TLS encryption for SMTP connection |
Example: Email Configuration in Jenkinsfile
pipeline {
agent any
post {
always {
emailext (
subject: "Build ${currentBuild.result} - ${env.JOB_NAME}",
body: "Build URL: ${env.BUILD_URL}",
to: "team@example.com"
)
}
}
}
Note: Ensure that the SMTP settings are correctly configured in Jenkins System Configuration under "Manage Jenkins" > "Configure System".
2. Using Slack Notifications
| Property | Value | Description |
|---|---|---|
| jenkins.slack.webhook.url | https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX |
Webhook URL for Slack integration |
| jenkins.slack.channel | #build-notifications |
Slack channel to post build notifications |
| jenkins.slack.username | Jenkins CI |
Username to display in Slack messages |
Example: Configure Slack Notification in Jenkins Pipeline
pipeline {
agent any
stages {
stage('Build') {
steps {
echo 'Building...'
}
}
}
post {
always {
slackSend channel: '#build-notifications',
message: "Build ${env.BUILD_NUMBER} completed for project ${env.JOB_NAME}"
}
}
}
Note: Ensure the Jenkins Slack plugin is installed and configured with appropriate permissions.
Warning: Slack webhook URLs are sensitive and should be stored securely, not hardcoded in pipelines.
3. Using Microsoft Teams Webhooks
| Property | Value | Description |
|---|---|---|
| teams.webhook.url | https://outlook.office.com/webhook/... |
The incoming webhook URL for the Microsoft Teams channel |
| teams.message.title | Build Notification |
Title of the message sent to Teams |
| teams.message.text | Build ${BUILD_NUMBER} completed with status: ${BUILD_STATUS} |
Customizable message body |
Example: Configure Jenkins to send build notifications to Microsoft Teams
pipeline {
agent any
stages {
stage('Build') {
steps {
echo 'Building...'
}
}
}
post {
always {
script {
def webhookUrl = 'https://outlook.office.com/webhook/...'
def message = [
title: "Build ${env.BUILD_NUMBER} completed",
text: "Status: ${currentBuild.result}"
]
sh "curl -X POST -H 'Content-Type: application/json' -d '{\"title\":\"${message.title}\",\"text\":\"${message.text}\"}' ${webhookUrl}"
}
}
}
}
Note: Ensure the webhook URL is kept secure and not exposed in logs or public repositories.
Warning: Microsoft Teams webhooks are deprecated in favor of Connectors and Incoming Webhooks with updated security models.
4. Integrating with Jira
| Property | Value | Description |
|---|---|---|
| jira.url | https://your-jira-instance.com |
Base URL of the Jira instance |
| jira.project.key | PROJ |
Project key in Jira to associate with build |
| jira.issue.type | Bug |
Issue type to create in Jira (e.g., Bug, Task) |
| jira.username | jenkins-user |
Jira username for authentication |
| jira.api.token | api-token |
Jira API token for authentication |
Example: Configuring Jira Integration in Jenkins Pipeline
pipeline {
agent any
stages {
stage('Build') {
steps {
echo 'Building...'
}
}
}
post {
always {
script {
def jiraUrl = 'https://your-jira-instance.com'
def projectKey = 'PROJ'
def issueType = 'Bug'
def jiraUser = 'jenkins-user'
def apiToken = 'api-token'
// Example of updating Jira issue status
sh "curl -X PUT -H 'Content-Type: application/json' \
-u '${jiraUser}:${apiToken}' \
'${jiraUrl}/rest/api/3/issue/PROJ-123/transitions \
-d '{\"transition\": {\"id\": \"2\"}}'"
}
}
}
}
Note: Ensure the Jenkins user has appropriate permissions in Jira to update issues and create comments.
Warning: The Jira API token must be securely stored and not exposed in logs or configuration files.
5. Using GitHub Status API
| Property | Value | Description |
|---|---|---|
| github.status.api.url | https://api.github.com/repos/{owner}/{repo}/statuses/{sha} |
Endpoint to post build status to GitHub |
| github.status.context | jenkins/build |
Context identifier for the status |
| github.status.description | Build {buildNumber} completed |
Description of the build status |
Example: Post Build Status to GitHub
import org.jenkinsci.plugins.github.status.GitHubStatusPublisher
import hudson.model.Result
def status = new GitHubStatusPublisher(
context: "jenkins/build",
description: "Build ${env.BUILD_NUMBER} completed",
targetUrl: "${env.BUILD_URL}",
state: env.BUILD_STATUS == "SUCCESS" ? "success" : "failure"
)
status.publish()
Note: Requires
github-status-plugin to be installed and configured in Jenkins.
Warning: Ensure the
GITHUB_TOKEN is properly set in Jenkins credentials for API access.
6. Using GitLab Commit Status
| Property | Values | Description |
|---|---|---|
| gitlabCommitStatus.enabled | true / false |
Enable or disable GitLab commit status updates. |
| gitlabCommitStatus.context | string |
Context identifier for the status (e.g., ci/jenkins). |
| gitlabCommitStatus.description | string |
Description of the build status (e.g., Build in progress). |
| gitlabCommitStatus.targetUrl | string |
URL to the build result in Jenkins. |
Example: GitLab Commit Status Configuration
pipeline {
agent any
stages {
stage('Build') {
steps {
sh 'echo "Building..."'
}
}
}
post {
always {
gitlabCommitStatus(
enabled: true,
context: "ci/jenkins",
description: "Build completed",
targetUrl: "https://jenkins.example.com/job/myjob/123/"
)
}
}
}
Note: Requires the
GitLab Plugin to be installed and configured in Jenkins.
7. Sending Custom HTTP Notifications
| Property | Value | Description |
|---|---|---|
| httpNotification.url | https://example.com/webhook |
The target URL to send the HTTP POST request |
| httpNotification.method | POST |
HTTP method to use for the request (e.g., POST, PUT) |
| httpNotification.headers | {"Content-Type": "application/json"} |
Custom headers to include in the request |
| httpNotification.bodyTemplate | {"event": "${BUILD_STATUS}", "job": "${JOB_NAME}"} |
Template for the request body using Jenkins build variables |
Example: Configure Custom HTTP Notification
import jenkins.model.Jenkins
import hudson.model.listeners.BuildListener
def job = Jenkins.instance.getItemByFullName("my-job")
def notifier = new hudson.plugins.http_notification.HttpNotification(
"https://example.com/webhook",
"POST",
["Content-Type": "application/json"],
'{"event": "${BUILD_STATUS}", "job": "${JOB_NAME}"}'
)
job.getBuildersList().add(notifier)
Note: The
bodyTemplate supports Jenkins build variables like ${BUILD_STATUS}, ${JOB_NAME}, and ${BUILD_NUMBER}.
8. Using Build Badges
Build badges provide a visual indicator of a build's status directly in your project's README or documentation.
| Badge Type | URL Pattern | Description | Example |
|---|---|---|---|
| Build Status | https://jenkins.example.com/job/MyProject/build/badge.svg |
Shows the current build status (success, failure, etc.) | |
| Build Number | https://jenkins.example.com/job/MyProject/build/badge.svg?buildNumber=123 |
Displays the specific build number |
Example: Adding Build Badge to README.md
<img src="https://jenkins.example.com/job/MyProject/build/badge.svg" alt="Build Status">
Note: Ensure the Jenkins instance is accessible from the location where the badge will be displayed.
9. Configuring Notification Triggers
| Trigger | Description | Configuration | Notes |
|---|---|---|---|
| Build Triggers | Triggers that initiate a build based on external events | Build periodically, SCM polling, Upstream project |
Can be combined with other triggers |
| Build Periodically | Schedules builds at regular intervals using cron syntax | H/15 * * * * (every 15 minutes) |
Use H for load balancing |
| SCM Polling | Checks for changes in source control every specified interval | SCM: Poll SCM with Interval (e.g., 5 min) |
Can be slow; use Webhooks for faster response |
| Upstream Project | Triggers a build when an upstream project completes | Build after other projects are built |
Supports parameterized builds |
10. Using Rich Notification Templates
| Template Type | Description | Usage | Example |
|---|---|---|---|
| Jenkins Notification Template | Structured template for build notifications | Define in Jenkins UI or via configuration as code | {{#success}}Build succeeded!{{/success}} |
| HTML Template | Rich HTML-based notification format | Supports rich text, images, links | |
| JSON Template | Structured JSON payload for external services | Used with Webhook or Slack plugins | { "build": "{{buildNumber}}", "status": "{{status}}" } |
Example: Slack Notification with HTML Template
def slackMessage = """
<div class="slack-notification">
<h3>Build {{buildNumber}}</h3>
<p>Status: <strong>{{status}}</strong></p>
<p>Duration: {{duration}}</p>
</div>
"""
Note: Templates can be customized using Jenkins' built-in variables and plugins like
Template Plugin.
Warning: Ensure HTML templates are sanitized to prevent XSS vulnerabilities.