VCS Integration  ⇑ top

The Bug Genie includes the VCS Integration module, which allows you to link your projects in The Bug Genie to a source code repository. This allows your commits to update issues, as well as access the repository viewer from The Bug Genie. However, before you can start, you need to set up the module - both globally and for each project using the module.

Please note that the git hook does not support the web access method (explained later), only the direct access method. In addition, a Mercurial hook is available, though it is not included due to license restrictions. Please refer to The Bug Genie website to obtain it.

Setting up  ⇑ top

Global settings  ⇑ top

There are two methods for VCS hooks (the code that interfaces between your source code repository and The Bug Genie) to communicate with your installation. The methods are direct access and http access.

Direct access  ⇑ top

In direct access, the repository exists on the same server as The Bug Genie, or the hook can use SSH or other associated systems to access the server that The Bug Genie is hosted on. Therefore the user that VCS hooks are executed as will need access to The Bug Genie's files, as well as a PHP executable. You will also require the CLI version of PHP installed.

In each hook, you will need to enable direct mode, and set the path to PHP and The Bug Genie's tbg_cli file. You will also need to set the project ID, which can be found on the VCS configuration page. Please refer to each hook's documentation (it may be included in the hook file itself) to see how to do this.

Then, in the VCS Integration general settings tab, on the Configuration page, choose Direct access and click Save. You can then set up your projects.

HTTP access  ⇑ top

Another option would be to use HTTP access, where the hook will use HTTP to access a page on your installation of The Bug Genie, which will cause the checkin to be recorded. Choose this option if you are not able to use the direct method. You will also need this method to interface The Bug Genie with github.

You will need to configure hooks to use this mode, as well as set the project ID and URL to access. Refer to hook documentation for doing this (this may be included in the hook itself). Please also set a secure passkey to prevent unauthorized commits. This will need to be the same for every VCS, and set in each hook.

You will then need to choose HTTP access on the VCS Integration general settings tab. In addition, you will need to enter the passkey you set earlier on this screen.

After saving these settings, you can then set up each project.

Github support  ⇑ top

If you wish to use the github hook, please set up HTTP access as previously discussed. You will then need to set up your Github project's post-receive hook to contact The Bug Genie.

To do this, go to your project's service hooks page on github, and set a Post-recieve URL to point to the following URL:

  http://www.your-tbg-site.com/vcs_integration/report/PROJECTID/github/?passkey=PASSKEY

You will need to set the hostname and path correctly as appropriate, as well as replacing PASSKEY with the passkey you set, and PROJECTID with the ID number of the project, which can be found on the projects tab of VCS Integration configuration.

Any commits which follow the rules for being picked up (see below) will then be recorded against their respective issues on push, though commits which make no changes to the filesystem (i.e. nothing added, removed or modified) will not be recorded in this release of VCS Integration.

Bitbucket support  ⇑ top

If you wish to use the bitbucket hook, please set up HTTP access as previously discussed. You will then need to set up your Bitbucket project's post-receive hook to contact The Bug Genie.

To do this, go to your project's service hooks page on bitbucket, and set a POST URL to point to the following URL:

  http://www.your-tbg-site.com/vcs_integration/report/PROJECTID/bitcucket/?passkey=PASSKEY

You will need to set the hostname and path correctly as appropriate, as well as replacing PASSKEY with the passkey you set, and PROJECTID with the ID number of the project, which can be found on the projects tab of VCS Integration configuration.

Any commits which follow the rules for being picked up (see below) will then be recorded against their respective issues on push, though commits which make no changes to the filesystem (i.e. nothing added, removed or modified) will not be recorded in this release of VCS Integration.

Gitorious support  ⇑ top

If you have a locally hosted Gitorious server, then you can integrate that with The Bug Genie.

Again, set a post-receive hook as per your documentation, the URL for which is:

  http://www.your-tbg-site.com/vcs_integration/report/PROJECTID/gitorious/?passkey=PASSKEY

Please note that the Gitorious support will only create comments and will not record filesystem changes, plus it will not work on the gitorious.com server.

Project settings  ⇑ top

Each project to use VCS Integration will then require configuration. If a project will not be using VCS Integration, then you can leave its repository URL field empty.

To set up each project, you need to specify the repository browser you use. This will be used to build the right URLs to be displayed in The Bug Genie. In the URL to repository browser field, you enter the path to the root of the repository browser (i.e. this may be the page where a list of available repository browsers is shown). Finally you enter the repository name in the final box.

After pressing save, a Source code link will be added to the project dashboard. You can use this link to test to see if the details are correct - if so this link will open the main page of the repository browser for your chosen project.

After doing this, the module can be used by committing details as below, and they will show up in a new tab when viewing an issue, with links to view files, diffs, revision info and other details.

Using the module  ⇑ top

When a commit is made which refers to an issue, then the issue will be updated with the commit log and details of every changed file. The Bug Genie will pick up any commits which contain any of the following words, followed by an issue number:

  bug, issue, ticket, fix, fixes, fixed, fixing, applies to, closes
  references, ref, addresses, re, see, according to, also see

The user assigned to the commit will depends on the user who committed it to the VCS. If you are using a VCS where your committer name is in the form "Joe Bloggs <jbloggs@example.com>", for example, then The Bug Genie will search for users with the email as provided.

If a user can not be found, or if there is no email, then The Bug Genie will take the name part (or username) and search against the Full Name field. Failing that, we then search against the friendly name and then finally the user name. If still no user can be found then no user will be recorded for the commit.

Links on the project dashboard to view the source code repository is added upon set up, and each commit will have a link to view the commit details, a log of commits, diffs and links to view files.