GitLab Runner Garbage Collection

To free up unused Docker containers, networks, and images, you can completely remove them with a simple command. Removing these unused resources frees up disk space.

Prerequisites

GitLab Runner
SSH access

Check Disk Usage

sudo /usr/share/gitlab-runner/clear-docker-cache space

Run System Prune

To run a Docker System Prune on the GitLab Runner, establish an SSH connection using your privileged SSH user. You can then run the Docker System Prune with the following command:

Delete unused containers and images

sudo /usr/share/gitlab-runner/clear-docker-cache prune

Delete unused containers, images, and volumes

sudo /usr/share/gitlab-runner/clear-docker-cache prune-volumes

Available Options

Option	Description
`help`	Display help for the command
`space`	Display disk usage
`prune`	Delete unused containers and images
`prune-volumes`	Delete unused containers, images, and volumes

If your SSH user cannot execute this SSH command, please contact our support team so that your user can be granted the necessary permissions. (Managed)

Clear the Docker Build Cache

Each build of a Docker image consists of several steps (layers)—such as installing dependencies, copying files, or configuration. Docker stores these layers in a cache so that, for future builds, only the changed steps need to be re-executed. You can clear this cache with the following command:

sudo docker buildx prune -a -f

Available Options

Option	Description
`-a`, `—all`	Removes the entire unused Docker build cache
`-f`, `--force`	No re-confirmation required

Setting Up a Cron Job

If you want to set up the Docker System Prune as a cron job that runs automatically at the desired time, you can configure the cron job in our Customer Center. For instructions, see our Help Center article on Cron Jobs.

Alternatively, you can create a cron job directly on the GitLab Runner itself using crontab -e. You can use our default configuration or edit it to suit your needs.

Unused Containers and Images

  0 0 * * * sudo /usr/share/gitlab-runner/clear-docker-cache prune
# ┬ ┬ ┬ ┬ ┬
# │ │ │ │ │
# │ │ │ │ └──── Day of the week (0–7; Sunday is 0 or 7)
# │ │ │ └────── Month (1–12)
# │ │ └──────── Day (1-31)
# │ └────────── Hour (0-23)
# └──────────── Minute (0-59)

You can then save the file, and the cron job will run every night at 00:00 (UTC).

Docker Build Cache

  0 0 * * * sudo docker buildx prune -a -f 
# ┬ ┬ ┬ ┬ ┬
# │ │ │ │ │
# │ │ │ │ └──── Day of the week (0–7; Sunday is 0 or 7)
# │ │ │ └────── Month (1–12)
# │ │ └──────── Day (1-31)
# │ └────────── Hour (0-23)
# └──────────── Minute (0–59)

Checking Hard Drive Space

If the Prune system does not free up enough space, this indicates that the data and files in question are in use and necessary for the Runner’s operation. If this occurs, we recommend increasing the hard drive capacity. See also: Increase Hard Drive Capacity