NAME
Git::MoreHooks::TriggerJenkins - Git::Hooks plugin to create and remove jobs from Jenkins
VERSION
version 0.018
SYNOPSIS
Use package via Git::Hooks interface (configuration in Git config file).
DESCRIPTION
This Git::Hooks plugin hooks itself to the hooks below to trigger a build in Jenkins for the current branch.
post-receive
This hook is invoked once for every branch in the remote repository after a successful
git push. It's used to trigger a build or builds in Jenkins.
This plugin will create a Jenkins job with the name of the pushed branch. This job will then be triggered. The job is configured so that an email is sent to the user (the pushing user) at the end of the run. If the job already exists at Jenkins, its parameters are not updated. It is only triggered again.
STATUS
Package Git::MoreHooks is currently being developed so changes in the existing hooks are possible.
USAGE
To enable this hook add it to the githooks.plugin configuration option:
git config --add githooks.plugin Git::MoreHooks::TriggerJenkinsREQUIREMENTS
Required additional dependencies:
These must be installed separately. They are not included as normal dependencies for Git::MoreHooks package because they are needed only by TriggerJenkins.
CONFIGURATION
The plugin is configured by the following git options.
githooks.triggerjenkins.ref REFSPEC
By default, all refs (branch names) are triggered. To trigger only some refs (usually some branch under refs/heads/), specify them with one or more instances of this option.
The refs can be specified as a complete ref name (e.g. "refs/heads/master") or by a regular expression starting with a caret (^), which is kept as part of the regexp (e.g. "^refs/heads/(master|common\/TICKET-[0-9]+)").
TODO: Apply environment var USER to refs regular expression.
githooks.triggerjenkins.base-url URL
Specifies the Jenkins server HTTP URL. Only the base, e.g. http://jenkins.company. Required.
githooks.triggerjenkins.api-key USERNAME
Specifies the Jenkins server username. Required.
githooks.triggerjenkins.api-token TOKEN
Specifies the Jenkins server access token. Required.
githooks.triggerjenkins.project KEY
If set use this Jenkins project instead of extracting the name from ref name and suffix in option job-template.
githooks.triggerjenkins.create-job [01]
# TODO Implement! If set to 0, only trigger build if the job already exists. If set to 1, create a new Jenkins job (project), unless it already exists). Default 1.
githooks.triggerjenkins.job-template JOBSUFFIX FILENAME
If set, contains the suffix of the Jenkins jobname and the template filename. Read the file as a Template Toolkit template file, and use it to create a new Jenkins job. The suffix and the filename are separated by space.
githooks.triggerjenkins.job-template-var KEY=VALUE
Define a key for value substitution in Jenkins job template. E.g.
[githooks "triggerjenkins"]
job-template-var = BUILD_DIR=/root/some/dir
job-template-var = AUTH2_TOKEN=1234567890abcdefggithooks.triggerjenkins.quiet [01]
If set to 1, do not print out anything to explain to user what was done. If set to 0, explain to user what was done and print out the link to the Jenkins job. Default 0.
githooks.triggerjenkins.force [01]
# TODO Implement! If set to 1, force a new build by cancelling the running build and scheduling a new. Default 0.
githooks.triggerjenkins.message-domain STRING
The domain name part of email or instant messager address, i.e. "domain.com" in <user.name@domain.com>. If not present, notification message address will not be configured into Jenkins job.
githooks.triggerjenkins.override-message-address REFSPEC STRING
If present this option will override the notification message address. A common setting would be to have branches like user.name/branch-name and these would be configured to send message to user.name@message-domain. Then this option would be configured to <Smaster all-dev@what.ever>. This option can be set multiple times. The branch name will be matched against all rows so several branch name combinations/regular expressions are possible.
githooks.triggerjenkins.allow-commit-msg REGEXP
If no commit message in the push matches this regular expression, then no build is triggered. This can be useful if the repository has often small configuration changes which need not or cannot be tested.
EXPORTS
This module exports routines that can be used directly without using all of Git::Hooks infrastructure.
handle_commit_at_client GIT
This is the routine used to implement the post-commit hook. It needs a Git::More object. TODO Finish!
handle_affected_refs GIT
This is the routine used to implement the post-receive hook. It needs a Git::More object for parameter.
SEE ALSO
REFERENCES
- This script is heavily inspired (and sometimes derived) from Gustavo Chaves' Git::Hooks::CheckJira.
NOTES
Thanks go to Gustavo Leite de Mendonça Chaves for his Git::Hooks package.
This hook first implemented for Cxense Sweden AB. Published to CPAN with Cxense Sweden AB's permission.
AUTHOR
'Mikko Koivunalho <mikkoi@cpan.org>'
COPYRIGHT AND LICENSE
This software is copyright (c) 2022 by Mikko Koivunalho.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.