Groovy Hook Scripts

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

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

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.