README

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.