# Repository Connector Options Reference (SVN, Git, Azure DevOps, etc.)
To create a project, Teamscale needs to be connected to your version control system. To this end, it offers several different repository connectors. We describe the options for each repository connector.
- Shared Connector Options
- Subversion (SVN) branch analysis
- Azure DevOps Team Foundation Version Control Credentials (formerly called Team Foundation Server (TFS))
- Artifactory Connector Options
- Issue Tracker Connector Options
- Jira Server Issue Update Option Details
# Shared Connector Options
Setting up the other connectors to source code repositories and issue trackers is very similar to the Git connector setup. Many connectors share general options such as a polling interval and therefore, we only describe the options (if there are any) for first connector that uses it. If there are no additional options in a connector, we don't document the connector separately.
# Common and Git-specific Connector Options
|Default branch Name||The name of the branch to import.|
|Account||Account credentials that Teamscale will use to access the
repository. Clicking on the button opens a credentials creation dialog.
|Path suffix||Should Teamscale analyze a only a sub directory of the repository?|
|Repository identifier||Teamscale will use this identifier to distinguish different repositories in the same project. (Teamscale-internal only)|
|Included file names||One ore more Ant Patterns separated by comma or newline to restrict the analysis on a subset of files.|
|Excluded file names||One ore more Ant Patterns separated by comma or newline to exclude from the analysis.|
|Include submodules||Whether to also analyze code in submodules.|
|Submodule recursion depth||The maximum depths of nested submodules that will be analyzed. (Has no effect if Include submodules is not selected.)|
|SSH Private Key ID||The ID of a SSH private key stored in Teamscale which will be used when connecting to a Git Account over SSH.
You can manage all your Git private keys on the Settings page of the Admin perspective, in the Git section. When using a Git private key, the Account used by the connector has to be configured as follows: The URL has to contain the user name (e.g.,
|Enable branch analysis||This checkbox activates our new branch support feature. If you select it, Teamscale will analyze all branches of the repository. If branch analysis is enabled, the Default branch Name option specifies the main branch (usually |
|Included branches||Explicitly control which branches will be analyzed. (hidden if Enable branch analysis is not selected.)|
|Excluded branches||Explicitly state which branches to exclude. Note that Teamscale will create so called anonymous branches for all historic branches whose name could not be reconstructed. By default these are filtered using the exclude pattern |
|Start revision||The first revision that will be analyzed. You can enter a date (which selects the first revision after the date) or a revision hash.|
|Content exclude||A comma-separated list of regular expressions. Teamscale will exclude all files that match one of these filters.|
|Polling interval||How often should we query the repository and update our findings? (Unit is seconds)|
# Team Foundation Server (TFS)-specific Connector Options
|Path suffix||A common sub directory on the Azure DevOps Server appended to the account URI. Leave empty if the whole directory structure is relevant. This is the root directory when looking for branches if branching is enabled.|
|Branch path suffix||The sub path (relative to the branches) that should be analyzed. Leave empty to analyze all code within each branch.|
|Branch lookup paths||The paths in the repository separated by commas where Teamscale will search for branches within the root directory defined by the Path suffix and account URI. If set, Teamscale only looks for branches on the top level of each branch lookup path. If empty only the root directory is searched for branches on the top level.|
|Included/Excluded branches||Included and excluded branches must contain the full path to the branch relative to the root directory. This means the Branch lookup paths appended with the contained branch|
# Subversion (SVN)-specific Connector Options
|Branches directory||A path in which to look for branches.
Defaults to |
# File System-specific Connector Options
|Input directory||The path of the source-code directory|
# Subversion (SVN) branch analysis
Subversion by itself does not support real branches, but rather uses its cheap copy operation and folder naming conventions for managing logical branches. For Teamscale to recognize a folder as a branch, it must either by a top-level folder trunk or a folder below the branches directory configured for the repository (defaults to branches). Then enable branch support and configure the URL of the SVN connector to point to the project folder, i.e., the one containing trunk and the configured branches directory. If the SVN repository in question is using the standard SVN layout, then you can simply use the branches directory option's default.
Note that Teamscale assumes all folders directly within the branches directory to be actual branches. Using further folder hierarchies to organize your branches is currently not supported. More specifically, a branch name may never contain a slash. Also, as Teamscale analyzes your history, even branches that have been deleted from the branches folder will be found and potentially be analyzed, as they are part of the recorded history. If you want to prevent this, either set a start date after the time the branch was deleted or exclude the corresponding branches using the branch exclude patterns.
# Azure DevOps Team Foundation Version Control Credentials (formerly called Team Foundation Server (TFS))
When connecting to Azure DevOps TFVC via a repository connector, you may use either the account credentials of a domain user or a personal access token (if these are enabled in your Azure DevOps).
When configuring an account credential for an access token, enter the Azure DevOps access token in the Access Token field. The Username is optional in this case. By convention, you may use the name of the access token.
# Azure DevOps Boards (formerly called Team Foundation Server Work Items)
When connecting to a Azure DevOps Server via an issue connector, please verify whether the Basic Authentication option is enabled in your IIS or not. Depending on this option, you may need to use different credentials than you used for your repository connector when connecting to the Azure DevOps to retrieve work items.
# With Basic Authentication enabled:
You must connect with the credentials (username and password) of a Azure DevOps user account. Connecting with personal access tokens will not work. This may either be a domain user or a Azure DevOps user with the necessary rights to read work items.
# With Basic Authentication disabled:
You must connect with a personal access token. Connecting with a user account (username + password) will not work. Put the personal access token in the Password field in the Teamscale UI. Configuring a Username in Teamscale is optional in this case. By convention, you may use the name of the TFS access token.
# Artifactory Connector Options
Artifactory is a tool hosting a repository where build artifacts can be
stored. Examples of such artifacts are generated code or findings
generated by some external tool. It is good practice to store these in a
versioned manner with a reference to the revision used to generate the
given artifacts. This can be easily achieved by encoding the revision in
the path of the artifact, e.g.,
Teamscale can extract such metadata from the artifact path and use it to link revisions in Artifactory to revisions in source-code repositories.
# Artifactory Connector Options
To extract metadata from paths, Teamscale offers a variety of extraction options that can be configured in the Artifactory Repository Connector. These options are defined by regular expressions with exactly one capturing group. The regular expression will be applied to the complete path of the imported artifact, and the content of the capturing group will be interpreted as the data to be extracted.
If the Artifactory file layout is not yet fixed, it may prove helpful to keep ease of extraction in mind when deciding on a structure. For example, paths should include the names of the fields Teamscale should extract. This allows simpler regular expressions than when having to derive the fields from the repository layout, especially if that layout is highly diverse across different projects.
Consequently, the path
/app/component/branch_trunk/rev_1234/artifact.zip is easier to parse than the path
However, Teamscale is flexible enough to accommodate all repository structures, even when the layout is already established.
Teamscale assumes that uploads to Artifactory are typically triggered by VCS commits. Some configuration options only make sense in this light, e.g., "Timestamp Interpretation". This option allows relating an Artifactory upload to some previous repository commit.
# Artifactory Connector Configuration
|Repository||The name of the Artifactory repository which contains the relevant data|
|Name Search Pattern||The pattern (Artifactory Query Language) on the
simple file name used for finding archive files. Supported wildcards are
|Path Search Pattern||The pattern (Artifactory Query Language) on the full
path used for finding archive files. Supported wildcards are |
|Branch Extraction Pattern||Pattern used to
extract the branch name from the full path. A regex pattern with exactly
one capturing group. The group is used to find the branch name from the
archive's path. |
|Timestamp Extraction Pattern||Pattern used
to extract the timestamp or revision from the full path. A regex pattern
with exactly one capturing group. The group is used to find the
timestamp name from the archive's path. If this is empty, the creation
date from Artifactory will be used. |
|Timestamp Interpretation||Describes how to interpret the value from timestamp extraction. Possible values are 'date:pattern', where pattern is a Java time format descriptor, 'timestamp:seconds' and 'timestamp:millis' for unix timestamps in seconds or milliseconds, 'connector:repository-identifier' to interpret the value as a revision of a connector in the same project, 'svn:account-name' to interpret the value as a Subversion revision, and 'git:account-name' to interpret the value as a git commit hash for a repository using the 'File System' connector.|
|Prefix Extraction Pattern||Pattern used to
extract an additional prefix that is placed before the name of files
extracted from the ZIP files. A regex pattern with exactly one capturing
group. The group is used to find the prefix from the archive's path. If
this is empty, no prefix will be used. |
|Ignore extraction failures (expert option)||When checked, Teamscale will try to ignore errors during timestamp extraction according to the given extraction pattern. This can be useful when many non-conforming paths are expected to be analyzed alongside the conforming paths. When this is unchecked, such errors will stop the import until they are corrected (to avoid importing inconsistent data). When this option is checked, the non-conforming paths will be skipped but all conforming paths will still be imported.|
# Issue Tracker Connector Options
# Options for all Issue Tracker Connectors
|Issue ID pattern||A regular expression that matches the issue ID inside commit messages. Must contain at least one capturing group. The first capturing group of the regular expression must match the entire issue ID as it is used by the issue tracker. For example, for JIRA a valid pattern might be `(JIRA-\\d+)` . If the regular expression can match alternate spellings that the issue tracker does not consider valid issue IDs, then these spellings must be normalized using an Issue ID transformation (see below).|
|Projects||A comma-separated list of project names from the issue tracker. Only issues from these projects will be imported|
|Issue ID transformation (expert option)||A
regular expression matching all spellings of an issue ID that may occur
inside commit messages together with a replacement expression that
converts the alternate spellings into the normalized spelling required
by the issue tracker. For example, |
# Jira-specific Issue Tracker Connector Options
|Add to Jira issues||Allows to configure active (push) update of Jira issues with analysis results from Teamscale. The Jira issue update configuration menu is shown below. An example of a Jira issue field enhanced with Teamscale-generated data can be seen in this guide.|
# TFS Worker Item-specific Issue Tracker Connector Options
|Areas||A list of full area paths to extract work items from.|
|Include Sub-Areas||If checked, issues from sub-areas are retrieved as well, otherwise just issues exactly matching one of the area paths are retrieved.|
# RTC/Jazz-specific Issue Tracker Connector Options
|Field filter expression||An expression used to filter issues that should be imported. Must conform to RTC/Jazz’s Reportable REST API specification.|
# Jira Server Issue Update Option Details
The Add to Jira issues (expert option) allows to configure the type of Teamscale analysis results appended to Jira issues as well as the destination field(s) of Teamscale-generated data in matched issues. Following analysis results can be appended to matched Jira issues:
Findings balance suboption allows to update Jira issue(s) with finding badges that contain the counts of added/removed/changed code findings introduced by the respective issue(s).
Test gap suboption allows to update Jira issue(s) with the test gap ratio of the respective issue(s). The test gap ratio also includes changes from child issues in case the Jira issue acts as a parent for other issues.
Both suboptions are linked to the Issue perspective where all issue-related information can be viewed.
Additionally, it is possible to configure the field(s) of Jira issues that Teamscale-generated data should be appended to:
Issue description suboption allows to append Teamscale-generated data to issue description.
Custom field(s) suboption allows to append Teamscale-generated data to specified custom fields. The custom fields have to be created by Jira Administrator and be of Text Field (multi-line) type.