How to trigger Jenkins build from GitHub (and pass parameters)

Introduction

Integrating Jenkins with GitHub is a common practice for automating the build and deployment process in a continuous integration/continuous deployment (CI/CD) pipeline. This tutorial will guide you through setting up Jenkins to trigger a build automatically from a GitHub push and how to pass parameters to those builds for more dynamic and flexible automation.

Prerequisites:

• A Jenkins server set up and running.
• A GitHub account and a repository for which you have admin privileges.
• Jenkins plugins: GitHub plugin and Generic Webhook Trigger plugin (for more complex triggers).

Basic Setup: Triggering a Jenkins Build from a GitHub Push

First, we’ll cover the basics of triggering a Jenkins build from a GitHub push using webhooks.

Step 1: Configuring a Jenkins Job

1. Log in to your Jenkins dashboard and create a new freestyle job.
2. In the job configuration, navigate to the Source Code Management section and select Git. Enter your repository URL and credentials if necessary.
3. In the Build Triggers section, enable the option GitHub hook trigger for GITScm polling.

Step 2: Setting Up a Webhook in GitHub

1. Go to your GitHub repository settings, then to the Webhooks section, and click Add webhook.
2. In the Payload URL field, enter the URL of your Jenkins instance followed by /github-webhook/, for example, http://your-jenkins-server.com/github-webhook/. Select application/json for the content type, and leave the Secret field blank for this basic configuration.
3. Choose Just the push event for which events would trigger this webhook, then click Add webhook.

With these steps, any push to your GitHub repository will automatically trigger a Jenkins build.

Passing Parameters in a Jenkins Build

Moving beyond the basic setup, let’s discuss how to pass parameters through Jenkins builds initiated from GitHub.

Step 1: Creating a Parameterized Jenkins Job

1. In the job configuration, check the option This project is parameterized.
2. Click Add Parameter and select the type of parameter you wish to add (e.g., String Parameter).
3. Fill out the details of your parameter, such as Name and Default Value.

Step 2: Triggering the Build with Parameters from GitHub

To trigger a parameterized build from GitHub, you’ll need to use the Generic Webhook Trigger plugin.

1. Install the Generic Webhook Trigger Plugin in Jenkins.
2. In the configuration of your parameterized job, find the Generic Webhook Trigger section.
3. Set up the token, optional filters, and specify the Request parameters that will capture the values you wish to pass into your job.
4. In GitHub, adjust your webhook payload URL to include the token as a query parameter, e.g., http://your-jenkins-server.com/generic-webhook-trigger/invoke?token=YOUR_TOKEN.

Handling Dynamic Parameters and Complex Workflows

For more complex scenarios where you need dynamic parameters or need to handle different workflows based on the payload of the GitHub webhook, you can expand upon the previous steps with scripting within Jenkins or by utilizing additional plugins for processing JSON or XML payloads.

Example: Extracting Information from the Webhook Payload

jsonPath $.pull_request.head.sha

This code snippet illustrates how you can extract data, such as the SHA of a pull request head, directly from the webhook payload using the Generic Webhook Trigger plugin’s feature for parsing JSON.

Advanced Use Case: Combining Parameters and Conditional Builds

As your automation needs grow, you might find the need to not only pass parameters but also control the flow of your Jenkins jobs based on those parameters. This section explores how you can design jobs that proceed based on the values of input parameters or the context of the GitHub event.

Using Environment Variables in Scripted Pipelines

In a Jenkinsfile:

pipeline {
    agent any
    parameters {
        string(name: 'MY_PARAM', defaultValue: 'default', description: '')
    }
    stages {
        stage('Example') {
            steps {
                script {
                    if(env.MY_PARAM == 'value1') {
                        echo 'Performing steps for value1'
                    } else {
                        echo 'Default steps'
                    }
                }
            }
        }
    }
}

This shows how a Jenkins pipeline can use conditions based on passed parameters to dictate the behavior of the build process.

Conclusion

Integrating Jenkins with GitHub to trigger builds provides a powerful foundation for automating the software development process. By leveraging parameters, you can create more dynamic build processes that adapt to your project’s needs. With the basics of simple triggers to advanced parameter handling, your CI/CD pipeline can efficiently handle a wide range of scenarios, improving your deployment workflow and productivity.