Teamscale IDE Configuration File Format (.teamscale.toml)

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

• File Format (Version 1.0)
  • Supported Properties
  • Unrecognized Properties
  • Alternative Syntaxes
  • Merging Strategy
• Auto-Generating the Configuration File

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.

A minimal configuration file hence looks like this:

[server]
url = "https://teamscale.io/"

[project]
id = "example"

Supported Properties

A configuration file setting every property looks like this:

version = "1.0"
root = false

[server]
url = "https://teamscale.io/"

[project]
id = "example"
branch = "main"
path = "remote/path"

The individual properties are described below.

version

Optional, default 1.0.

The Teamscale IDE configuration file format version of this file.

root

Optional, default false.

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

server.url

Optional, but must be set in the merged configuration.

The URL of the Teamscale server. It must match the URL of a server for which credentials (username and access key) have been configured in the respective IDE.

project.id

Optional, but must be set in the merged configuration.

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 project.id and does not set project.path explicitly, it implicitly sets project.path = "", that is, it associates the current folder with the root folder of the Teamscale project.

project.branch

Optional.

The branch to use for retrieving data from the server.

If empty or unset, the applicable branch is discovered from the version-control system, with the Teamscale default branch as a fallback. If set and non-empty, branch auto-discovery is not used and the given branch is used instead.

project.path

Optional.

The code path within the Teamscale project on the server.

Paths from parent configuration files are overwritten rather than merged. Forward slashes are used as path separators. If empty, that is path = "", the Teamscale project root is used as the code path.

Unrecognized Properties

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"

Alternative Syntaxes

The examples above use TOML's table syntax, where a header such as [project] is followed by the properties nested under project:

[project]
id = "example"
branch = "main"

TOML's dotted-key syntax spells out that nesting in the key itself, which keeps short configuration files more compact:

project.id = "example"
project.branch = "main"

Both syntaxes describe the same configuration and may be combined in one file, for example a dotted server.url key alongside a [project] table. The same table must not be defined twice, though, so [project] and project.id cannot be used in the same file.

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.

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.