Manage GitLab project housekeeping from the default branch. The component cleans up obsolete terminal pipelines, applies a default container registry cleanup policy, stops stale environments, and schedules deletion for old stopped review app environments.

The token in GITLAB_TOKEN requires project Owner access to update pipeline-retention settings and delete pipelines. By default, old pipelines are eligible for deletion after 7 days, the container registry cleanup policy is enabled with (?:[0-9]+\.[0-9]+\.[0-9]+|main|latest) kept, and stopped review app environments older than 30 days are scheduled for deletion.

Configure GITLAB_TOKEN with a group service account and grant it Owner access to the managed project.

Usage

include:
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/common@stable
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/housekeeping@stable

The job only runs on the default branch unless you override rules.

Guarded pipeline cleanup

pipeline-retention-seconds is the minimum age for cleanup (default: seven days, or 604800 seconds). The job processes all eligible pipelines without a per-run deletion limit. Both creation and last-update timestamps must be older than the cutoff, so a recently retried old pipeline is retained.

The job retains all active/manual/unknown-status pipelines, its own pipeline, the latest pipeline and latest successful pipeline for every ref, and pipelines for the latest ref SHA. Tag and child pipelines are retained. Candidates are inventoried with pagination before deletion, then their state and latest ref are rechecked. API errors, incomplete age/SHA data, or a latest-pipeline response for a different ref fail the job before that candidate is deleted.

The component disables GitLab's age-only background cleanup before guarded cleanup. GitLab documents that the background policy can delete pipelines regardless of status, including the latest pipeline for a branch or tag. The job verifies that it is disabled; an insufficient token or unsupported response fails before pipeline deletion.

Only terminal success, failed, canceled, and skipped pipelines can be deleted. Pipeline deletion permanently removes associated logs and artifacts. Do not run concurrent manual retries or independent deletion jobs during cleanup: GitLab has no atomic compare-and-delete API, so state rechecks cannot lock a pipeline against an external change between the final read and delete.

Inputs

Name	Description	Default	Type
---	---	---	---
name	The name of the housekeeping job.	project	string
needs	The jobs that this job depends on.	[]	array
pipeline-retention-seconds	Minimum age for guarded pipeline cleanup. Active and current pipelines are retained.	604800	number
registry-cleanup-cadence	Cadence for the GitLab container registry cleanup policy.	7d	string
registry-cleanup-keep-n	Minimum number of container tags to keep.	100	number
registry-cleanup-name-regex	Container tag regex selected by the cleanup policy.	.*	string
registry-cleanup-name-regex-keep	Container tag regex always kept by the cleanup policy.	(?:[0-9]+\.[0-9]+\.[0-9]+|main|latest)	string
registry-cleanup-older-than	Delete container tags older than this value.	14d	string
rules	Rules controlling when the housekeeping job runs.	[{"if":"$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH","when":"on_success"},{"when":"never"}]	array
stage	The stage where the housekeeping job runs.	.post	string
stale-environment-days	Stop environments last modified before this many days. GitLab requires at least 7 days.	30	number
stopped-review-app-days	Schedule deletion for stopped review app environments older than this many days.	30	number
stopped-review-app-limit	Maximum number of stopped review app environments to schedule for deletion in one run.	100	number
tags	The runners that this job depends on.	[]	array
token-variable	Name of the CI/CD variable containing a GitLab token allowed to manage project settings and environments.	GITLAB_TOKEN	string