...
When Continua gets the latest changesets from your source repository, it automatically retrieves all commit/checkin messages associated with that changeset. If your source repository is linked to an issue connector then it will also try to parse the commit/checkin messages for issue ids. It will then take those issue id's from the commit message and generate a hyperlink to that issue in your issue tracking system. The list of hyperlinks will be displayed in the "Issues" tab when viewing a build. Issue Connectors do not interact with your issue tracking system, they just generate hyperlinks to it! It won't open or close issues or require any kind of login to your system.
Once an Issue Connector has been created, it needs to be linked to a repository. This linking can be achieved on any of the repository pages where you can edit repository details.
Why use an Issue Connector?
...
Issue Connectors can be created and edited in the Administration area, under the Continuous Integration section. On the Issue Connectors page you should see several default issue connectors that have already been created. These issue connectors link to some of the major issue tracking / repository hosting systems and they should work with most of these systems out of the box.
New Issue Connectors can be created through the [Create] link at the top of the page, or existing issue connectors can be edited through the [Edit] links. Both these links will bring up the Issue Connector dialog:
Name
The Name of the issue connector is used to reference specific issue connectors when adding an issue connector to a repository.
Template
By selecting a template, you are pre-populating the remaining fields with appropiate values for a certain issue tracking system. Eg. If you select GitHub, it will set Commit Message Regex to #(?<id>\d+), Issue Server URL to {repo.url}/issues/{id} and Validation to Bug fix check in for issue #392881.
Note that changing the template will overwrite any values that you have already entered into the remaining fields.
Commit Message Regex
The Commit Message Regex is a regular expression that tells the issue connector to extract certain data out of commit messages. To properly construct a regular expression to your needs, determine what your repository commit message will contain then write the regex to extract the issue id out of it. Any information that needs to be extracted MUST be placed into a named group. Named groups have the following syntax <namedGroup>. For example, to extract an issue id, you could use the following regex: #(?<id>\d+). This regex gets any number that is preceded by a hash (#) and saves the value into the <id> named group.
Note that every commit message regex MUST contain the <id> named group.
Named groups can then be inserted into the Issue Server URL using the following syntax: { namedGroupName }. For example, to insert the <id> named group into the Issue Server URL, you would include {id} in the Issue Server URL.
Issue Server URL
The Issue Server URL is a template URL for generating links to your issue system. It allows you to dynamically set values of the URL based on specific build information. Any information that is pulled out of a commit message using the Commit Message Regex named groups (read above) can be inserted into the URL. All of the default issue connectors simply pull out the issue id by using the <id> named group in the Commit Message Regex and insert the id field into the generated issue url by using the {id} syntax (See the example provided in the 'Why Use an Issue Connector?' section).
Additional information can be included within the Issue Server URL. For example, if you use the project name in your commit messages, you can set your Commit Message Regex to also extract the project name using the <project> named group. This project name can then be inserted into the Issue URL with {project} syntax.
Issue Connectors also allow for certain repository information to be included within the Issue Server URL. The following tags can be used:
| Tag | Description | Url and Value | Example |
|---|---|---|---|
| {repo.url} | Extracts the source url from the repository and places it in the Issue Server URL | Repository Source URL: https://github.com/username/testGitHub.git {repo.url}: https://github.com/username/testGitHub | Issue Server URL: {repo.url}/issues/{id} Generated Link: https://github.com/username/testGitHub/issues/1 |
| {repo.subdomain} | Extracts the subdomain from the repository source url and place it in the Issue Server URL | Repository Source URL: https://myrepo.kilnhg.com/Code/Repositories/Group/Test1 {repo.subdomain}: myrepo | Issue Server URL: http://{repo.subdomain}.fogbugz.com/default.asp?{id} Generated Link: http://myrepo.fogbugz.com/default.asp?1 |
| {repo.host} | Extracts the host from the repository source url | Repository Source URL: https://myrepo.kilnhg.com/Code/Repositories/Group/Test1 {repo.host}: myrepo.kilnhg.com | Issue Server URL: http://{repo.host}/default.asp?{id} Generated Link: http://myrepo.kilnhg.com/default.asp?1 |
| {repo.path} | Extracts the path and query from the repository source url | Repository Source URL: https://git01.codeplex.com/mygitrepo {repo.path}: mygitrepo | Issue Server URL: http://{repo.path}.codeplex.com/workitem/{id} Generated Link: https://mygitrepo.codeplex.com/workitem/1 |
Validation
Once you have given the Commit Message Regex and the Issue Server URL a value, you can validate your settings by providing a typical commit message you would use when checking in a fix for a bug. If the validation was successful, a link will be generated that points to your issue tracker.
Note that if any of the tags in the table above have been used in the Issue Server URL then the validation link will not point to the right location. The reason for this is that these repository tags need a repository to work. On validation, these tags will be generated into dummy information such as www.yourepositoryurl.com
Issue Connector Rules and Restrictions
...
The Name of the Issue Connector is used to reference the Issue Connector throughout the Continua UI. The Issue System is a drop down list of the more popular issue tracking systems. The option you select from the Issue System drop down has no effect on the Issue Connector, it simply pre-populates the "Commit Message Regex" and "Issue Server URL" fields. You could just as easily select "Custom" from the drop down and fill out the other fields with your settings. The two important fields are "Commit Message Regex" and "Issue Server URL".
Commit Message Regex
The Commit Message Regex is a regular expression that tells the issue connector to extract certain data out of commit messages and store them in a named group. To properly construct a regular expression to your needs, determine what your repository commit message will contain then write the regex to extract the issue id out of it. When extracting the id, make sure you use regular expression named groups to name that issue id match to the group "id". You may also add other named groups to your regex which can then be used when generating the URL.
Issue Server URL
The Issue Server URL is a template URL for generating links to your issue system. A simple way to construct the URL is to take a link to a certain issue in your issue system then substitute the issue id field in it with {id}. When the issue id's are parsed out of the commit message using the commit message regex, they'll then be substituted into the template URL where the {id} field was placed.
...