MantisBT API for Ruby
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

mantisrb Build Status

mantisrb is an API that works with the Savon gem to talk to a Mantis bug tracker through SOAP calls. Mantis' SOAP interface is called MantisConnect (see example for an API view).



gem install mantisrb

Create a session to the Mantis server:

session = "", "YourUsername", "YourPassword"

Various components are described below:


Configuration details about the Mantis installation can be retrieved, such as finding out the status types, access levels, and view states:

session.config.priorities # get priorities
session.config.statuses # possible issue statuses
session.config.version # Mantis version

More information on this can be found in {Mantis::Config}.


Get a list of projects that your user can access:


Create a project:

    project_id = session.projects.create params={
      name: "project name"  # Minimally, this is all you need

Or provide more details (some shown below):

    project = session.projects.create {
      name: "project thing",
      status: "development"
      enabled: true,
      view_state: :public # or 'public', or session.projects.status.public,
      inherit_from_global: true
    }  # "project thing"    # 10 or whatever for referencing

More details on what is in a project can be found in {Mantis::XSD::ProjectData}.


Getting issues is easy, too:

by id:

    session.issues.by_id 110 # if you know the id
    session.issues.exists? 110 # if you don't know if it's there
    session.issues.by_name "problem name I solved" # name of Mantis issue that
    you want to search explicitly by (no wildcards or regex'ing, sorry)

    session.projects.issues "project name" # get first 100 issues by Project Name

by ugly Mantis summary searching:

    session.issues.summary_matches "some regex"  # Do some ssearching (mind, it
    is going to be pretty slow)

by project id:

    session.issues.by_project_id project_id, page_#, issues_per_page # The
    fully flexible way of getting a list of issues
    session.issues.by_project_id project_id # gets you an Enumerable to go
    through things
    session.issues.by_project_id project_id, limit # number of issues to get at

Creating them isn't too bad (know your options):

    issue = session.issues.create {
      summary: "issue description somewhere here",
      priority: :high,
      due_date: "10/13/2011 08:45 AM" # or other formats as DateTime will

Required fields for an issue:

  • project (id or name of project will work)
  • summary
  • description
  • category name (you can get this from the project)

Information on what is in an Issue can be found in the {Mantis::XSD::IssueData} class.

Issue Check-in

Issues can be updated with comments or completion with this quick call to an issue:

    session.issues.checkin(issue_id, comment, completed?) # defaults to false

There are a number of other features that you can manipulate through the API, so check out the documentation for more. See {Mantis::Issues} for more information on the other types (relationships, attachments, etc.)


Filters are Mantis' way of saving a configured search. You likely know what they are if you have used Mantis, so if not, please take a brief look at this blogpost to see what you can use filters for.

Get a filter by id:

    session.filters.by_project_id 110 # get all filters you can search by for the project_id

Get issues for a particular filter:

    session.filters.get_issues project_id # get first 100 issues for a given
    session.filters.get_issues project_id, page_num, issues_per_page
    # fully-formatted search

Creation/Deletion/Etc., actions on Filters are unsupported as Mantis' SOAP API does not support it.

Categories in Projects

When creating issues, you will need to know what category the issue belongs to, so this should be helpful.

Get all categories for a project:


Add a category

    session.projects.add_category(45, "Triage")
    session.projects.add_category(<project_id>, <category_name>)

Delete a category

    session.projects.delete_category(<project_id>, <category_name>)

Rename a category

    session.projects.rename_category params={
      project_id: <id>,
      old_category: <category_name>,
      new_category: <new_category_name>,
      project_assigned_to: <id> # leaving this out will keep it in the same


You can see which environments have been tested on Travis CI. JRuby support is lacking, as it appears there might be an issue with Nokogiri and Savon gems (to be determined). Any help in getting JRuby to work (w/ JRUBY_OPTS=--1.9) would be greatly appreciated.

License, Open-Source-ness, and other Miscellany

I've licensed mantisrb with the MIT License, which should be permissive enough for you to muck around and fiddle with. It's open-source, so contributions are welcomed and encouraged.

For any questions / suggestions / contributions, contact me at:

Email: klauer - at - gmail - dot - com for more information or send me a pull-request.


There are alot of things I don't have done in this, but you should be able to get by for the most part with:

  • querying projects/issues/filters, etc
  • CRUD tasks on issues/projects/filters/categories, etc.

What isn't done:

  • Mocking - I have yet to get mocking to work on this project, and I could use someone's help in getting that up. That would make finishing the testing SOOO much easier.
  • Testing - I have a long way to go

What can't be done:

Unfortunately, MantisConnect just isn't as full-featured as their web application. If you want feature parity with Mantis, I have yet to find an API that will work with it, besides attempting to stub out all of the calls that are normally performed from the browser in an API, or possibly hard-wiring your application into the Mantis Database tables.

I have at a minimum, implemented every method call that MantisConnect provides. If mantisrb doesn't provide something, it's probably not in their SOAP API.