Skip to main content

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 Status Badge
Build Number https://jenkins.example.com/job/MyProject/build/badge.svg?buildNumber=123 Displays the specific build number Build Number Badge

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

Example: Build Periodically Configuration

H/15 * * * *

Example: SCM Polling Configuration

SCM: Poll SCM
Interval: 5 min

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
<div class="notification">
  <h3>Build {{buildNumber}}</h3>
  <p>Status: {{status}}</p>
</div>
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.

Template Configuration Options

  • Build Status: success, failure, unstable, aborted
  • Build Variables: buildNumber, duration, timestamp
  • Custom Fields: author, commit, branch

Was this article helpful?