REST::Buildbot - Interface to the Buildbot v2 REST API
Version 0.02
This is an interface to the REST API provided by Buildbot instances. Most object types can be fetched by name or id, and most object types can be used to look up associated objects. The individual objects have no methods, but do have accessors for all of the data returned by the REST API. Most attributes are pure perl data types, the only exception is BuildSets and Changes, both of which have an attribute that contains a REST::BuildBot::SourceStamp or an arrayref of them.
use REST::Buildbot; my $bb = REST::Buildbot->new(url => 'http://localhost:8010/api/v2/'); # Get the 'linux' builder's first build my $linux_builder = $bb->get_builder_by_name('linux'); my $build = $bb->get_build_by_builder_and_number($linux_builder, 1); # Learn about this build my $buildrequest = $bb->get_buildrequest_by_id($build->buildrequestid); my $buildset = $bb->get_buildset_by_id($buildrequest->buildsetid); my $sourcestamp = $buildset->sourcestamps->[0]; # Branch, revision ID, and commit message are in the SourceStamp object # Look up all the builds with a certain revision my $rev = '0123456789abcdef...'; my $buildsets = $bb->get_buildsets_by_revision($rev); # There may be several, choose in your own way my $buildset = $buildsets->[0]; # Find all the builds on this buildset, and explore some information my $buildrequests = $bb->get_buildrequests_by_buildset($bsid); foreach my $buildrequest (@$buildrequests) { my $brid = $buildrequest->buildrequestid; my $builds = $bb->get_builds_by_buildrequest($brid); # Again, choose one build. Usually most recent, older ones may # be cancels or retries my $build = $builds->[0]; my $steps = $bb->get_steps_by_build($build->buildid); # The last step is make test for me my $make_test = $steps->[-1]; my $logs = $bb->get_logs_by_step($make_test->stepid); # Choose which log to use - probably by looping and # comparing against name my $log; foreach my $l (@$logs) { if ($l->name =~ /stdio/) { $log = $l; last; } } die "No stdio log" unless $log; my $stdio_text = $bb->get_log_text($log->logid); }
The following subtypes are available: Build, Builder, BuildRequest, BuildSet, Change, Log, SourceStamp, Step. Of these, all 8 have an ID which they can be looked up by, for example, get_build_by_id, or they can all be looked up at once by, for example, get_builds.
Additionally, Builders can be looked up by name, Changes can be looked up by revision. These methods use names like get_builder_by_name.
Builds can also be looked up using the build "number" (which is unique by builder, but not globally unique - it is distinct from the build id). This method requires the Builder object and the build number, and is called get_build_by_builder_and_number.
The objects themselves have a number of interrelationships. Most of these are one-to-many, even though some of them are one-to-one under most normal cases. For example, buildset to buildrequest is expected to be one-to-many (if one scheduler triggers more than one builder), but usually each buildrequest has only one build. There may be multiple builds per buildrequest if one of the builds was cancelled manually or due to a client restart. Here is a full list of valid relationships:
Each of the above is a one-to-many relationship. For example, get_builds_by_builder returns an arrayref of Builds, but get_builder_by_build returns a single Builder.
Additionally, a Change is one-to-one with a SourceStamp, and a BuildSet is one-to-many with SourceStamps. Generally, you will not use this relationship, instead using a helper function like get_buildsets_by_revision or get_changes_by_revision if you have a source control revision, or the ->sourcestamp->* properties of a Change, or the ->sourcestamps->[$i]->* properties of a BuildSet, to get a source control revision.
Finally, it is possible to get the text of a log object using get_log_text.
On error, REST::Buildbot methods will return undef and set an error string, which can be accessed by ->errorstr. An error is defined as an LWP::UserAgent error, a lookup by an ID that does not exist, or calling a method with insufficient or incorrect arguments.
If no items are found for a query, REST::Buildbot will return undef, for methods returning a single object, or an empty array ref, for methods potentially returning multiple objects.
REST::Buildbot may cache the results of common calls, such as the list of all builders. In general, you should assume that data is no more recent than the first call made against a REST::Buildbot object. If you wish to ensure that cached data is not being used, for example, if you are using REST::Buildbot within an application that runs as a daemon, you should create a new REST::Buildbot object.
Constructor. Takes one mandatory argument, the URL to the API of the Buildbot instance to use. Should end in /api/v2/.
my $bb = REST::Buildbot->new(url => 'http://localhost:8010/api/v2/');
This set of methods allows lookup of all objects of a given type that the buildbot instance has. It returns a reference to an array of those objects. If there are none, it returns an empty array.
This set of methods allows looking up an item by its unique id. Looking up an item that does not exist is an error, and is currently handled by dying. In the future, this behavior may change, likely by having these methods return undef.
This is the set of methods that employs the relationships between data types. In all cases, they take a single argument: an object of the type to be searched by.
The following items return a reference to an array containing any number of the target type:
The following items return an object of the target type, or undef on failure.
Looks up a builder by name. Returns a REST::Buildbot::Builder object. Returns undef if there is not exactly one builder with a matching name.
Looks up changes by a revision string. Returns a reference to an array of REST::Buildbot::Change objects. If there are no results, the reference will be to an empty array.
Looks up buildsets by a revision string. Returns a reference to an array of REST::Buildbot::BuildSet objects. If there are no results, the reference will be to an empty array.
Looks up a build using the Builder object and the build number. Returns a REST::Buildbot::Build object. Returns undef if there is no match.
Returns the contents of a log as a string. Returns undef on failure.
Dan Collins, <DCOLLINS at cpan.org>
<DCOLLINS at cpan.org>
Please report any bugs or feature requests to bug-rest-buildbot at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=REST-Buildbot. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-rest-buildbot at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc REST::Buildbot
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=REST-Buildbot
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/REST-Buildbot
CPAN Ratings
http://cpanratings.perl.org/d/REST-Buildbot
Search CPAN
http://search.cpan.org/dist/REST-Buildbot/
Copyright 2016 Dan Collins.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
To install REST::Buildbot, copy and paste the appropriate command in to your terminal.
cpanm
cpanm REST::Buildbot
CPAN shell
perl -MCPAN -e shell install REST::Buildbot
For more information on module installation, please visit the detailed CPAN module installation guide.