.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Jenkins::API 3pm" .TH Jenkins::API 3pm "2023-05-23" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Jenkins::API \- A wrapper around the Jenkins API .SH "VERSION" .IX Header "VERSION" version 0.18 .SH "SYNOPSIS" .IX Header "SYNOPSIS" This is a wrapper around the Jenkins \s-1API.\s0 .PP .Vb 1 \& use Jenkins::API; \& \& my $jenkins = Jenkins::API\->new({ \& base_url => \*(Aqhttp://jenkins:8080\*(Aq, \& api_key => \*(Aqusername\*(Aq, \& api_pass => \*(Aqapitoken\*(Aq, \& }); \& my $status = $jenkins\->current_status(); \& my @not_succeeded = grep { $_\->{color} ne \*(Aqblue\*(Aq } @{$status\->{jobs}}; \& # { \& # \*(Aqcolor\*(Aq => \*(Aqred\*(Aq, \& # \*(Aqname\*(Aq => \*(AqTest\-Project\*(Aq, \& # \*(Aqurl\*(Aq => \*(Aqhttp://jenkins:8080/job/Test\-Project/\*(Aq, \& # } \& \& my $success = $jenkins\->create_job($project_name, $config_xml); \& ... .Ve .SS "\s-1ATTRIBUTES\s0" .IX Subsection "ATTRIBUTES" Specify these attributes to the constructor of the \f(CW\*(C`Jenkins::API\*(C'\fR object if necessary. .SS "base_url" .IX Subsection "base_url" This is the base url for your Jenkins installation. This is commonly running on port 8080 so it's often something like http://jenkins:8080 .SS "api_key" .IX Subsection "api_key" This is the username for the basic authentication if you have it turned on. .PP If you don't, don't specify it. .PP Note that Jenkins returns 403 error codes if authentication is required but hasn't been specified. A common setup is to allow build statuses to be read but triggering builds and making configuration changes to require authentication. Check \*(L"response_code\*(R" after making a call that fails to see if it is an authentication failure. .PP .Vb 12 \& my $success = $jenkins\->trigger_build($job_name); \& unless($success) \& { \& if($jenkins\->response_code == 403) \& { \& print "Auth failure\en"; \& } \& else \& { \& print $jenkins\->response_content; \& } \& } .Ve .SS "api_pass" .IX Subsection "api_pass" The \s-1API\s0 token for basic auth. Go to the Jenkins wiki page on authenticating scripted clients for information on getting an \s-1API\s0 token for your user to use for authentication. .SH "METHODS" .IX Header "METHODS" .SS "check_jenkins_url" .IX Subsection "check_jenkins_url" Checks the url provided to the \s-1API\s0 has a Jenkins server running on it. It returns the version number of the Jenkins server if it is running. .PP .Vb 2 \& $jenkins\->check_jenkins_url; \& # 1.460 .Ve .SS "current_status" .IX Subsection "current_status" Returns the current status of the server as returned by the \s-1API.\s0 This is a hash containing a fairly comprehensive list of what's going on. .PP .Vb 10 \& $jenkins\->current_status(); \& # { \& # \*(AqassignedLabels\*(Aq => [ \& # {} \& # ], \& # \*(Aqdescription\*(Aq => undef, \& # \*(Aqjobs\*(Aq => [ \& # { \& # \*(Aqcolor\*(Aq => \*(Aqblue\*(Aq, \& # \*(Aqname\*(Aq => \*(AqJenkins\-API\*(Aq, \& # \*(Aqurl\*(Aq => \*(Aqhttp://jenkins:8080/job/Jenkins\-API/\*(Aq \& # }, \& # \*(Aqmode\*(Aq => \*(AqNORMAL\*(Aq, \& # \*(AqnodeDescription\*(Aq => \*(Aqthe master Jenkins node\*(Aq, \& # \*(AqnodeName\*(Aq => \*(Aq\*(Aq, \& # \*(AqnumExecutors\*(Aq => 2, \& # \*(AqoverallLoad\*(Aq => {}, \& # \*(AqprimaryView\*(Aq => { \& # \*(Aqname\*(Aq => \*(AqAll\*(Aq, \& # \*(Aqurl\*(Aq => \*(Aqhttp://jenkins:8080/\*(Aq \& # }, \& # \*(AqquietingDown\*(Aq => bless( do{\e(my $o = 0)}, \*(AqJSON::XS::Boolean\*(Aq ), \& # \*(AqslaveAgentPort\*(Aq => 0, \& # \*(AquseCrumbs\*(Aq => $VAR1\->{\*(AqquietingDown\*(Aq}, \& # \*(AquseSecurity\*(Aq => $VAR1\->{\*(AqquietingDown\*(Aq}, \& # \*(Aqviews\*(Aq => [ \& # { \& # \*(Aqname\*(Aq => \*(AqAll\*(Aq, \& # \*(Aqurl\*(Aq => \*(Aqhttp://jenkins:8080/\*(Aq \& # } \& # ] \& # } .Ve .PP It is also possible to pass two parameters to the query to refine or expand the data you get back. The tree parameter allows you to select specific elements. The example from the Jenkins documentation , \f(CW\*(C`tree=> \*(Aqjobs[name],views[name,jobs[name]]\*(Aq\*(C'\fR demonstrates the syntax nicely. .PP The other parameter you can pass is depth, by default it's 0, if you set it higher it dumps a ton of data. .PP .Vb 9 \& $jenkins\->current_status({ extra_params => { tree => \*(Aqjobs[name,color]\*(Aq }});; \& # { \& # \*(Aqjobs\*(Aq => [ \& # { \& # \*(Aqcolor\*(Aq => \*(Aqblue\*(Aq, \& # \*(Aqname\*(Aq => \*(AqJenkins\-API\*(Aq, \& # }, \& # ] \& # } \& \& $jenkins\->current_status({ extra_params => { depth => 1 }}); \& # returns everything and the kitchen sink. .Ve .PP It is also possible to only look at a subset of the data. Most urls you can see on the website in Jenkins can be accessed. If you have a job named Test-Project for example with the url \f(CW\*(C`/job/Test\-Project\*(C'\fR you can specify the \f(CW\*(C`path_parts => [\*(Aqjob\*(Aq, \*(AqTest\-Project\*(Aq]\*(C'\fR to look at the data for that job alone. .PP .Vb 6 \& $jenkins\->current_status({ \& path_parts => [qw/job Test\-Project/], \& extra_params => { depth => 1 }, \& }); \& # just returns the data relating to job Test\-Project. \& # returning it in detail. .Ve .PP The method will die saying 'Invalid response' if the server doesn't respond as it expects, or die with a \s-1JSON\s0 decoding error if the \s-1JSON\s0 parsing fails. .SS "get_job_details" .IX Subsection "get_job_details" Returns detail about the job specified. .PP .Vb 10 \& $job_details = $jenkins\->get_job_details(\*(AqTest\-Project\*(Aq); \& # { \& # \*(Aqactions\*(Aq => [], \& # \*(Aqbuildable\*(Aq => bless( do{\e(my $o = 0)}, \*(AqJSON::PP::Boolean\*(Aq ), \& # \*(Aqbuilds\*(Aq => [], \& # \*(Aqcolor\*(Aq => \*(Aqdisabled\*(Aq, \& # \*(AqconcurrentBuild\*(Aq => $VAR1\->{\*(Aqbuildable\*(Aq}, \& # \*(Aqdescription\*(Aq => \*(Aq\*(Aq, \& # \*(AqdisplayName\*(Aq => \*(AqTest\-Project\*(Aq, \& # \*(AqdisplayNameOrNull\*(Aq => undef, \& # \*(AqdownstreamProjects\*(Aq => [], \& # \*(AqfirstBuild\*(Aq => undef, \& # \*(AqhealthReport\*(Aq => [], \& # \*(AqinQueue\*(Aq => $VAR1\->{\*(Aqbuildable\*(Aq}, \& # \*(AqkeepDependencies\*(Aq => $VAR1\->{\*(Aqbuildable\*(Aq}, \& # \*(AqlastBuild\*(Aq => undef, \& # \*(AqlastCompletedBuild\*(Aq => undef, \& # \*(AqlastFailedBuild\*(Aq => undef, \& # \*(AqlastStableBuild\*(Aq => undef, \& # \*(AqlastSuccessfulBuild\*(Aq => undef, \& # \*(AqlastUnstableBuild\*(Aq => undef, \& # \*(AqlastUnsuccessfulBuild\*(Aq => undef, \& # \*(Aqname\*(Aq => \*(AqTest\-Project\*(Aq, \& # \*(AqnextBuildNumber\*(Aq => 1, \& # \*(Aqproperty\*(Aq => [], \& # \*(AqqueueItem\*(Aq => undef, \& # \*(Aqscm\*(Aq => {}, \& # \*(AqupstreamProjects\*(Aq => [], \& # \*(Aqurl\*(Aq => \*(Aqhttp://jenkins\-t2:8080/job/Test\-Project/\*(Aq \& # } .Ve .PP The information can be refined in the same way as \*(L"current_status\*(R" using \f(CW\*(C`extra_params\*(C'\fR. .SS "view_status" .IX Subsection "view_status" Provides the status of the specified view. The list of views is provided in the general status report. .PP .Vb 10 \& $jenkins\->view_status(\*(AqMyView\*(Aq); \& # { \& # \*(AqbusyExecutors\*(Aq => {}, \& # \*(AqqueueLength\*(Aq => {}, \& # \*(AqtotalExecutors\*(Aq => {}, \& # \*(AqtotalQueueLength\*(Aq => {} \& # } \& # { \& # \*(Aqdescription\*(Aq => undef, \& # \*(Aqjobs\*(Aq => [ \& # { \& # \*(Aqcolor\*(Aq => \*(Aqblue\*(Aq, \& # \*(Aqname\*(Aq => \*(AqTest\*(Aq, \& # \*(Aqurl\*(Aq => \*(Aqhttp://jenkins\-t2:8080/job/Test/\*(Aq \& # } \& # ], \& # \*(Aqname\*(Aq => \*(AqTest\*(Aq, \& # \*(Aqproperty\*(Aq => [], \& # \*(Aqurl\*(Aq => \*(Aqhttp://jenkins\-t2:8080/view/Test/\*(Aq \& # } .Ve .PP This method allows the same sort of refinement as the \*(L"current_status\*(R" method. To just get the job info from the view for example you can do essentially the same, .PP .Vb 10 \& use Data::Dumper; \& my $view_list = $api\->current_status({ extra_params => { tree => \*(Aqviews[name]\*(Aq }}); \& my @views = grep { $_ ne \*(AqAll\*(Aq } map { $_\->{name} } @{$view_list\->{views}}; \& for my $view (@views) \& { \& my $view_jobs = $api\->view_status($view, { extra_params => { tree => \*(Aqjobs[name,color]\*(Aq }}); \& print Dumper($view_jobs); \& } \& # { \& # \*(Aqjobs\*(Aq => [ \& # { \& # \*(Aqcolor\*(Aq => \*(Aqblue\*(Aq, \& # \*(Aqname\*(Aq => \*(AqTest\*(Aq \& # } \& # ] \& # } .Ve .SS "trigger_build" .IX Subsection "trigger_build" Trigger a build, .PP .Vb 1 \& $success = $jenkins\->trigger_build(\*(AqTest\-Project\*(Aq); .Ve .PP If you need to specify a token you can pass that like this, .PP .Vb 1 \& $jenkins\->trigger_build(\*(AqTest\-Project\*(Aq, { token => $token }); .Ve .PP Note that the success response is simply to indicate that the build has been scheduled, not that the build has succeeded. .SS "trigger_build_with_parameters" .IX Subsection "trigger_build_with_parameters" Trigger a build with parameters, .PP .Vb 1 \& $success = $jenkins\->trigger_build_with_parameters(\*(AqTest\-Project\*(Aq, { Parameter => \*(AqValue\*(Aq } ); .Ve .PP The method behaves the same way as trigger_build. .SS "build_queue" .IX Subsection "build_queue" This returns the items in the build queue. .PP .Vb 1 \& $jenkins\->build_queue(); .Ve .PP This allows the same \f(CW\*(C`extra_params\*(C'\fR as the \*(L"current_status\*(R" call. The depth and tree parameters work in the same way. See the Jenkins \&\s-1API\s0 documentation for more details. .PP The method will die saying 'Invalid response' if the server doesn't respond as it expects, or die with a \s-1JSON\s0 decoding error if the \s-1JSON\s0 parsing fails. .SS "load_statistics" .IX Subsection "load_statistics" This returns the load statistics for the server. .PP .Vb 7 \& $jenkins\->load_statistics(); \& # { \& # \*(AqbusyExecutors\*(Aq => {}, \& # \*(AqqueueLength\*(Aq => {}, \& # \*(AqtotalExecutors\*(Aq => {}, \& # \*(AqtotalQueueLength\*(Aq => {} \& # } .Ve .PP This also allows the same \f(CW\*(C`extra_params\*(C'\fR as the \*(L"current_status\*(R" call. The depth and tree parameters work in the same way. See the Jenkins \&\s-1API\s0 documentation for more details. .PP The method will die saying 'Invalid response' if the server doesn't respond as it expects, or die with a \s-1JSON\s0 decoding error if the \s-1JSON\s0 parsing fails. .SS "create_job" .IX Subsection "create_job" Takes the project name and the \s-1XML\s0 for a config file and gets Jenkins to create the job. .PP .Vb 1 \& my $success = $api\->create_job($project_name, $config_xml); .Ve .SS "project_config" .IX Subsection "project_config" This method returns the configuration for the project in \s-1XML.\s0 .PP .Vb 1 \& my $config = $api\->project_config($project_name); .Ve .SS "set_project_config" .IX Subsection "set_project_config" This method allows you to set the configuration for the project using \s-1XML.\s0 .PP .Vb 1 \& my $success = $api\->set_project_config($project_name, $config); .Ve .SS "delete_project" .IX Subsection "delete_project" Delete the project from Jenkins. .PP .Vb 1 \& my $success = $api\->delete_project($project_name); .Ve .SS "general_call" .IX Subsection "general_call" This is a catch all method for making a call to the \s-1API.\s0 Jenkins is extensible with plugins which can add new \s-1API\s0 end points. We can not predict all of these so this method allows you to call those functions without needing a specific method. .PP general_call($url_parts, \f(CW$args\fR); .PP .Vb 8 \& my $response = $api\->general_call( \& [\*(Aqjob\*(Aq, $job, \*(Aqapi\*(Aq, \*(Aqjson\*(Aq], \& { \& method => \*(AqGET\*(Aq, \& extra_params => { tree => \*(Aqcolor,description\*(Aq }, \& decode_json => 1, \& expected_response_code => 200, \& }); \& \& # does a GET /job/$job/api/json?tree=color%2Cdescription \& # decodes the response as json \& # dies if a 200 response isn\*(Aqt returned. .Ve .PP The arguments hash can contain these elements, .IP "\(bu" 4 method .Sp Valid options are the \s-1HTTP\s0 verbs, make sure they are in caps. .IP "\(bu" 4 extra_params .Sp Pass in extra parameters the method expects. .IP "\(bu" 4 decode_json .Sp Defaulted to true. .IP "\(bu" 4 expected_response_code .Sp Defaulted to 200 .SS "response_code" .IX Subsection "response_code" This method returns the \s-1HTTP\s0 response code from our last request to the Jenkins server. This may be useful when an error occurred. .SS "response_content" .IX Subsection "response_content" This method returns the content of the \s-1HTTP\s0 response from our last request to the Jenkins server. This may be useful when an error occurs. .SS "response_header" .IX Subsection "response_header" This method returns the specified header of the \s-1HTTP\s0 response from our last request to the Jenkins server. .PP The following example triggers a parameterized build, extracts the 'Location' \&\s-1HTTP\s0 response header, and selects certain elements of the queue item information .PP .Vb 10 \& $success = $jenkins\->trigger_build_with_parameters(\*(AqTest\-Project\*(Aq, { Parameter => \*(AqValue\*(Aq } ); \& if ($success) { \& my $location = $jenkins\->response_header(\*(AqLocation\*(Aq); \& my $queue_item = $jenkins\->general_call( \& [ URI\->new($location)\->path_segments, \*(Aqapi\*(Aq, \*(Aqjson\*(Aq ], \& { \& extra_params => { tree => \*(Aqurl,why,executable[url]\*(Aq } \& } \& ); \& # { \& # \*(Aqexecutable\*(Aq => { \& # \*(Aqurl\*(Aq => \*(Aqhttp://jenkins:8080/job/Test\-Project/136/\*(Aq, \& # \*(Aq_class\*(Aq => \*(Aqorg.jenkinsci.plugins.workflow.job.WorkflowRun\*(Aq \& # }, \& # \*(Aqurl\*(Aq => \*(Aqqueue/item/555125/\*(Aq, \& # \*(Aqwhy\*(Aq => undef, \& # \*(Aq_class\*(Aq => \*(Aqhudson.model.Queue$LeftItem\*(Aq \& # }; \& } else { \& print $jenkins\->response_code; \& } .Ve .SH "BUGS" .IX Header "BUGS" The \s-1API\s0 wrapper doesn't deal with Jenkins installations not running from the root path. I don't actually know if that's an install option, but the internal url building just doesn't deal with that situation properly. If you want that fixing a patch is welcome. .PP Please report any bugs or feature requests to through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc Jenkins::API .Ve .PP You can also look for information at: .IP "\(bu" 4 github issue list .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 Jenkins \s-1CI\s0 server .Sp .IP "\(bu" 4 Net::Jenkins .Sp An alternative to this library. .Sp .IP "\(bu" 4 Task::Jenkins .Sp Libraries to help testing modules on a Jenkins server. .Sp .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Birmingham Perl Mongers for feedback before I released this to \s-1CPAN.\s0 .PP With thanks to Nick Hu for adding the trigger_build_with_parameters method. .PP Alex Kulbiy for the auth support and David Steinbrunner for some Makefile love. .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Nick Hu .IP "\(bu" 4 David Steinbrunner .IP "\(bu" 4 Alex Kulbiy .IP "\(bu" 4 Piers Cawley .IP "\(bu" 4 Arthur Axel 'fREW' Schmidt .IP "\(bu" 4 Dave Horner .IP "\(bu" 4 Sven Willenbuecher .SH "AUTHOR" .IX Header "AUTHOR" Colin Newell .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2012\-2021 by Colin Newell. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.