My premiere plugin set, this package provides a generalized framework for integrating source control
repositories within the normal MantisBT workflow. Building on that framework are a set of integration
plugins that implement individual VCS tools, and translate that data into the framework’s generalized
data types. Once translated, the framework can act on those datasets in many ways to improve the workflow
in MantisBT, or to better inform developers and team members when looking at issues.
Some of the unique features offered by this framework include the ability to link changesets to issues and
the users that created them, automatic resolving or manipulation of issues depending on commit messages, and
the ability to intelligently map repository branches to project versions in the tracker. For instance, when
I commit a bugfix to the MantisBT repository’s “master” branch, if the commit message says “Fixes issue #17”,
the tracker can automatically mark issue #17’s fixed-in version as “1.3.x”, the current development version.
Once repository and commit data has been imported into MantisBT, it can be browsed or searched, and each
changeset can automatically link the user to external diffing or viewing tools appropriate for that
repository and tool.
But the best part about this framework is that it inherently supports the fundamental concepts behind any
version control tool. While it currently includes Git and Subversion with the core framework, it can just as
easily support integration for other tools, including Mercurial, CVS, or Bazaar. All it requires is a
developer knowledgeable in that version control tool to write a simple integration layer, and indeed there
is already an integration layer in the works for both Mercurial and Perforce.
This framework can be seen in use on the official MantisBT tracker, as well as on my own bugtracker.
The source code can be found on GitHub or cloned from the Source Integration repo.
When users are having troubles with setting up the source integration plugin with their repositories, I’ve
found that there is a common set of pain points. I’m going to list them here, along with their respective
solutions, in hopes that users can more easily find the fixes in the future. This post will be updated as
new tips or advice arrive.
Linking changesets to issues requires commit messages to match the regular expressions specified in the
source integration configuration page. By default, phrases like “fixes #123” or “resolved #123, #123”
are supported, in present, past, singular, and plural forms.
Remote checkin must be enabled for use by post-commit hooks that don’t use an API key to authenticate,
and must list the IP addresses or blocks for any repository server that will push commit data to Mantis.
Remote imports must be enabled for use by cronjob-based scripts that will trigger Mantis to pull in new
changeset data for a given repository.
Your web server needs to have the SVN client binaries installed, and they must be accessible by the
account that your web server uses. Similarly, if the binaries are in a directory that’s not included in
your web server’s default path, you will need to specify the directory path in your source integration
configuration. On Linux, this is usually
/usr/local/bin — on Windows, something like
c:/path/to/subversion/bin is likely required.
For Windows servers, you may also need to enable the “Windows start” source integration option.
Make sure that the individual repository URL that you use for Mantis is the same URL you would use to
checkout the repository when using an SVN client.
When using repositories that require authentication, make sure the username and password you enter in
Mantis has read access to the entire repository.
If your repositories are hosted using HTTPS/SSL, and your server is using self-signed certificates, you
will need to have SVN version 1.6 or newer installed, and you will need to enable the “Trust all SSL
certs” option from source integration.
If your commit messages contain UTF-8 or other non-ASCII characters, or your system’s locale is not set
to “en_US”, then you may need to look at issue #93 and #130 on my bug tracker
for help modifying your server or SourceSVN plugin to use an appropriate encoding or locale.
If using Gitweb, versions newer than 1.6 may not work correctly, as the Gitweb plugin is scraping HTML
from the viewer, and changes to the HTML structure will break the Gitweb plugin. The version of Gitweb
in use on MantisForge is known to work with the plugin.
Using Github with private organization repositories is not yet supported. Private repositories for
normal user accounts, however, is supported. Enter the username and API key from any Github account
with access to the repository, and it should import correctly.
Using branches other than “master” will require you to modify the individual repository configuration in
Mantis to list any branches that you want to be imported.
Today marks an incremental release to the Source Integration plugin framework for MantisBT, now at version
0.16.3. This marks the introduction of support for using an API key to authorize inbound changeset data
from repository data sources. It is initially supported for integration with Github, where large array of
servers made it all but impossible to whitelist allowed IPs for remote commit data.
Future plans for the feature include support for configuring multiple API keys simultaneously, as well as
adding support for using the API keys from other data sources, such as SVN or Gitweb repositories.
Additionally, the old options for listing allowed IP addresses is now considered deprecated, and will likely
be removed entirely at the next major release.
To set up an API key in your MantisBT instance, visit the Repository Configuration page, where you will find
a new option labelled, strangely enough, “API Key”. You will need to generate your own key; the best way to
do this is on a machine with OpenSSL by running the following command to create a secure, random string of
hexadecimal digits, and then copying the resulting string to MantisBT:
$ openssl rand -hex 12
Once this is done, you can enable this on your Github projects by visiting the Service Hooks admin page for
your repositories, activating the MantisBT hook, and copying the same key string into the “Api Key” field
there. Any future pushes to your Github repo should send data to your MantisBT install using the API key to
authorize the data submission.
Chris Dornfeld at Unitz has an excellent, detailed overview of the
options available when importing Subversion repositories into MantisBT using
my Source Integration framework. My previous article on the topic fails
to go into particulars with SVN repositories, mainly because many of the
options weren’t even dreamed of at the time, let alone implemented.
Anyways, the information and explanations presented in his article are pretty
accurate. Until I can get the time to fully document the SVN and Git plugins,
or the framework as a whole, consider Chris’s post to be canonical information.
Update: The information in this post is unfortunately out of date. While much of the code samples are similar, the new method of creating new plugins has changed in subtle, but very significant ways. Until a new guide can be written, please refer to the existing plugins for code examples.
Considering that my last post on Integrating Git and SVN has garnered a fair amount of attention, I thought that it would be useful to discuss my Source Integration framework in more detail. Specifically, I’ll be covering topics such as the design and implementation of the framework and, more importantly, how developers can go about implementing support for other version control tools.
The point of this is to show that it’s quite possible to integrate just about any type of version control tool with the Source Integration system; indeed I planned from the beginning to create a generalized framework that would support many different types and paradigms for version control. This should at least be evident in that I have already created extension plugins for Git and Subversion - it should be quite possible to extend the concepts further to Mercurial, Bazaar, CVS, or any other tool.
For the point of brevity, I’ll make the assumption that the developer at least has a fair understanding of PHP, their version control tool, and how events and plugins work in MantisBT. If you are not yet familiar with the plugin system, there is currently a basic introduction in the MantisBT Developer’s Guide, which I’ll hopefully be adding more information to in the near future.
Continue reading »
With the ongoing work towards a 1.2 release, the Mantis Bug Tracker features a brand new plugin and event system, which will allow users to implement entirely new features for MantisBT without ever needing to touch any of the core codebase. It’s a very extensible system, and allows plugin authors to implement only what they need, while still allowing advanced plugins as much flexibility as possible. Plugins can be as small as a single file with 20 lines of code, or as large as entire hierarchies of files, pages, with their own API’s.
As the core developer of the new plugin system, I have been working on a variety of plugins. In particular, I have created a vastly improved method of integrating source control repositories within MantisBT. The plugin package is named, aptly enough, Source Integration, and implements a generic framework that will allow integration with multiple repositories, each potentially using any source control systems available, simply by creating an extension plugin for each new tool. Currently, I have implemented integration packages for both Git and Subversion, my two source control tools of choice.
The Source Integration package tracks repository information based on a series of changesets, each of which may have a list of affected files. The data representation is generic enough to cover version control concepts used by all types of tools, from the ubiquitous CVS and Subversion, to modern distributed tools like Git and Hg. However, the system takes the stance of implementing as few details as possible, so it relies on existing repository-viewing tools for tasks such as viewing commit diffs, file contents, tree browsing, etc. Extension plugins handle translating tool-specific information, like history logs or checkin data, into the generalized data objects used by the framework. Extensions also generate URL’s for viewing files and diffs, but everything else is handled automatically by the core framework.
The true benefit of the Source Integration package lies in the amount of repository integration that it implements within MantisBT. When importing changesets from your repository, Source looks at the commit message of each changeset for references to bug numbers in your tracker, and sets up links in the database for any bugs mentioned. When viewing bugs mentioned in commit messages, a new section is displayed after the bugnotes called “Related Changesets”, giving a list of linked changes, including information about the changeset, such as the branch, author, timestamp, and a list of changed files.
Continue reading »