# 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

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 NameThe name of the branch to import.
AccountAccount credentials that Teamscale will use to access the repository. Clicking on the button opens a credentials creation dialog.
  • The Account Name setting in the dialog is Teamscale-internal (does not need to match anything in git).
  • When using a file URL (file:///) in the account, make sure that the corresponding repository is bare, i.e. has been cloned with the --bare option.
Path suffixShould Teamscale analyze a only a sub directory of the repository?
Repository identifierTeamscale will use this identifier to distinguish different repositories in the same project. (Teamscale-internal only)
Included file namesOne ore more Ant Patterns separated by comma or newline to restrict the analysis on a subset of files.
Excluded file namesOne ore more Ant Patterns separated by comma or newline to exclude from the analysis.
Include submodulesWhether to also analyze code in submodules.
Submodule recursion depthThe maximum depths of nested submodules that will be analyzed. (Has no effect if Include submodules is not selected.)
SSH Private Key IDThe 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., ssh://username@gitserver/path/to/repo.git), the password entered must be the password for the private key and the username may be left empty.
Enable branch analysisThis 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 master
Included branchesExplicitly control which branches will be analyzed. (hidden if Enable branch analysis is not selected.)
Excluded branchesExplicitly 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 _anon.*
Start revisionThe first revision that will be analyzed. You can enter a date (which selects the first revision after the date) or a revision hash.
Content excludeA comma-separated list of regular expressions. Teamscale will exclude all files that match one of these filters.
Polling intervalHow often should we query the repository and update our findings? (Unit is seconds)

# Team Foundation Server (TFS)-specific Connector Options

Path suffixA 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 suffixThe sub path (relative to the branches) that should be analyzed. Leave empty to analyze all code within each branch.
Branch lookup pathsThe 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 branchesIncluded 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 directoryA path in which to look for branches. Defaults to branches.

# File System-specific Connector Options

Input directoryThe 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., /app/component/trunk/rev1234/artifact.zip.

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 /app/component/trunk/1234/artifact.zip. 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

RepositoryThe name of the Artifactory repository which contains the relevant data
Name Search PatternThe pattern (Artifactory Query Language) on the simple file name used for finding archive files. Supported wildcards are * and ?. Separate multiple patterns with comma or newline.
Example: *.zip
Path Search PatternThe pattern (Artifactory Query Language) on the full path used for finding archive files. Supported wildcards are * and ?. Separate multiple patterns with comma or newline.
Example: component/subcomponent/*
Branch Extraction PatternPattern 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.
Example: component/(trunk|branch)/rev
Timestamp Extraction PatternPattern 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.
Example: /rev(\d+)/
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 PatternPattern 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.
Example: variant/(var1|var2)/componentwill prepend either var1 or var2 to the path used in Teamscale
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 patternA 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).
ProjectsA 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(-|_)(\d+) -> JIRA-$1

# 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.

Jira Server Issue Update Configuration Menu

# TFS Worker Item-specific Issue Tracker Connector Options

AreasA list of full area paths to extract work items from.
Include Sub-AreasIf 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 expressionAn 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.