Clean Up Your Workspace: Archiving GitLab Projects

by Devop · Published 11/08/2024 · Updated 14/11/2024

Keeping your GitLab workspace organized is key to working efficiently. One way to do this is by archiving projects that are no longer active. Archiving helps you manage resources better and keeps your workspace clutter-free. This guide will walk you through the importance of archiving, the steps to do it, and how to manage archived projects.

Table of Contents

Key Takeaways

Archiving GitLab projects helps keep your workspace organized and efficient.
You need specific permissions and should ensure data backup before archiving a project.
Archiving makes the project read-only but retains access to important data.
You can view, restore, or delete archived projects as needed.
Regularly cleaning up your workspace improves performance and saves storage space.

Understanding the Importance of Archiving GitLab Projects

Archiving GitLab projects is a crucial practice for maintaining an organized and efficient workspace. It helps in managing resources, improving performance, and ensuring that your team can focus on active projects without distractions. Let’s dive into why archiving matters, the benefits it brings, and when you should consider archiving a project.

Why Archiving Matters

Archiving projects in GitLab is essential for several reasons. First, it helps in decluttering your workspace by moving inactive projects out of sight. This makes it easier to find and focus on active projects. Second, it ensures that important data is preserved without being actively used, which can be crucial for compliance and historical reference. Lastly, archiving can improve the overall performance of your GitLab instance by reducing the load on the system.

Benefits of Archiving

Archiving offers numerous benefits, including:

Resource Management: By archiving inactive projects, you free up resources that can be better utilized for active projects.
Improved Performance: With fewer active projects, your GitLab instance can run more efficiently.
Enhanced Focus: Team members can concentrate on current tasks without being distracted by outdated projects.
Compliance and Record-Keeping: Archived projects serve as a historical record, which can be important for audits and compliance.

When to Archive a Project

Knowing when to archive a project is just as important as knowing how to do it. Here are some scenarios where archiving might be the best option:

The project is no longer actively maintained or developed.
The project has been completed, and all tasks are finished.
The project is being replaced by a new initiative or repository.
The project is needed for historical reference but not for active use.

By understanding the importance of archiving GitLab projects, you can keep your workspace clean and efficient, ensuring that your team can work more effectively. Whether you’re using GitLab Ultimate or GitLab Premium, archiving is a feature that can significantly enhance your project management strategy.

Prerequisites for Archiving a GitLab Project

Before you archive a GitLab project, there are a few important steps to follow. These steps ensure that the process goes smoothly and that no critical data is lost. Let’s dive into the prerequisites for archiving a GitLab project.

Required Permissions

To archive a project, you must have at least the Maintainer role. Without the right permissions, you won’t be able to access the archive option. Make sure you check your role before proceeding.

Deactivating Pipeline Schedules

Active pipeline schedules can interfere with the archiving process. Deactivate or delete any active pipeline schedules for the project. This step is crucial to avoid any disruptions.

Ensuring Data Backup

Before archiving, it’s essential to back up your data. This includes all repositories, issues, and merge requests. Having a backup ensures that you can restore your project if needed.

Archiving a project makes it read-only, so make sure everything is in order before you proceed.

By following these prerequisites, you’ll be well-prepared to archive your GitLab project without any issues.

Step-by-Step Guide on How to Archive a GitLab Project

Archiving a GitLab project is a straightforward process that helps keep your workspace organized. Follow these steps to ensure a smooth archiving experience.

Navigating to Project Settings

First, log in to your GitLab account and go to the project you want to archive. On the left sidebar, click on Settings. This will open a menu where you can manage various aspects of your project.

Accessing the Archive Option

In the Settings menu, scroll down to find the General section. Here, you’ll see an option labeled Advanced. Click on it to expand more settings. Look for the Archive project button and click on it.

Confirming the Archive Action

A confirmation dialog will appear, asking if you’re sure you want to archive the project. Confirm your action by clicking on the Archive button. Your project will now be archived and moved out of your active projects list.

Archiving a project doesn’t delete it; you can always restore it later if needed.

Managing Archived Projects

Viewing Archived Projects

To view your archived projects, navigate to the Inactive tab on the group page, Your work page, or Explore page. Archived projects are labeled with an archived badge, making them easy to identify. This feature helps you keep track of projects that are no longer active but still hold valuable information.

Restoring Archived Projects

If you need to bring an archived project back to life, you can easily restore it. Follow these steps:

