Ruby wrapper for the TeamCity Rest API
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
$ gem install teamcity-ruby-client
API Usage Examples
- Tested on TeamCity 7.X and 8.0.X
- Most of the api calls return either an array of Hashie::Mash objects or a single Hashie::Mash object which allows you to send messages to retreive an attribute easily.
- See api docs or specs for additional examples and usage
- See configuration source or api doc for more configuration options
- You may use v7 of the TeamCity api by adding '7.0' to the endpoint configuration (This would be similar to using latest on a TeamCity 7 server)
require 'teamcity' # This only needs to be set once per Ruby execution. # You may use guestAuth instead of httpAuth and omit the use of http_user and http_password # This is using the latest version of the api . do |config| config.endpoint = 'http://my-teamcity-server:8111/httpAuth/app/rest' config.http_user = 'teamcity-user' config.http_password = 'teamcity-password' end
# Get a list of projects puts .projects # Get a project by id puts .project(id: 'project1') # Get a list of buildtypes for a project puts .project_buildtypes(id: 'project1') # Each item returned is a Hashie::Mash object which allows you to send messages # to retreive an attribute easily. For example, get the name of # the first buildtype in a project puts .project_buildtypes(id: 'project1').first.name # Create an empty project .create_project('my-new-project') # Copy a project .copy_project('project1', 'copied-project-name') # Delete a project .delete_project('project1') # Change project name .set_project_field('project1', 'name', 'new-project-name')
Build Types (Build Configurations)
# Get a list of buildtypes (build configurations) puts .buildtypes # Get buildtype details (build configuration) puts .buildtype(id: 'bt1') # Get buildtype steps puts .buildtype_steps(id: 'bt1') # Change buildtype name .set_buildtype_field('bt1', 'name', 'new-buildtype-name')
# Get build details puts .build(id: 1) # Get build tags puts .(id: 1) # Fetch all the builds (defaults to the last 100 builds, use the 'count' build locator to return more) puts .builds # Filter builds by multiple criteria's using the build locator puts .builds(count: 1, status: 'SUCCESS') # This will return the most recent build that passed puts .builds(count: 1).first.name puts .builds(buildType: 'bt3') # Fetch all builds where buildType=bt4 puts .builds(status: 'FAILURE') # Fetch all builds that failed # Passing the output to another to fetch additional information puts .build(id: .builds(count: 1).first.id).buildType.name # Fetch the name of the last build to run
# Get all the vcs roots puts Teamcity.vcs_roots # Get vcs root details puts .vcs_root_details(1) # Create VCS Root for a project .create_vcs_root(vcs_name: 'my-git-vcs-root', vcs_type: 'git', :project_id => 'project2') do |properties| properties['branch'] = 'master' properties['url'] = 'email@example.com:jperry/teamcity-ruby-client.git' properties['authMethod'] = 'PRIVATE_KEY_DEFAULT' properties['ignoreKnownHosts'] = true end
Generating API Docs
- Pull the source down
- open doc/index.html
TeamCity Rest API Plugin
Ways to contribute:
- report a bug
- fix an issue that is logged
- suggest enhancements
- suggest a new feature
- cleaning up code
- refactoring code
- fix documentation errors
- test on a new versions of teamcity
- Use the gem :)
Submitting an issue
I use issue tracker to track bugs, features, enhancements, etc. Please check the list of issues to confirm it hasn't already been reported. Please tag the the issue with an appropriate tag. If submitting a bug please include any output that will help me in diagnosing the issue, link to a gist if you have multiple outputs (client output, teamcity server output). Please include the version of teamcity you are using the client against as well as the gem and ruby versions.
Submitting a Pull Request
- Fork the project.
- Create a topic branch.
- Implement your feature or bug fix.
- Add documentation for your feature or bug fix.
- Please use the @rest_api_version tag to specify if a method is only compatible with a specific version of the rest api
rake doc:yard. If your changes are not 100% documented, go back to step 4.
- Add specs for your feature or bug fix.
- If the rspec test is making a request use VCR to record the response, see the other examples.
rake spec. If your changes are not 100% covered, go back to step 6.
- Commit and push your changes.
- Submit a pull request.
- Enable debug-rest in TeamCity to see all the rest api requests come through in the
teamcity-rest.log, you can find this on the Diagnostics page under Server Administration
Feel free to contact me directly through github. Enjoy!