Provided by: libjenkins-api-perl_0.18-2_all bug

NAME

       Jenkins::API - A wrapper around the Jenkins API

VERSION

       version 0.18

SYNOPSIS

       This is a wrapper around the Jenkins API.

           use Jenkins::API;

           my $jenkins = Jenkins::API->new({
               base_url => 'http://jenkins:8080',
               api_key => 'username',
               api_pass => 'apitoken',
           });
           my $status = $jenkins->current_status();
           my @not_succeeded = grep { $_->{color} ne 'blue' } @{$status->{jobs}};
           # {
           #   'color' => 'red',
           #   'name' => 'Test-Project',
           #   'url' => 'http://jenkins:8080/job/Test-Project/',
           # }

           my $success = $jenkins->create_job($project_name, $config_xml);
           ...

   ATTRIBUTES
       Specify these attributes to the constructor of the "Jenkins::API" object if necessary.

   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

   api_key
       This is the username for the basic authentication if you have it turned on.

       If you don't, don't specify it.

       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 "response_code" after
       making a call that fails to see if it is an authentication failure.

           my $success = $jenkins->trigger_build($job_name);
           unless($success)
           {
               if($jenkins->response_code == 403)
               {
                   print "Auth failure\n";
               }
               else
               {
                   print $jenkins->response_content;
               }
           }

   api_pass
       The API token for basic auth.  Go to the Jenkins wiki page on authenticating scripted
       clients <https://wiki.jenkins-ci.org/display/JENKINS/Authenticating+scripted+clients> for
       information on getting an API token for your user to use for authentication.

