Dormant project deletion

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

• Introduced in GitLab 15.0 with a flag named inactive_projects_deletion. Disabled by default.
• Feature flag inactive_projects_deletion removed in GitLab 15.4.
• Configuration through GitLab UI introduced in GitLab 15.1.
• Renamed from inactive project deletion in GitLab 18.1.

{{< /history >}}

Over time, projects in large GitLab instances can become dormant and use unnecessary disk space.

You can configure GitLab to automatically delete dormant projects after a specific period of inactivity. When a project has no activity within this defined period:

• Maintainers receive notifications that warn about the scheduled deletion.
• If no activity occurs in the project, GitLab deletes it when the timeframe expires.
• When deletion occurs, GitLab generates an audit event that shows @GitLab-Admin-Bot performed the deletion.

For the default setting on GitLab.com, see GitLab.com settings.

Configure dormant project deletion

Prerequisites:

• Administrator access.

To configure deletion of dormant projects:

1. In the upper-right corner, select Admin.
2. Select Settings > Repository.
3. Expand Repository maintenance.
4. In the Dormant project deletion section, select Delete dormant projects.
5. Configure the settings.
   • The warning email is sent to users who have the Owner and Maintainer role for the dormant project.
   • The email duration must be less than the Delete project after duration.
6. Select Save changes.

Dormant projects that meet the criteria are scheduled for deletion and a warning email is sent. If the projects remain dormant, they are deleted after the specified duration. These projects are deleted even if the project is archived.

Configuration example

Example 1

If you use these settings:

• Delete dormant projects enabled.
• Delete dormant projects that exceed set to 50.
• Delete project after set to 12.
• Send warning email set to 6.

If a project is less than 50 MB, the project is not considered dormant.

If a project is more than 50 MB and it is dormant for:

• More than 6 months: A deletion warning email is sent. This email includes the date at which the project will be scheduled for deletion.
• More than 12 months: The project is scheduled for deletion.

Example 2

If you use these settings:

• Delete dormant projects enabled.
• Delete dormant projects that exceed set to 0.
• Delete project after set to 12.
• Send warning email set to 11.

Because the size limit has been set to 0 MB, all projects in an instance are covered. If a project is dormant for:

• More than 11 months: A deletion warning email is sent. This email includes the date at which the project will be scheduled for deletion.
• More than 12 months: The project is scheduled for deletion.

If a project exists that has already been dormant for more than 12 months when you configure these settings:

• A deletion warning email is sent immediately. This email includes the date at which the project will be scheduled for deletion.
• The project is scheduled for deletion 1 month (12 months - 11 months) after the warning email has been sent.

Determine when a project was last active

You can view a project's activities and determine when the project was last active in the following ways:

• Go to the activity page for the project and view the date of the latest event.
• View the last_activity_at attribute for the project using the Projects API.
• List the visible events for the project using the Events API. View the created_at attribute of the latest event.