Groovy Hook Scripts

This section is a work in progress. Want to help? Check out the jenkinsci/docs gitter channel. For other ways to contribute to the Jenkins project, see this page about participating and contributing.

In several places inside Jenkins, a series of "hook scripts" get executed to allow some actions to take place in reaction to some key events.

These scripts are written in Groovy, and get executed inside the same JVM as Jenkins, allowing full access to the domain model of Jenkins. For given hook HOOK, the following locations are searched:

WEB-INF/HOOK.groovy in jenkins.war
WEB-INF/HOOK.groovy.d/*.groovy in the lexical order in jenkins.war
$JENKINS_HOME/HOOK.groovy
$JENKINS_HOME/HOOK.groovy.d/*.groovy in the lexical order

HOOK.groovy.d is suitable to avoid conflicts — multiple entities can insert stuff into the hook without worrying about overwriting each other’s code.

The following events use this mechanism by replacing HOOK in HOOK.groovy.d or HOOK.groovy by one of the below mentioned types:

init: Post-initialization script
boot-failure: Boot failure hook

Post initialization script (init hook)

You can create a Groovy script file $JENKINS_HOME/init.groovy, or any .groovy file in the directory $JENKINS_HOME/init.groovy.d/, to run some additional things right after Jenkins starts up. The groovy scripts are executed at the end of Jenkins initialization. This script can access classes in Jenkins and all the plugins. So for example, you can write something like:

import jenkins.model.Jenkins;

// start in the state that doesn't do any build.
Jenkins.instance.doQuietDown();

Output is logged to the Jenkins log file. For Debian based users, this is /var/log/jenkins/jenkins.log

If you are using the Jenkins Docker image, $JENKINS_HOME/init.groovy.d/ does not exist. Instead, you should place the Groovy script files in /usr/share/jenkins/ref/init.groovy.d/, as this directory is copied when the Docker container starts. For more details, refer to the Installing more tools documentation.

Boot failure hook

When Jenkins encounters a fatal problem during boot, it’ll invoke "boot-failure" hook script to allow automatic corrective actions to be taken (such as notifying somebody, raising alerts, restarting, and so on.)

These scripts get the cause of the problem as the "exception" variable when run.

User Handbook

Tutorials

Resources

Groovy Hook Scripts

Post initialization script (init hook)

Boot failure hook