Clean-up in TeamCity is a feature allowing automatic deletion of data belonging to old builds.

Since TeamCity 9.0, project-related clean-up settings are configured in the Project Settings (not in the Server Administration | Clean-up Settings section like in previous versions).

The general clean-up configuration is available in the server Administration | Clean-up Settings.

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 TeamCity Data Directory/system and in the database. Also, during the clean-up time the server performs various maintenance tasks (e.g. resets VCS full patch caches).

On this page:

Server Clean-up Settings

The server settings are configured on the Administration | Server Administration | Clean-up Settings.

Since TeamCity 9.0, the build history clean-up is run as a background process, which means that now there is no server maintenance down-time.
(warning) If you use the HSQL database, there is a short period of server unavailability when the HSQL database is being compacted.

Depending on the amount of data to clean up, the process may take significant time, during which the server might be less performant. Therefore, it is recommended to schedule clean-up to run during off-peak hours. By default, TeamCity will start cleaning up daily at 3.00 AM. It is also possible to run it manually.

You can also 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

The Previous clean-up  section of the server clean-up settings enables you to:

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

Project Clean-up Rules

Clean-up rules are configured per project and define when and what data to clean. Different rules can be assigned to a project and templates or build configurations within this project.

To manage the rules, use the Project-Settings | Clean-up Rules page.

The following inheritance rules apply:

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:

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

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:

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

{hidden-data}(build log messages, developers' changes, artifacts, statistical data and so on){hidden-data}

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 snapshot dependencies in other builds. These builds are not deleted from builds history by the clean-up procedure. Artifacts of these builds can be deleted based on the option below.
TeamCity can optionally preserve builds and their artifacts which are used in other builds by artifact dependencies.

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 branches, before applying clean-up rules, TeamCity splits the build history of this configuration into several groups. TeamCity creates one group per each active branch, 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).

Deleted Build Configurations Cleanup

When a project or a build configuration is deleted, the corresponding builds data is removed during the cleanup, but only if 24 hours has passed since the deletion. To change the timeout, set the teamcity.deletedBuildTypes.cleanupTimeout internal property to the required number of seconds to protect the data from deletion.

See also:

Concepts: Dependent Build