GitLab Pipeline Configuration Hierarchy

WHY IT EXISTS: CI/CD pipelines handle sensitive artifacts, logs, and deployment capabilities. A one-size-fits-all permission model would either overexpose internal data or block legitimate collaboration. GitLab created a layered configuration system so project visibility, pipeline-specific toggles, and role-based restrictions can be composed independently.

THE MENTAL MODEL: Think of it as a set of nested gates. The outermost gate is project visibility: Public, Internal, or Private. Inside that sits a pipeline visibility toggle that either aligns pipeline access with the project level or restricts it further. Finally, role-based rules act as turnstiles for specific actions like canceling jobs or viewing security dashboards. Each layer can narrow access, but never widen it beyond the layer above.

HOW IT WORKS: Project visibility determines who can reach the project at all. When project-based pipeline visibility is selected, pipelines inherit that visibility: Public projects show pipelines to everyone, Internal to authenticated users, Private to project members. When cleared, Public projects still show pipeline status on merge requests and commits to non-members, but logs, artifacts, and security dashboards require Reporter role or higher. A separate non-project member setting for Public projects adds another split: you can let everyone see pipelines or restrict them to members only, but this only matters when project visibility is Public and the project-based toggle is enabled. For destructive actions, the minimum role to cancel pipelines defaults to Developer, but can be raised to Maintainer or revoked entirely. You can also relocate the CI/CD configuration file from the root directory to an alternate path, including outside the project.

WHEN TO USE IT: Use these layers when you need to share pipeline status with external contributors without handing them build artifacts, when compliance requires limiting who can abort deployments, or when you want to centralize CI/CD configuration in a separate repository while applying it to multiple projects.

WHEN NOT TO USE IT: Do not rely on the non-project member pipeline setting for Internal or Private projects; the source explicitly states it has no effect there because non-members cannot access those projects in the first place. Also avoid toggling the project-based pipeline visibility checkbox in isolation without auditing the downstream permission table, since the interaction between the checkbox and role requirements changes dramatically when it is cleared.

ONE CANONICAL EXAMPLE: A Public open-source project wants to let anyone verify that tests pass on merge requests, but keep container images and security scan logs internal. The team enables project-based pipeline visibility, then sets non-project member access to Only project members, or alternatively clears project-based visibility so non-members see only commit status while Reporters and above see artifacts. They also restrict pipeline cancellation to Maintainers to prevent accidental deployment interruptions by external contributors.