Integrating TeamCity with GitHub Issues

GitHub issues allow your development team to prioritize the current problems, break them down into actionable tasks, and track their statuses.

If a commit message includes a reference to an existing issue, TeamCity shows a link to this issue on the build history and Build Results pages.

This integration also works for projects with configured Pull Requests feature: if a pull request mentions an existing issue, TeamCity displays corresponding data in its UI.

Note that with this integration in place, any string that matches the GitHub issue ID pattern (for example, #054) is treated as a reference to the corresponding GitHub issue and converted to a clickable link. For example, you may reference issues when writing a reason for manually switching the build status to "Successful" or "Failed".

If your GitHub repository has no issue with this ID, the Issue not found hint is shown.

Configure the GitHub Issues Integration

Before you start, make sure the GitHub issues feature is enabled in your repository, and that there is at least one active issue.

In TeamCity, navigate to project settings (Administration | <Your_Project>) and switch to the Issue Trackers tab.
Click Create New Connection and choose GitHub as the connection type.
Enter the public name for your integration. This name is used solely for TeamCity UI.

Fill in the repository URL and authentication fields. You can enter all data manually or leverage existing GitHub connections.

In the Repository URL field, enter the URL of your repository main page (not the clone URL). For example, https://github.com/johndoe/my-repo (not https://github.com/johndoe/my-repo.git or git@github.com:johndoe/my-repo.git).
Choose the required Authentication method.
- Anonymous authentication can be used for public repositories and issues that do not require users to log in.
- Access token requires a static personal token issued on GitHub.
- GitHub App access token is the most secure option that leverages dynamic non-personal tokens. If the repository whose URL you specified is available via an existing GitHub App connection, TeamCity will display this connection along with the Acquire button. Click it to issue a new token that will allow TeamCity to access this repository.

Click a GitHub icon next to the the Repository URL field.

TeamCity will scan for repositories available through the related connection. Choose the required repository and all required options (including authentication settings) will be filled in automatically.

In the Issue ID Pattern field, specify a regular expression pattern to filter the issues that belong to this project. You can usually leave this at the default setting, #(\d+). See this article for more information: Converting Strings into Links to Issues
Click Test Connection and follow the dialog instructions to test the issue tracker connection.
Click Create to save your settings and exit the setup.

Kotlin DSL

To create a TeamCity-GitHub issue integration in Kotlin DSL, add a new githubIssues object to the features block of your project.

project {
    // ...
    features {
        githubIssues {
            id = "PROJECT_EXT_17"
            displayName = "Default GH Issue Tracker"
            repositoryURL = "..."
            authType = storedToken {
                tokenId = "..."
            }
        }
    }
}

Last modified: 26 January 2024