NAME

WebService::TeamCity - Client for the TeamCity REST API

VERSION

version 0.04

SYNOPSIS

    use WebService::TeamCity;

    my $client = WebService::TeamCity->new(
        scheme   => 'https',
        host     => 'tc.example.com',
        port     => 8123,
        user     => 'tc-user',
        password => 'tc-password',
    );

    my $projects = $client->projects;
    for my $project ( @{$projects} ) {
        say $project->id;
        for my $build_type ( @{ $project->build_types } ) {
            say $build_type->id;
        }
    }

    my $projects = $client->projects;
    for my $project ( @{$projects} ) {
        ...;
    }

DESCRIPTION

This distribution provides a client for the TeamCity REST API.

Currently, this client targets the TeamCity 9.1 release exclusively. It is also quite incomplete and only supports read operations. Pull requests are very welcome!

The entry point for the API is this module, WebService::TeamCity. Once you have an object of that class, you can use it to get at various other objects provided by the API.

INSTABILITY WARNING

This distribution is still in its early days and its API may change without warning in future releases.

API

This module provides the top-level client for the API.

WebService::TeamCity->new(...)

This method takes named parameters to construct a new TeamCity client.

• scheme

  The URL scheme to use. This defaults to http.

• host

  The host to connect to. Required.

• port

  The port to connect to. By default, this just uses whatever the scheme normally uses.

• user

  The username to use for authentication. Required.

• password

  The password to use for authentication. Required.

• ua

  An instance of LWP::UserAgent. You can pass one in for testing and debugging purposes.

$client->projects(...)

Returns an array reference of WebService::TeamCity::Entity::Project objects. This contains all the projects defined on the TeamCity server.

You can pass arguments as key/value pairs to limit the projects returned:

• id => Str

  Only return projects matching this id.

• name => Str

  Only return projects matching this name.

$client->build_types

Returns an array reference of WebService::TeamCity::Entity::BuildType objects. This contains all the build types defined on the TeamCity server.

You can pass arguments as key/value pairs to limit the build types returned:

• affected_project => { ... }

  Only return build types which affect the specified project. Projects can be specified as defined for the projects method. This includes sub-projects of the specified project.

• id => Str

  Only return build types matching this id.

• name => Str

  Only return build types matching this name.

• paused => Bool | JSONBool

  Only return build types which are or are not paused.

• project => { ... }

  Only return build types which affect the specified project. Projects can be specified as defined for the projects method. This only includes the project itself, not its sub-projects.

• template => { ... }

  Only return build types which use the specified template. The template is defined the same way as a build type, but you cannot include a template key for the template spec too.

• template_flag => Bool | JSONBool

  Only return build types which are or are not templates.

$client->builds

Returns a WebService::TeamCity::Iterator which returns WebService::TeamCity::Entity::Build objects.

You can pass arguments as key/value pairs to limit the projects returned:

• affected_project => { ... }

  Only return builds which affect the specified project. Projects can be specified as defined for the projects method. This includes sub-projects of the specified project.

• agent_name => Str

  Only return builds which used the specified agent.

• branch => Str

  Only return builds which were built against the specified branch.

• build_type => { ... }

  Only return builds which were built using the specific build type. Build types can be specified as defined for the build_types method.

• canceled => Bool | JSONBool

  Only returns builds which were or were not canceled.

• failed_to_start => Bool | JSONBool

  Only returns builds which did or did not fail to start.

• id => Str

  Only return builds matching this id.

• lookup_limit => Int

  Only search the most recent N builds for a matching build.

• name => Str

  Only return builds matching this name.

• number => Str

  Only return builds matching this number.

• personal => Bool | JSONBool

  Only returns builds which are or are not marked as personal builds.

• pinned => Bool | JSONBool

  Only returns builds which are or are not pinned.

• project => { ... }

  Only return builds which affect the specified project. Projects can be specified as defined for the projects method. This only includes the project itself, not its sub-projects.

• running => Bool | JSONBool

  Only returns builds which are or are not running.

• since_date => DateTime

  Only returns builds started on or after the specified datetime.

• status => Str

  Only returns builds with the specified status. This can be one of SUCCESS, FAILURE, or ERROR.

• tags => [ ... ]

  Only returns builds which match all of the specified tags. Tags are given as strings.

SUPPORT

Bugs may be submitted through https://github.com/maxmind/WebService-TeamCity/issues.

AUTHOR

Dave Rolsky <autarch@urth.org>

CONTRIBUTORS

• Dave Rolsky <drolsky@maxmind.com>

• Greg Oschwald <goschwald@maxmind.com>

• Mark Fowler <mark@twoshortplanks.com>

• Olaf Alders <oalders@maxmind.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by MaxMind, Inc.

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