Coffee Talk: Java, News, Stories and Opinions
BLOG

How to implement a remote Jenkins build trigger with a URL

Cameron McKenzie
Cameron McKenzie
TechTarget

The ability to implement a remote Jenkins build trigger is a common requirement for many continuous integration and continuous delivery pipelines. Not surprisingly, this capability is baked into every Jenkins job you create.

However, developers need to click the right buttons in the Jenkins admin console to enable the trigger, and provide the correct credentials to not encounter a 403 error.

Create a remote Jenkins build trigger in three steps

Developers can follow these three steps to implement a remote Jenkins build trigger:

  1. Create a Jenkins build job and enable the Trigger builds remotely checkbox.
  2. Provide an authentication token; This can be any text string of your choice.
  3. Invoke the Jenkins build URL to remotely trigger the build job.
    • Note: A username and password are required to avoid a 403 error
remote build trigger jenkins example

This remote build trigger in Jenkins example sets abc-123 as the secret token.

Avoid remote Jenkins build 403 errors

Developers will need to provide someone’s username and password with rights to invoke the Jenkins build job to avoid a 403 error. They can accomplish this by prepending the username and password to the URL.

http://user:[email protected]/job/RemoteTriggerExample/build?token=abc-123

However, any network sniffer can see these unencrypted credentials. In a production facility, you’ll be required to use SSL and HTTPS.

Your intro to GitHub Actions training course

Here’s how to get started with GitHub Actions:

Follow these tutorials to learn GitHub Actions fast.

Test a remote Jenkins build trigger

There are multiple ways to test a remote Jenkins build trigger. The easiest way is to paste the remote Jenkins build trigger URL into a web browser’s address bar. Once this is done, a developer will see a new build initiated in the Jenkins console.

Another way is by script. A developer can invoke the following CURL command to test the build URL:

$ curl -I http://user:[email protected]/job/RemoteTriggerExample/build?token=abc-123

Jenkins and the Java HttpClient

For even more control over how and when a remote Jenkins build job is triggered, a full stack developer might want to invoke the build URL as part of a Java or Groovy program. Use the following code to invoke a Jenkins build in Java through the HttpClient class:

package com.mcnz.jenkins;

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpResponse.BodyHandlers;

/* Trigger builds remotely in JenkinsCI with Java Example */
public class JenkinsTrigger {

  public static void main(String[] args) throws Exception {
    /* Prepend credentials to fix the Jenkins remote build 403 error */
    String JENKINS_URL = "http://user:[email protected]/job/RemoteTriggerExample/build?token=abc-123";
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create(JENKINS_URL)).build();
    HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
    System.out.println(response.toString());
  }
}

Jenkins and GitHub remote build triggers

However, one way that developers shouldn’t use is GitHub. If a developer uses GitHub to invoke a Jenkins job it will result in the following error:

403 No valid crumb was included in the request

You can work around this program, however. Install the Jenkins GitHub plugin and use the Jenkins GitHub webhook to integrate Jenkins and GitHub.