METHODS

   check_jenkins_url
       Checks the url provided to the API has a Jenkins server running on it.  It returns the
       version number of the Jenkins server if it is running.

           $jenkins->check_jenkins_url;
           # 1.460

   current_status
       Returns the current status of the server as returned by the API.  This is a hash
       containing a fairly comprehensive list of what's going on.

           $jenkins->current_status();
           # {
           #   'assignedLabels' => [
           #     {}
           #   ],
           #   'description' => undef,
           #   'jobs' => [
           #     {
           #       'color' => 'blue',
           #       'name' => 'Jenkins-API',
           #       'url' => 'http://jenkins:8080/job/Jenkins-API/'
           #     },
           #   'mode' => 'NORMAL',
           #   'nodeDescription' => 'the master Jenkins node',
           #   'nodeName' => '',
           #   'numExecutors' => 2,
           #   'overallLoad' => {},
           #   'primaryView' => {
           #     'name' => 'All',
           #     'url' => 'http://jenkins:8080/'
           #   },
           #   'quietingDown' => bless( do{\(my $o = 0)}, 'JSON::XS::Boolean' ),
           #   'slaveAgentPort' => 0,
           #   'useCrumbs' => $VAR1->{'quietingDown'},
           #   'useSecurity' => $VAR1->{'quietingDown'},
           #   'views' => [
           #     {
           #       'name' => 'All',
           #       'url' => 'http://jenkins:8080/'
           #     }
           #   ]
           # }

       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 , "tree=> 'jobs[name],views[name,jobs[name]]'" demonstrates the
       syntax nicely.

       The other parameter you can pass is depth, by default it's 0, if you set it higher it
       dumps a ton of data.

           $jenkins->current_status({ extra_params => { tree => 'jobs[name,color]' }});;
           # {
           #   'jobs' => [
           #     {
           #       'color' => 'blue',
           #       'name' => 'Jenkins-API',
           #     },
           #   ]
           # }

           $jenkins->current_status({ extra_params => { depth => 1 }});
           # returns everything and the kitchen sink.

       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 "/job/Test-Project" you can specify the "path_parts => ['job', 'Test-Project']" to
       look at the data for that job alone.

           $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.

       The method will die saying 'Invalid response' if the server doesn't respond as it expects,
       or die with a JSON decoding error if the JSON parsing fails.

   get_job_details
       Returns detail about the job specified.

           $job_details = $jenkins->get_job_details('Test-Project');
           # {
           #   'actions' => [],
           #   'buildable' => bless( do{\(my $o = 0)}, 'JSON::PP::Boolean' ),
           #   'builds' => [],
           #   'color' => 'disabled',
           #   'concurrentBuild' => $VAR1->{'buildable'},
           #   'description' => '',
           #   'displayName' => 'Test-Project',
           #   'displayNameOrNull' => undef,
           #   'downstreamProjects' => [],
           #   'firstBuild' => undef,
           #   'healthReport' => [],
           #   'inQueue' => $VAR1->{'buildable'},
           #   'keepDependencies' => $VAR1->{'buildable'},
           #   'lastBuild' => undef,
           #   'lastCompletedBuild' => undef,
           #   'lastFailedBuild' => undef,
           #   'lastStableBuild' => undef,
           #   'lastSuccessfulBuild' => undef,
           #   'lastUnstableBuild' => undef,
           #   'lastUnsuccessfulBuild' => undef,
           #   'name' => 'Test-Project',
           #   'nextBuildNumber' => 1,
           #   'property' => [],
           #   'queueItem' => undef,
           #   'scm' => {},
           #   'upstreamProjects' => [],
           #   'url' => 'http://jenkins-t2:8080/job/Test-Project/'
           # }

       The information can be refined in the same way as "current_status" using "extra_params".

   view_status
       Provides the status of the specified view.  The list of views is provided in the general
       status report.

           $jenkins->view_status('MyView');
           # {
           #   'busyExecutors' => {},
           #   'queueLength' => {},
           #   'totalExecutors' => {},
           #   'totalQueueLength' => {}
           # }
           # {
           #   'description' => undef,
           #   'jobs' => [
           #     {
           #       'color' => 'blue',
           #       'name' => 'Test',
           #       'url' => 'http://jenkins-t2:8080/job/Test/'
           #     }
           #   ],
           #   'name' => 'Test',
           #   'property' => [],
           #   'url' => 'http://jenkins-t2:8080/view/Test/'
           # }

       This method allows the same sort of refinement as the "current_status" method.  To just
       get the job info from the view for example you can do essentially the same,

           use Data::Dumper;
           my $view_list = $api->current_status({ extra_params => { tree => 'views[name]' }});
           my @views = grep { $_ ne 'All' } map { $_->{name} } @{$view_list->{views}};
           for my $view (@views)
           {
               my $view_jobs = $api->view_status($view, { extra_params => { tree => 'jobs[name,color]' }});
               print Dumper($view_jobs);
           }
           # {
           #   'jobs' => [
           #     {
           #       'color' => 'blue',
           #       'name' => 'Test'
           #     }
           #   ]
           # }

   trigger_build
       Trigger a build,

           $success = $jenkins->trigger_build('Test-Project');

       If you need to specify a token you can pass that like this,

           $jenkins->trigger_build('Test-Project', { token => $token });

       Note that the success response is simply to indicate that the build has been scheduled,
       not that the build has succeeded.

   trigger_build_with_parameters
       Trigger a build with parameters,

           $success = $jenkins->trigger_build_with_parameters('Test-Project', { Parameter => 'Value' } );

       The method behaves the same way as trigger_build.

   build_queue
       This returns the items in the build queue.

           $jenkins->build_queue();

       This allows the same "extra_params" as the "current_status" call.  The depth and tree
       parameters work in the same way.  See the Jenkins API documentation for more details.

       The method will die saying 'Invalid response' if the server doesn't respond as it expects,
       or die with a JSON decoding error if the JSON parsing fails.

   load_statistics
       This returns the load statistics for the server.

           $jenkins->load_statistics();
           # {
           #   'busyExecutors' => {},
           #   'queueLength' => {},
           #   'totalExecutors' => {},
           #   'totalQueueLength' => {}
           # }

       This also allows the same "extra_params" as the "current_status" call.  The depth and tree
       parameters work in the same way.  See the Jenkins API documentation for more details.

       The method will die saying 'Invalid response' if the server doesn't respond as it expects,
       or die with a JSON decoding error if the JSON parsing fails.

   create_job
       Takes the project name and the XML for a config file and gets Jenkins to create the job.

           my $success = $api->create_job($project_name, $config_xml);

   project_config
       This method returns the configuration for the project in XML.

           my $config = $api->project_config($project_name);

   set_project_config
       This method allows you to set the configuration for the project using XML.

           my $success = $api->set_project_config($project_name, $config);

   delete_project
       Delete the project from Jenkins.

           my $success = $api->delete_project($project_name);

   general_call
       This is a catch all method for making a call to the API.  Jenkins is extensible with
       plugins which can add new API end points.  We can not predict all of these so this method
       allows you to call those functions without needing a specific method.

       general_call($url_parts, $args);

           my $response = $api->general_call(
               ['job', $job, 'api', 'json'],
               {
                   method => 'GET',
                   extra_params => { tree => 'color,description' },
                   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't returned.

       The arguments hash can contain these elements,

       •   method

           Valid options are the HTTP verbs, make sure they are in caps.

       •   extra_params

           Pass in extra parameters the method expects.

       •   decode_json

           Defaulted to true.

       •   expected_response_code

           Defaulted to 200

   response_code
       This method returns the HTTP response code from our last request to the Jenkins server.
       This may be useful when an error occurred.

   response_content
       This method returns the content of the HTTP response from our last request to the Jenkins
       server.  This may be useful when an error occurs.

   response_header
       This method returns the specified header of the HTTP response from our last request to the
       Jenkins server.

       The following example triggers a parameterized build, extracts the 'Location' HTTP
       response header, and selects certain elements of the queue item information

           $success = $jenkins->trigger_build_with_parameters('Test-Project', { Parameter => 'Value' } );
           if ($success) {
             my $location = $jenkins->response_header('Location');
             my $queue_item = $jenkins->general_call(
               [ URI->new($location)->path_segments, 'api', 'json' ],
               {
                 extra_params => { tree => 'url,why,executable[url]' }
               }
             );
             # {
             #   'executable' => {
             #      'url' => 'http://jenkins:8080/job/Test-Project/136/',
             #      '_class' => 'org.jenkinsci.plugins.workflow.job.WorkflowRun'
             #   },
             #   'url' => 'queue/item/555125/',
             #   'why' => undef,
             #   '_class' => 'hudson.model.Queue$LeftItem'
             # };
           } else {
             print $jenkins->response_code;
           }

BUGS

       The API 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.

       Please report any bugs or feature requests to through the web interface at
       <https://github.com/colinnewell/Jenkins-API/issues/new>.  I will be notified, and then
       you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

       You can find documentation for this module with the perldoc command.

           perldoc Jenkins::API

       You can also look for information at:

       •   github issue list

           <https://github.com/colinnewell/Jenkins-API/issues>

       •   AnnoCPAN: Annotated CPAN documentation

           <http://annocpan.org/dist/Jenkins-API>

       •   CPAN Ratings

           <http://cpanratings.perl.org/d/Jenkins-API>

       •   Search CPAN

           <http://search.cpan.org/dist/Jenkins-API/>

SEE ALSO

       •   Jenkins CI server

           <http://jenkins-ci.org/>

       •   Net::Jenkins

           An alternative to this library.

           <https://metacpan.org/module/Net::Jenkins>

       •   Task::Jenkins

           Libraries to help testing modules on a Jenkins server.

           <https://metacpan.org/module/Task::Jenkins>

ACKNOWLEDGEMENTS

       Birmingham Perl Mongers for feedback before I released this to CPAN.

       With thanks to Nick Hu for adding the trigger_build_with_parameters method.

       Alex Kulbiy for the auth support and David Steinbrunner for some Makefile love.

CONTRIBUTORS

       •   Nick Hu

       •   David Steinbrunner

       •   Alex Kulbiy

       •   Piers Cawley

       •   Arthur Axel 'fREW' Schmidt

       •   Dave Horner <https://dave.thehorners.com>

       •   Sven Willenbuecher

AUTHOR

       Colin Newell <colin.newell@gmail.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2012-2021 by Colin Newell.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.