Feature Request: Custom HTTP Response Codes for Token Access Permissions in Self-Managed GitLab
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Problem to solve
Currently, when a token does not have the correct permissions to access a project, GitLab returns a "404 Not Found" response. This behavior is designed to avoid leaking information about project existence. However, this approach creates an issue for customers who rely on the "404 Not Found" response as an indication of a project being deleted. This situation makes it difficult to distinguish between cases where a project does not exist and cases where the token has insufficient permissions to access the project.
For example, a self-managed Ultimate customer running Omnibus on-prem has an image sweeper process that expects to see "404 Not Found" responses to determine if a project has been deleted. Since a 404 is returned both when a project is deleted and when a token lacks access, this process cannot differentiate between a legitimate deletion and an authorization issue. This ambiguity increases the risk of unintended image deletions and introduces potential security and operational complications.
Proposal
Introduce a configuration option in self-managed GitLab instances that allows administrators to choose custom HTTP response codes for permission-related errors. This option could be controlled by an "Error Visibility" flag or a similar setting that enables GitLab administrators to specify whether to return:
- 401 Unauthorized: For invalid credentials or bad tokens.
- 403 Forbidden: For valid credentials that lack sufficient permissions to access the resource.
- 404 Not Found: For cases where the requested project or resource does not exist.
This flexibility would allow administrators to choose more appropriate HTTP response codes for their use cases, without impacting GitLab's default behavior of returning "404 Not Found" on gitlab.com and other hosted instances where security and privacy concerns take priority. For additional customization, a flag could be introduced to control whether errors should be masked as 404 responses to prevent information disclosure.
Intended users
System Administrators: Who require more granular control over error handling in self-managed GitLab instances to support operational workflows, such as image sweeper processes.
DevOps Engineers: Who need to integrate GitLab’s HTTP response codes with automation tools that depend on accurate error codes for decision-making.
Security Teams: Who need clear, distinct response codes to diagnose and differentiate between access-related errors and resource availability issues without compromising security principles.