TeamCity 8.0 Help


Clean-up in TeamCity is a feature allowing automatic deletion of data belonging to old builds. Clean-up settings are configured under Administration | Project-related Settings | Build History Clean-up.

It is recommended to configure clean-up rules to remove obsolete builds and their artifacts, purge unnecessary data from database and caches in order to free disk space, remove builds from the TeamCity UI and reduce the TeamCity workload.

Clean-up deletes the data stored under /system and in the database. Also, during the clean-up time the server performs various maintenance tasks (e.g. resets VCS full patch caches).

Clean-up Settings

Depending on the amount of data to clean up, the process may take significant time, during which the server will be unavailable for other users. You can schedule clean-up to to run daily during off-peak hours. By default, TeamCity will start cleaning up at 3.00 AM. It is also possible to Manual-Clean-up-Launch.

To ensure the server availability, you can specify the time limit for the clean-up process. In case not all the data is purged within the time-frame specified, the remaining data will be removed during the next clean-up process.

Manual Clean-up Launch

You can run clean-up manually. TeamCity provides the information on the last clean-up duration helping you decide whether to launch the clean-up process at a given moment.

During clean-up, TeamCity informs you on the progress. If you need, you can stop the clean-up process and the remaining data will be removed during the next clean-up.

Clean-up Rules

A clean-up rule defines when and what data to clean. Clean-up rules can be assigned to a project, template or build configuration.

To manage the rules, use the Administration | Project-related Settings | Build History Clean-up page, Configure clean-up rules section.

The following inheritance rules apply:

  • if a clean-up rule is assigned to a project, it becomes default for all configurations or subprojects in this project

  • if a clean-up rule is assigned to a template, it becomes default for all configurations inherited from this template, but if a clean-up rule is assigned to both a template and a project, the rule from the project will override the rule from the template

  • if a clean-up rule is assigned to a build configuration, it will override the clean-up rule from a project or a template.

In each rule, you can define a number of successful builds to preserve, and/or the period of time to keep builds in history (e.g. keep builds for 7 days).

The following clean-up levels are available:

  • Artifacts (all other data including build logs is preserved. Build Artifact are also preserved);

  • History (all the build data is deleted except for builds statistics values that are visible in the Statistic Charts);

  • Everything (no build data remains in TeamCity). Each level includes the one(s) listed above it.

By default, everything is kept forever. When you select custom settings, for each of the items above you can specify:

  • the number of days. Builds older than the number of days specified will be cleaned with the specified level. The starting point is the date of the last build, not the current date. A day is equivalent to a 24-hour period, not a calendar day;

  • the number of successful builds. Only builds older than the last matching successful build will be cleaned with the level specified (all the failed builds between the preserved successful ones are kept). This rule is only taken into account if there are successful builds in the build configuration.

When both conditions are specified, only the builds which must be cleaned according to all rules will be actually removed: TeamCity finds the oldest build to preserve according to each of the the rules and then cleans all builds older than the oldest one of the two found.

For the Artifacts level you can also specify the patterns for the artifact names:

  • Artifact patterns. The artifacts matching the specified pattern will be included in/excluded from the clean-up. Use newline-delimited rules following Ant-like pattern. Example: to clean-up artifacts with 'file' as a part of the name, use the following syntax: +:**/file*.*. To exclude *.jar artifacts with 'file' as a part of the name from clean-up, use -:**/file*.jar.

There are builds that preserve all their data and are not affected during cleanup. These are:

Clean-up for Dependent Builds

The settings in the Dependencies section of the Edit Clean Up Rules dialog affect clean-up of artifacts in builds that the builds of the current build configuration depend on.

TeamCity always preserves builds which are used as Dependent Build in other builds. These builds and their associated data (e.g. artifacts) are never deleted by the clean-up procedure.

TeamCity can optionally preserve builds which are used in other builds by Dependent Build.

  • Use default choice uses the option configured in the default cleanup rule.

  • Prevent clean-up choice protects builds (and their artifacts) which were used as a source of artifact dependencies for the builds of the current build configuration. By default, TeamCity does not prevent dependency artifacts cleanup.

  • Do not prevent clean-up choice makes cleanup-related processing of the dependency builds disregard the fact that they are used by the builds of the current build configuration.

Example: Say, a build configuration A has an artifact dependency on B. If Prevent clean-up option is used for A, the builds of B that provide artifacts for the builds of A will not be processed while cleaning the builds, so the builds and their artifacts will be preserved.

Clean-up in Build Configurations with Feature Branches

If a build configuration has builds from several Working with Feature Branches, before applying clean-up rules, TeamCity splits the build history of this configuration into several groups. TeamCity creates one group per each Working with Feature Branches, and a single group for all builds from inactive branches. Then clean-up rules are applied to each group independently.

Clean-up of Personal Builds

Cleanup rules are applied separately for the non-personal builds and then for the personal builds. That is, if you have a rule to preserve 3 successful builds, 3 non-personal builds and 3 personal builds are preserved (in each branch group as per description above).

Last modified: 20 April 2023