Skip to main content
In this guide, you’ll learn how to force cache invalidation in GitLab CI/CD whenever your project dependencies change. We’ll cover:
  1. Restoring an existing cache
  2. Updating dependencies locally
  3. Detecting a cache miss in the pipeline
  4. Rebuilding and saving a new cache
  5. Manually clearing the cache via the GitLab UI
This ensures your runners always use up-to-date artifacts, improving build reliability and performance.

​
1. Restoring the Existing Cache

When you run your pipeline without modifying dependencies, GitLab CI restores the cache using a key derived from the SHA of package-lock.json.
This confirms that the existing cache was restored and used for the npm install step.
GitLab CI uses the contents of package-lock.json to generate a unique cache key. Any modification to this file produces a new key.

​
2. Updating Dependencies Locally

To demonstrate cache invalidation, we’ll add nodemon as a dev dependency. Nodemon automatically restarts your Node.js server on file changes.
  1. Switch to your feature branch
  2. Install nodemon and update lockfiles
  3. Verify changes in package.json
  4. Commit and push

​
3. Observing Cache Invalidation in the Pipeline

After pushing, the pipeline’s unit testing job will attempt to restore the cache with a newly generated key. Because package-lock.json changed, GitLab cannot find the old cache.
The image shows a GitLab CI/CD pipeline job interface, indicating a successful unit testing job with logs detailing each step of the process.
Because the key changed, GitLab reports a cache miss and proceeds to install dependencies from scratch.

​
4. Rebuilding and Saving the New Cache

On cache miss, the job runs npm install again:
After tests pass, GitLab saves a new cache under the updated key:
Notice the increase in cached files (from ~5700 to ~6040) after adding nodemon.

​
5. Manually Clearing the Cache

You can also clear all runner caches for your project via the GitLab UI:
  1. Go to CI/CD > Pipelines
  2. Click Clear runner caches
  3. Confirm the action
The image shows a GitLab CI/CD pipeline interface with a list of pipeline statuses, including warnings, skipped, and canceled states. The sidebar displays project navigation options like issues, merge requests, and pipelines.
Clearing caches will remove all stored artifacts, potentially increasing build times until caches are rebuilt.
By following this approach, you ensure GitLab CI invalidates and regenerates caches whenever your dependency lockfiles change, keeping your pipelines fast and reliable.

Watch Video