Note: If you’re unfamiliar with GitLab CI, I highly recommend you try it out on for free.

A few months ago, the disk space on my on-prem GitLab instance began to fill up. Fortunately for me, my monitoring reported the issue before it became a major problem. My first thought was, why is this happening? I knew that I had provisioned more than enough space and there should be no reason it was almost full.

After a brief investigation, I found that the build artifacts section of most of my repositories was 99% of the total repository size…some of them being over 40GB! That’s when I went down the rabbit hole of artifact expiration. In this post, we’ll focus on the solution to this problem as well as a stop-gap.


Set Default Artifact Expiration Policy (On-Prem Only)

The GitLab default policy for artifact expiration differs between and on-prem GitLab versions. Depending on your GitLab CI workloads, pipeline size, job runtimes, and disk size 😊, you’ll want to set the expiration time that works best for your environment. Always err on the side of larger for your default setting as you don’t want to negatively affect a job run because the artifact was deleted too soon.

GitLab Documentation on default artifact expiration.

SettingGitLab.comOn-Prem GitLab Versions
Artifacts expiry timekept forever30 days

Set Artifact Expiration in .gitlab-ci.yml

Starting with GitLab 8.9 artifact expiration within the .gitlab-ci.yml became possible. This becomes a necessity if you’re using as you’re unable to set the default artifact expiration policy. It also gives you finer control in on-prem GitLab instances as it allows you to delete an artifact prior to when the default expiration policy comes into effect.

GitLab Documentation on the artifacts:expire_in setting.


    expire_in: 1 week


Now that I’ve discussed proper handling of Job Artifacts, let’s move on to the stop-gap… It’s all fine and dandy to know about proper artifact expiration settings but what do I do with the artifacts that were created previously? GitLab provides two methods for deleting artifacts that have no expiration:

  • GitLab Web UI
  • GitLab REST API

Deleting artifacts via the Web UI is a non-starter IMO unless you want to delete only a few. That leaves the best option to be leveraging the REST API. In my searching, I came upon a very helpful GitLab forum post. This served as the base for the script I used to clean up my artifacts. I hope this serves you well.

Bash Script for removing GitLab Job Artifacts

Script Source Code

Prior to running the script, make sure you have curl and jq installed and you’ve updated the project_id, token, and server variables to match your environment.