Project Deletion
Deleting a project is more than deleting a record from Console. A project can own source repositories and container images in GitLab, channels in Mattermost, and deployments in Kubernetes. Console coordinates cleanup across those systems before removing its own record of the project.
How deletion works
After a Platform Admin or Organization Admin confirms the deletion, Console processes the actions in this order:
- Delete the project's GitLab resources.
- Delete the project's Mattermost channels.
- Delete the project's deployments.
- Delete the project's records from the Console database.
Console only interacts with the features enabled for the installation. If an integration is disabled or the project has no resources for it, Console skips that part of the workflow.
What each stage removes
GitLab projects and container images
For each GitLab repository associated with the project, Console:
- Finds its container registry repositories.
- Deletes every container image tag in those repositories.
- Deletes the GitLab repository.
Console removes the tags before deleting each repository because GitLab can reject repository deletion while registry tags remain. After deleting the repositories, Console deletes the GitLab subgroup associated with the project.
Mattermost channels
Console sends a delete request for each Mattermost channel associated with the project. By default, Mattermost treats this request as an archive: the channel is hidden and made read-only, but its content remains on the Mattermost server and an authorized administrator can restore it.
Permanently deleting a channel requires the request to include permanent=true and the Mattermost server setting ServiceSettings.EnableAPIChannelDeletion to be enabled. Console does not currently request permanent deletion. For more information, see Delete a channel in the Mattermost API documentation.
Console does not delete the organization's Mattermost team or any channels that are not recorded as project resources.
Deployments
Console finds deployment resources labeled with the project's ID and deletes each one. For every deployment, it also attempts to remove the associated image and chart secrets.
Console records
Console removes its local records only after cleanup in the enabled external services succeeds. This includes:
- The project record
- Project-entity records that connect the project to tools
- User records of recently used project tools
- Tool ID mappings that connect the project to external systems
Deleting these records does not delete the organization, its members, or organization-level tool configuration.
What happens if cleanup fails
Project deletion is not a single transaction shared by Console, GitLab, Mattermost, and Kubernetes. Console can roll back its own database changes, but it cannot restore a remote resource after another service has deleted it.
If an enabled service reports an error, Console:
- Stops the workflow and returns a service error.
- Keeps the project and its related records in the Console database.
- Reports whether the failure came from GitLab, Mattermost, or deployment cleanup.
Because services are processed in sequence, an earlier service might already have removed resources before a later service fails. For example, GitLab repositories might be gone even though a deployment error leaves the project visible in Console. Resolve the reported service error before trying the deletion again.
Recovery and retention
Treat project deletion as permanent. Console does not provide an undo action for project deletion. Move or copy any images you need to keep before deleting the project.
If project deletion is disabled for the installation, Console hides the action and the backend rejects project deletion requests without removing anything.