Integrate with GitHub

TestRail integrates with GitHub so your team can link, view, add, and push issues between TestRail and GitHub as bugs/defects, requirements/references, or both. The TestRail integration with GitHub supports the following use cases:

• Link test cases to requirements
• Start creating requirements from TestRail
• View requirements in TestRail
• Link defects to test results
• Submit new defects in GitHub
• Submit new defects from TestRail
• View defects in TestRail

You don’t have to use all the listed integration options; you can mix and match the integration with other tools. Configuring the integration usually only takes a few minutes. This guide explains how to configure the integration and how it works.

Link test cases to requirements

To set up test coverage, when you are creating or editing test cases, simply add one or more work item IDs (separated by commas) to the References field.

The References you set in your test cases will be converted to a direct link to GitHub issues.

Start creating requirements from TestRail

GitHub issues can serve as a source of requirements, making them valuable references for test cases. TestRail offers a convenient Add link feature within the test case editor view, enabling seamless navigation to the GitHub issues screen. This feature expedites the process of creating new requirements that you wish to associate with your test cases. It's important to remember that once you've created a new work item, you should copy and paste its ID into the References field for proper traceability.

Configuring the Reference Add Url

To start creating new requirements from TestRail, you should configure the GitHub Reference Add Url in TestRail by following the steps below.

• Go to the Administration page, select Integration to configure globally or Projects for a single project, and open the References tab
• Insert your the Reference Add Url using the following pattern https://github.com/<OWNER>/<REPOSITORY>/issues/new
• Click Save Settings
  
  

View requirements in TestRail

TestRail can retrieve additional information from IDs entered into the References field of TestRail entities, such as test cases, test runs, and milestones. Simply hover over the links and a dialog will show you all the latest information without having to navigate to GitHub.

Configuring the Reference Plugin

To view requirements directly in TestRail, you should configure the GitHub Reference Plugin in TestRail by following the steps below.

• Go to the Administration page, select Integration to configure globally or Projects for a single project, and open the References tab
• Select your GitHub variant in the Reference Plugin drop-down list
• Configure the connection settings in the [connection] section
  • address: https://<GitHub_URL>/
  • user: your username for Github
  • password: your GitHub personal access token (PAT)
  • owner: owner of the GitHub repository
  • name: name of the GitHub repository
• Click Save Settings
  
  
  

Link defects to test results

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.

When you set up the Defect View URL integration with GitHub Issues, you can paste the ID of a GitHub issue in the Defects field of a test result and TestRail will automatically convert that ID into a clickable link to view the issue in GitHub. This allows your team to link tests with GitHub issues and create defect and traceability reports in TestRail

Configuring the Defect View Url

To link defects to test results in TestRail, you should configure the GitHub Defect View Url in TestRail by following the steps below.

• Go to the Administration page, select Integration to configure globally or Projects for a single project, and open the Defects tab
• Insert your Defect View Url using the following pattern https://github.com/<OWNER>/<REPOSITORY>/issues/%id%
• Click Save Settings

Note : Please make sure to replace <OWNER> and <REPOSITORY>with the actual repository and the owner name in GitHub you want to integrate with.

Submit new defects in GitHub

TestRail provides quick navigation to report defects using the GitHub interface. You can do it from two different places - the Defects menu and the Add Test Result dialog.

The Defects menu, also known as TestRail’s Defect From Anywhere feature, is displayed on top of most pages for quick access.

The Add Test Result dialog displays the Add link next to the Defects field for quickly and conveniently navigating to GitHub in order to submit a defect when your test is failing.

Configuring the Defect Add Url

To quickly navigate to GutHub to create a new defect, you should configure GitHub Defect Url in TestRail by following the steps below.

• Go to the Administration page, select Integration to configure globally or Projects for a single project, and open the Defects tab
• Insert your Defect Add Url using the following pattern https://github.com/<OWNER>/<REPOSITORY>/issues/new
• Click Save Settings
  
  

Note : Please make sure to replace <OWNER> and <REPOSITORY> with the actual repo and the owner name in GitHub you want to integrate with.

Submit new defects from TestRail

To enhance the seamless integration of defect reporting, TestRail offers a pre-configured GitHub defect plugin. This plugin empowers you to effortlessly submit new issues to GitHub directly from within TestRail.

By utilizing the intuitive Push Defect dialog, you can swiftly generate a fresh defect complete with a title, description, and any additional fields that GitHub supports. This streamlined process ensures a smoother defect management workflow.

You can open the defect submission dialog from two places - the Defects menu and the Add Test Result dialog.

The Defects menu, also known as TestRail’s Defect From Anywhere feature, is displayed on top of most pages for quick access.

The Add Test Result dialog displays the Push link next to the Defects field to efficiently report a defect while you're submitting your test results.

Configuring the Defect Plugin

To submit new defects straight from TestRail, you should configure the GutHub Defect Plugin in TestRail by following the steps below.

• Go to the Administration page, select Integration to configure globally or Projects for a single project, and open the References tab
• Select your GitHub variant in the Reference Plugin drop-down list
• Configure the connection settings in the [connection] section
  • address: https://<GitHub_URL>/
  • user: your username for GitHub
  • password: your GitHub personal access token ( PAT)
  • owner: owner of the GitHub repository
  • name: name of the GitHub repository
• Click Save Settings
  
  
  

View defects in TestRail

Simply hover over defect links and a dialog will show you all the latest information without having to navigate to GutHub. These links are available in the test results directly, as well as the Defects section on test runs, test plans and milestones.

Configuring the Defect Plugin

To submit new defects straight from TestRail, you should configure the GutHub Defect Plugin in TestRail by following the steps below.

• Go to the Administration page, select Integration to configure globally or Projects for a single project, and open the References tab
• Select your GitHub variant in the Reference Plugin drop-down list
• Configure the connection settings in the [connection] section
  • address: https://<GitHub_URL>/
  • user: your username for GitHub
  • password: your GitHub personal access token (PAT)
  • owner: owner of the GitHub repository
  • name: name of the GitHub repository
• Click Save Settings
  
  
  

It is also possible to customize the fields that appear via link hovering. You can see more information on how to do it on the Customizing the Requirement/Defect Plugins section.

Advanced customizations

User variables

We recommend using User Variables when configuring any integration credentials. This allows you to provide generic credentials without disclosing them, and also lets users define their own credentials in their personal settings, for better access control. Below you can see an example of how to set variables in your configuration.

user=%github_username%
password=%github_password%

Customizing the Requirement/Defect Plugins

The GitHub 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 work item IDs, both for requirements and defects. Preconfigured push fields and hover fields can be set to on or off in their respective [push.fields] and [hover.fields] sections, and you can also change their order, which will be reflected in the UI.

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.

[push.field.description]
label=Detailed Description
required=true

Please see below for full list and explanation of the available field options:

Attachments

The GitHub Defect Plugin supports submitting attachments to GitHub as well. This field can be turned on and off, but cannot be customized. To submit one or more attachments to GitHub, simply drag the attachment to the attachments or description areas of the push dialog or click on the area to choose an attachment from your file system.