00mjk / source-integration

Source control integration plugin framework for MantisBT, including support for Github, Gitlab, Bitbucket, Gitweb, Cgit, Subversion, Mercurial and more

Mantis Source Integration

Copyright (c) 2008 - 2012 John Reese - https://noswap.com
Copyright (c) 2012 - 2022 MantisBT Team - [email protected]

Released under the MIT license

Description

The Source plugin provides a flexible framework for fully integrating any sort of Version Control System (VCS) with Mantis, including support for multiple repositories, changesets or revisions, and file path tracking. It has many features already, such as importing repository history and optional support for remote check-ins or imports, and utilizes a class-based API to access objects in the database.

Initial support is included for Subversion and Git repositories using the following extension plugins:

• SourceBitBucket: Git repositories hosted on BitBucket.
• SourceCgit: Git repositories accessible via a cgit web frontend installation.
• SourceGithub: Git repositories hosted on GitHub.
• SourceGitlab: Git repositories hosted on GitLab.
• SourceAzureDevOps: Git repositories hosted on Azure DevOps Services Repos.
• SourceGitphp: Git repositories accessible via a Gitphp web frontend installation.
• SourceGitweb: Git repositories accessible via a GitWeb web frontend installation.
• SourceHgWeb: Mercurial repositories accessible via a HgWeb frontend installation.
• SourceSFSVN: SVN repositories hosted on SourceForge.
• SourceSVN: SVN repositories locally accessible by the SVN binaries.
• SourceViewVC: SVN repositories accessible via a ViewVC web frontend installation.
• SourceVisualSVNServer: SVN repositories hosted on a VisualSVN Server installation, with support for URL linking from MantisBT to VisualSVN Server's built-in web frontend.
• SourceWebSVN: SVN repositories accessible via a WebSVN web frontend installation.

Support for additional source control tools should be rather straightforward to implement due to the flexibility inherent in the integration framework and API.

Requirements

The Source Integration framework requires MantisBT version 2.21.0 or higher.

VCS plugins

Some VCS plugins have additional, specific requirements:

• SourceBitBucket requires the PHP Curl extension, or the ability to execute
  system calls (via shell_exec).

Installation

Compatibility

The Source Integration framework's version numbering follows Semantic Versioning. Major version increments indicate a change in the minimum required MantisBT version.

See the Change log for detailed revision history.

Depending on which version of MantisBT you are using, please make sure to get the appropriate version of the source code. Use release tags, or the relevant branch in the Plugin's GitHub repository, as per the table below:

MantisBT version	Tags	Branch	Notes
2.x	v2.*	master	Current release
1.3.x	v1.*	master-1.3.x	Support ended 2020-12-31
1.2.x	v0.*	master-1.2.x	Support ended 2017-06-30

Setup instructions

1. Download the appropriate version (see Compatibility section above) or clone a copy of the source code and checkout the correct branch.

2. Copy the primary Source plugin (the Source/ directory) into your Mantis installation's plugins/ directory.

3. Copy all the remaining plugins, or just the appropriate ones for your repositories, into your Mantis installation's plugins/ directory.

4. While logged into your Mantis installation as an administrator, go to 'Manage' -> "Manage Plugins".

5. In the "Available Plugins" list, you'll find the "Source Control Integration" and additional plugins:

   a. First, click the "Install" link for the "Source Control Integration" plugin.

   b. Next, click the "Install" link next to any additional Source Control plugins appropriate for your repositories.

6. Click on the "Source Control Integration" plugin to configure it.

   NOTE: an API Key must be set up to import changesets via shell. To generate a random key, run

    openssl rand -hex 12
   

7. Go to "Repositories" and enter your repository name, select the repository type, and click "Create Repository" to begin adding your first repository.

8. Configure the repository, following the specific documentation for the relevant plugin extension:

   • SourceGithub
   • SourceGitlab
   • SourceAzureDevOps
   • SourceViewVC
   • SourceSVN
   • SourceVisualSVNServer

9. Once configured, click the "Return to Repository" link and click either the "Import Everything" or "Import Newest Data" button to perform initial import of repository changesets and verify configuration.

10. Once satisfied that your repository is configured & working correctly, you can automate the import of new changesets by configuring a cron job on the web server where your Mantis installation resides, as follows:

    • import via curl (could run into timeouts on large repositories, or block your webserver)

        curl "http://host.domain.tld/mantisbt/plugin.php?page=Source/import&id=all&api_key=<YOUR_API_KEY>"
      

    • import via shell

        php-cgi -f plugin.php page=Source/import id=all api_key=<YOUR_API_KEY>
      

      Please be aware of the difference between php-cgi and php-cli. The import won't run with php-cli.

    This will import new changesets for all configured repositories.

11. You can also configure event-driven import of new changesets. Many source control systems support configurable hooks or triggers which can be used to notify the Source plugin that new commits or revisions are available for import. This improves user experience by eliminating delays between source control commits and MantisBT state updates.

    Refer to the configuration documentation for the relevant plugin extension(s) for more information.

12. Add additional repositories as needed.

Support

The following support channels are available if you wish to file a bug report, or have questions related to use and installation:

• GitHub issues tracker
• Gitter chat room
• If you feel lucky you may also want to try the legacy #mantisbt IRC channel on Freenode (irc://freenode.net/mantisbt) but since hardly anyone goes there nowadays, you may not get any response.

All code contributions (bug fixes, new features and enhancements, additional VCS integration plugins) are welcome and highly encouraged, preferably as a Pull Request.

The latest source code is available on GitHub; John Reese's original project documentation can be found on his website, noswap.com.