The defect URLs are used to let TestRail know how to convert a Defect ID into a URL for your GitHub instance. There are two types of URLs: View URLs and Add URLs.

The Defect View URL is used to build a link to GitHub based on the Defect ID, so you can simply click on an ID to open the issue directly in GitHub.

The Defect Add URL is used to create a link to the issue creation screen inside GitHub. Once the URL is configured, a new Add link appears next to the Defects field in the Add Test Result dialog and the ‘Defects’ menu in TestRail’s Push Defect From Anywhere feature. This link allows you to jump to GitHub’s New Issue form to report a new bug.

If you see the ‘Add’ link, you can copy the ID of your new GitHub issue and enter it into any Defects or References field inside TestRail.

The reference URLs are implemented in a very similar manner to Defect URLs described above. The primary difference is Reference URLs are used for the ‘References’ field on various TestRail entities (instead of the Defects field).

The Reference View URL is configured in the same manner as described above and allows TestRail to create a direct link to a GitHub based on an ID entered into a References field.

The Reference  Add URL is also configured in the same way as the Defect Add URL. Once configured, an ‘Add’ link will appear next to each References field in your instance or project. If you use the ‘Add’ link, you can copy the ID of your new GitHub issue and enter it into any Defects or References field inside TestRail.

If you have the Reference plugin configured, you’ll also be able to hover over a Reference ID to view the issue details directly from within TestRail. Keep reading to learn how to use and configure the Defect and Reference Plugins.

Defect plugins can be used to implement a deeper bug tracker integration and TestRail comes with a ready-to-use GitHub defect plugin. To configure the defect plugin, select Administration > Integration and select GitHub in the Defect Plugin drop-down list. The next step is to configure all the necessary connection settings in the [connection] category. You can also configure the integration for a specific project by editing a project’s settings.

The Defect Plugin utilizes GitHub’s API, so valid credentials are needed to connect to the API. You can enter a single set of credentials here for all GitHub users. or you can insert User Variables to allow each TestRail user to configure their own credentials. These credentials may be a combination of an email address or username with a password or API key.

The GitHub defect plugin was built to work with a standard GitHub configuration. TestRail allows you to customize the fields which appear in the Push dialog as well as when hovering over Defect IDs. Preconfigured push fields and hover fields can be set to ‘on’ or ‘off’ in their respective [push.fields] and [hover.fields] sections, or change the order in which they appear by the fields in each section.

Please keep in mind some fields (such as the title field) are always enabled and may not appear in these sections due to always beings required by either TestRail or GitHub.

The GitHub Defect Plugin also supports modifying field properties as well as custom fields.

In addition to enabling, disabling, or re-organizing fields as described above, it’s also possible to change additional options per field. To do this, you would define a section for the field, such as [push.field.description] and specify additional options within this section.

Reference plugins can be used to retrieve additional information from IDs entered into the References field of TestRail entities, such as test cases, test runs, and milestones. The Reference Plugin is configured on the References tab of the integration settings in the same manner the Defect Plugin is configured.

The plugin supports hovering over Reference IDs but does not support a Push dialog for the References field. It is also possible to customize the fields which appear via link hovering and add custom fields, as described above.

If you have the Defect Plugin already configured for GitHub, you can simply copy your [connection] and [hover.fields] sections from the Defect Plugin into the Reference plugin configuration. Alternatively, you can choose different fields to be displayed for References and Defects.