Teamscale IDE Configuration File Format (.teamscale.toml)

This article describes the uniform configuration file format used to configure the various IDEs supported by Teamscale.

Auto-Generating the Configuration File

A basic configuration file sufficient for many project set-ups can be auto-generated by Teamscale. To do so, select Configure IDE plug-ins / CLI on the Project Configuration > Projects page.

File format (Version 1.0)

The Teamscale IDE configuration is determined by one or more .teamscale.toml files stored in TOML format. Each file may set some properties, e.g., server.url or project.id, which may in turn be overridden by further, more specific .teamscale.toml files. This merging of configuration files makes it possible to succinctly describe even complex setups with a handful of small .teamscale.toml files.

In a single .teamscale.toml file, all properties are optional; thus, an empty file is a valid .teamscale.toml file. However, some properties must be set once all applicable .teamscale.toml files have been merged into a Teamscale IDE configuration.

# The Teamscale IDE configuration file format version of this file.

version = "1.0" # Optional, default: 1.0

# Whether this is the root config file.
# If true, configuration discovery stops at this file and does not continue upwards to the filesystem root.

root = false # Optional, default: false

[server]

# The URL of the Teamscale server.
# If set, it must match the URL of a server for which credentials (Username, Access Key) have been configured in the respective IDE.

url = "https://teamscale.io/" # Optional, but must be set in the merged configuration

[project]

# The Project ID (or one of its Alternative Project IDs) of the Teamscale project.
# Note that the Project ID may be different from the more prominently displayed Project Name.
#
# If a .teamscale.toml file sets the project.id and does not set project.path
# explicitly, then it implicitly sets project.path = "" (i.e., associates the
# current folder with the root folder of the Teamscale project).

id = "example" # Optional, but must be set in the merged configuration

# The branch to use for retrieving data from the server.
# 
# If empty or unset, the applicable branch is discovered from the VCS, with the
# Teamscale default branch being a fallback.
# If set and non-empty, branch auto-discovery is not used. Instead, the given branch is used

branch = "main" # Optional

# The code path within the Teamscale project on the server.
#
# Paths from parent configs will be overwritten.
# Forward-slashes are used as path separators.
# If empty (i.e., path = ""), the Teamscale project root is used as code path.

path = "remote/path" # Optional

A minimal valid config file may look like this using the alternate TOML syntax for nested keys:

server.url = "https://teamscale.io/"
project.id = "example"

Storing unrecognized properties in a .teamscale.toml is allowed. Hence, the following is allowed, even though the server.contact property is not defined in version 1.0 of the file format.

[server]
url = "https://teamscale.io/"
contact = "mailto:admin@teamscale.io"

Merging Strategy

The Discovery and merging strategy for .teamscale.toml files is similar to that of the well-known .editorconfig files.

• A .teamscale.toml inherits all properties (except for version and root) from .teamscale.toml files stored in parent directories unless these are explicitly set, i.e., overridden. Thus, it is possible to store the server URL and project ID only once in a .teamscale.toml file placed in the repository root and set only the project path in .teamscale.toml files placed in subdirectories.

• Discovery of further configuration files stops at a .teamscale.toml file with the root property set to true.