On the left sidebar, select Search or go to and find your project.
Select Settings > General.
Expand Advanced.
In the Unarchive project section, select Unarchive project.
Confirm the action by selecting OK.

Restoring a project removes the read-only restriction, making it fully accessible again.

Deleting Archived Projects

When it’s time to permanently remove an archived project, follow these steps:

On the left sidebar, select Search or go to and find your project.
Select Settings > General.
Expand Advanced.
In the Delete this project section, select Delete project.
Enter the project name in the confirmation dialog and select Yes, delete project.

Note: Deleting a project is irreversible, so make sure you have backed up any important data before proceeding.

Cleaning Up Your GitLab Workspace

Keeping your GitLab workspace tidy is essential for smooth operations and efficient project management. Here’s how you can clean up your workspace effectively.

Removing Unreferenced LFS Files

Unreferenced LFS files can take up valuable space in your repository. To remove these files, use the Rake task provided by GitLab. Make sure not to run this task within 12 hours of a GitLab upgrade to avoid data loss. This task will help you clear out invalid references, allowing garbage collection to free up space.

Cleaning Up Project Upload Files

Project upload files can accumulate over time, leading to unnecessary clutter. GitLab offers tools to clean up these files from both the file system and object storage. Regularly cleaning these files ensures your workspace remains organized and efficient.

Removing Orphan Artifact Files

Orphan artifact files are those that no longer have a record in the database but still occupy disk space. Use the gitlab-rake command to scan and delete these files. You can run this command in a dry run mode to see what will be deleted before actually removing the files. This step is crucial for maintaining a clean and efficient workspace.

Regular maintenance tasks like these are vital for keeping your GitLab workspace in top shape. They help you avoid unnecessary storage costs and ensure that your projects run smoothly.

Handling Projects Pending Deletion

Managing projects pending deletion in GitLab is crucial for maintaining a clean and organized workspace. Here’s how you can handle these projects effectively.

Viewing Projects Pending Deletion

To view a list of all projects that are pending deletion:

On the left sidebar, select Search or go to and find your project.
Select View all my projects.
Select the Pending deletion tab.

Each project in the list shows:

The time the project was marked for deletion.
The time the project is scheduled for final deletion.
A Restore link to stop the project from being eventually deleted.

Restoring a Project Marked for Deletion

If you need to restore a project that is marked for deletion, follow these steps:

On the left sidebar, select Search or go to and find your project.
Select Settings > General.
Expand Advanced.
In the Restore project section, select Restore project.

Note: You must have the Owner role for the project to restore it.

Permanently Deleting a Project

To immediately delete a project marked for deletion:

On the left sidebar, select Search or go to and find your project.
Select Settings > General.
Expand Advanced.
In the Delete this project section, select Delete project.
On the confirmation dialog, enter the project name and select Yes, delete project.

Remember, this action deletes the project and all associated resources, such as issues and merge requests. If you don’t want to wait for delayed deletion, you can delete a project immediately by performing the steps for deleting a project again. In the first cycle of deleting a project, the project is moved to the delayed deletion queue and automatically deleted after the retention period has passed. If during this delayed deletion time you run a second deletion cycle, the project is deleted immediately.

Reducing Repository Size

Managing the size of your GitLab repository is crucial for maintaining performance and avoiding storage limits. Here’s a step-by-step guide to help you reduce your repository size effectively.

Calculating Repository Size

First, you need to determine the current size of your repository. This can be done by computing the accumulated size of all files. It’s similar to running du --summarize --bytes on your repository’s hashed storage path. Knowing the size helps you understand how much space you need to free up.

Purging Files from Repository History

To reduce the disk size of your repository, you must remove references to large files from branches, tags, and other internal references created by GitLab. These include:

