Clean-up in TeamCity is a feature allowing automatic deletion of data belonging to old builds.
Project-related clean-up settings are configured in the Project Settings (prior to TeamCity 9.0, the Server Administration | Clean-up Settings section was used).
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.
The build history clean-up is run as a background process, which means that now there is no server maintenance down-time.
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.
With clean-up enabled, TeamCity will keep the server audit records for a year (365 days) by default.
Manual Clean-up Launch
The Previous clean-up section of the server clean-up settings enables you to:
- review the information on the previous server clean-up date and duration helping you decide whether to launch the clean-up process at a given moment
- run clean-up manually using the Start clean-up now button.
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:
- 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. Hidden Artifacts are also preserved);
- History (all the build data is deleted except for builds statistics values that are visible in the statistics 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 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.
- to clean-up artifacts with 'file' as a part of the name, use the following syntax:
- to exclude
*.jarartifacts with 'file' as a part of the name from clean-up, use
There are builds that preserve all their data and are not affected during cleanup. These are:
- pinned builds;
- builds used as a source for artifact dependency in other builds when the "Prevent clean-up" option for dependency artifacts is enabled. See Clean-Up for Dependent Builds below. Such builds are marked with icon in the build history list;
- builds used as snapshot dependency in other not yet deleted builds;
- builds of build configurations that were deleted less than one day ago.
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.
- 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 or snapshot dependencies for the builds of the current build configuration.
- Do not prevent clean-up (default) choice makes cleanup-related processing of the dependency builds disregard the fact that they are used by the builds of the current build configuration.
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.