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
injenkins.war
-
WEB-INF/HOOK.groovy.d/*.groovy
in the lexical order injenkins.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.