refs/merge-requests/*
refs/pipelines/*
refs/environments/*
refs/keep-around/*

Removing these references can significantly reduce your repository size. However, be cautious as this process is not suitable for removing sensitive data like passwords or keys.

Repository Cleanup Steps

Navigate to your project: On the left sidebar, select Search or go to and find your project.
Go to Settings: Navigate to Settings > Repository.
Expand Repository Maintenance: Here, you can upload a list of objects to be removed.
Upload the commit-map file: This file, created by [git filter-repo](https://www.geeksforgeeks.org/git-shallow-clone-optimizing-repository-size/), lists the objects to be removed. If the file is too large, split it and upload in parts.
Start Cleanup: Select Start cleanup to begin the process. This will remove internal Git references to old commits, run git gc --prune=30.minutes.ago, and unlink any unused LFS objects.

Important: GitLab sends an email notification with the recalculated repository size after the cleanup is completed. If the size does not decrease, it may be due to loose objects being kept around from recent Git operations. Try re-running the steps after the repository has been dormant for at least 30 minutes.

By following these steps, you can ensure your repository remains within size limits and operates efficiently.

Automating Inactive Project Deletion

Configuring Inactive Project Deletion

To set up the deletion of inactive projects, follow these steps:

On the left sidebar, at the bottom, select Admin.
Go to Settings > Repository.
Expand Repository maintenance.
In the Inactive project deletion section, select Delete inactive projects.
Configure the settings:
- A warning email is sent to users with the Owner and Maintainer roles.
- The email duration must be less than the Delete project after duration.
Select Save changes.

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

Determining Project Activity

To determine when a project was last active, you can view the project’s activities. This helps in identifying which projects are truly inactive and need to be deleted.

Setting Up Automated Deletion

Automating the deletion process ensures that your GitLab workspace remains clean and efficient. By setting up automated deletion, you can focus on active projects without worrying about clutter from inactive ones.

Tip: Regularly review your project activity to ensure that only truly inactive projects are deleted.

Best Practices for Maintaining a Clean GitLab Environment

Keeping your GitLab environment clean and organized is crucial for smooth operations and efficient project management. Here are some best practices to help you maintain a tidy workspace.

Regular Audits

Conducting regular audits of your GitLab projects ensures that everything is up-to-date and relevant. Regular audits help identify outdated or inactive projects that can be archived or deleted. This practice not only frees up space but also makes it easier to find active projects.

Using Rake Tasks for Cleanup

GitLab provides Rake tasks for various cleanup activities. These tasks can help you remove unreferenced LFS files, clean up project upload files, and remove orphan artifact files. Utilizing these tasks can significantly reduce the clutter in your GitLab environment.

Monitoring Storage Utilization

Keeping an eye on your storage utilization is essential. GitLab offers tools to monitor how much space your projects are consuming. By regularly checking storage usage, you can take proactive steps to manage and optimize your storage, ensuring that you don’t run into space issues.

A clean GitLab environment not only improves performance but also enhances team productivity by making it easier to find and manage projects.

Troubleshooting Common Issues

Incorrect Repository Statistics

Sometimes, the repository statistics might not show the correct data. This can be due to various reasons, such as background jobs not running properly. To fix this, you can manually trigger a repository statistics refresh from the admin area.

Space Not Being Freed

If you notice that space is not being freed up after deleting files or projects, it could be because the garbage collection hasn’t run yet. You can manually run the garbage collection to free up space immediately.

Failed Project Exports

Exporting a project can sometimes fail, especially if the project is large. If you’re attempting to import a large project into a development environment, you might encounter errors. Ensure that all necessary services are running and try the export again.

Troubleshooting these common issues can save you a lot of time and keep your GitLab environment running smoothly.

Leveraging GitLab Features for Efficient Project Management

Using Feature Flags

Feature flags in GitLab allow you to toggle features on and off without deploying new code. This is especially useful for testing new features in a controlled environment. By using feature flags, you can gradually roll out changes and minimize risk.

Experimenting with Beta Features

GitLab often releases beta features that you can try out before they become generally available. These features can provide early access to new tools and functionalities, helping you stay ahead of the curve. Experimenting with beta features allows you to give feedback and influence the final product.

Utilizing GitLab’s REST API

The GitLab REST API is a powerful tool for automating tasks and integrating GitLab with other systems. You can use the API to manage projects, users, and even CI/CD pipelines. This level of automation can significantly improve your team’s efficiency.

Leveraging GitLab’s features can transform how you manage projects, making your workflow more agile and efficient.

GitLab offers a range of features that can make managing your projects easier and more efficient. From tracking issues to continuous integration, GitLab has tools that can help you stay on top of your work. Want to learn more about how GitLab can benefit your team? Visit our website for more information and resources.

Conclusion

Tidying up your GitLab workspace by archiving projects is a smart move. It helps keep things organized and makes sure your active projects run smoothly. By following the steps to archive, delete, or restore projects, you can manage your resources better and avoid clutter. Remember, a clean workspace isn’t just about looks—it’s about efficiency and productivity. So, take the time to archive those old projects and enjoy a more streamlined workflow.