Linkers
Fisheye can render any issue IDs or Bug IDs that appear in commit messages or comments as hyperlinks. Users can click the links to quickly navigate to the relevant issue/bug in your issue/bug tracker. This link rendering relies on Fisheye detecting certain substrings in commit messages and comments. You can configure the "linker" patterns that Fisheye uses to detect these substrings for each repository in Fisheye.
Please note, if you have set up Jira integration between your Fisheye instance and a Jira server, you will need to disable linkers for that Jira server. Otherwise, the linkers will override the integration features described on that page (which includes linkers).
On this page:
Configuring linkers
You can configure linkers for a specific repository or configure linkers for all repositories.
Configure linkers for a specific repository
- Click the 'cog' menu in the Fisheye header, and choose Administration (you'll need to be logged in as an administrator to see this link).
- Click the Repositories link. The list of repositories set up in your Fisheye instance will be displayed.
- Click the name of the repository, (under the Name column in the list of repositories). The Repository Options for the repository will be displayed in a dialog.
- Click the Linkers tab. The 'Linkers' screen will be displayed (see screenshot below).
- Configure the linkers for the repository as desired:
- Click the Add... link to add a new linker. See the Adding a Linker section below for further instructions.
- Click the cog icon () next to a linker and click Edit from the dropdown menu to edit a linker. The editable 'Linker' dialog is identical to the 'Add a Link' dialog, except that you cannot change the link type. See the Adding a Linker section below for further instructions.
- Click the cog icon () next to a linker and click Delete from the dropdown menu to delete the linker.
- Save your changes.
Configure linkers for all repositories
- Click the 'cog' menu in the Fisheye header, and choose Administration (you'll need to be logged in as an administrator to see this link).
- Click Defaults. The 'Repository Defaults' will be displayed, with the Linkers tab shown (see screenshot below).
- Configure the linkers for all repositories as required:
- Click Add... to add a new linker. Any new linkers added in the repository defaults will be inherited by all repositories. See the Adding a Linker section below for further instructions.
- To edit a linker, click the cog icon () for a linker and click Edit. The editable 'Linker' dialog is identical to the 'Add a Link' dialog, except that you cannot change the link type. See the Adding a Linker section below for further instructions.
- To delete a linker, click the cog icon () for a linker and choose Delete.
- Save your changes.
Add a linker
- Navigate to the linkers for a specific repository or the repository defaults, as described above, and click the Add... link to add a new linker.
- Complete the fields on the dialog as follows:
- Linker Type — Select 'Simple' or 'Advanced'. Choose 'Simple' unless you are an experienced developer.
- Description — Enter a description for your linker.
- Regular Expression ('Simple' Linker Type) — Enter the regular expression defining the pattern that Fisheye will look for when rendering links. Fisheye uses the Java regular expression language, which is based on Perl 5 regular expressions. You can test your regular expressions on this online test page.
Tip: If you want your regex to be case insensitive, put(?i)
at the start of the regex. - Href ('Simple' Linker Type) — Enter the destination of the link. For example, http://jira.mycompany.com/browse/${0}
- SyntaxDef ('Advanced' Linker Type) — See Configuring the SyntaxDef Field section below.
- Click Add.
- Save your changes.
Tip: See the Example Linkers section below for examples of linkers to Jira and Bugzilla servers.
Example linkers
Here are some examples of simple linkers.
Jira examples
Do not create linkers for a Jira server, if you have already set up Jira integration between your Fisheye instance and that Jira server.
To link any occurrence of a Jira-style issue to Jira:
Regex: [a-zA-Z]{2,}-\d+ Href: http://jirahost:8080/browse/${0}
The regular expression above matches any sequence of two or more alphabetical characters, followed by a dash, followed by a number, which comprise the format of Jira isssue IDs (such as AB-123 or ABC-123 or ABCDE-123). Replace
jirahost
with the hostname of the desired Jira instance.
To link a specific set of Jira projects (e.g. JRA, CONF and CRUC) to a Jira instance:
Regex: (JRA|CONF|CRUC)-\d+ Href: http://jirahost:8080/browse/${0}
The regular expression above matches only specific Jira issue keys with any number, like JRA-123 or CONF-123 or CRUC-123. Replace
jirahost
with the hostname of the desired Jira instance.
Bamboo examples
To link to specific Bamboo builds:
Regex: (ABC)-[a-zA-Z]+-\d+ Href: http://bamboohost/browse/${0}
The regular expression above matches Bamboo build IDs like ABC-MAIN-123 or ABC-BRANCH-123. These will then be made links to the build reports in your Bamboo instance. Replace
bamboohost
with the hostname of the desired bamboo instance.
Bugzilla examples
To link bug numbers that occur at the start of a line to Bugzilla:
Regex: ^BUG: (\d+) Href: http://bugzilla/bugzilla/show_bug.cgi?id=${1}
To link bug numbers that occur after the word bug and optionally whitespace, ":" or "#" (e.g. Bug123, bug:123, or BUG #123):
Regex: (?i)bug[#|\s|:]*(\d+) Href: http://bugzilla/bugzilla/show_bug.cgi?id=${1}
The regular expressions above matches Bugzilla bug IDs. These will then be made links to build reports in your Bamboo instance.
Configuring the SyntaxDef field
This is an advanced feature, intended for use by experienced developers only.
Please note;
- The description is optional.
- You will want to define the three region properties as in the example below.
This example matches numbers that appear after a PR: and might be seperated by commas or 'and
':
PR: 123
PR: 123 456
PR: 123, 456
PR: 123, 456 and 789
<syntaxdef>
/PR:\s*((\d+\s*(and|,)?\s*)+)/i : {
nummatcher(${1});
}
context nummatcher {
/\d+/ : {
region {
href="http://issues.apache.org/bugzilla/show_bug.cgi?id=${0}";
}
}
}
Understanding the SyntaxDef example:
- The first regex matches means: match "PR:" followed by a sequence of numbers ("\d+") separated by whitespace,
'and
' or commas. - The "context" means in the above match, link each number individually.