Deploy a static website to Netlify using GitLab's CI/CD pipeline

Table of contents
  1. 🔗Goal
  2. 🔗Install netlify-cli
  3. 🔗Preparing Netlify for CI/CD
    1. 🔗Link your repo to a new Netlify project
    2. 🔗Generate a personal access token
    3. 🔗Setup Netlify's config file
  4. 🔗Preparing for GitLab CI/CD
  5. 🔗Modifying the CI/CD pipeline
  6. 🔗Push and check
  7. 🔗Bonus and reference


Instead of using Gitlab pages, using Netlify has a web hoster have the following advantages:

  • automatic Let's encrypt certificate + auto-renewing
  • managed DNS zone at the same place

But still using the Gitlab CI/CD over a fully manager Netlify pipeline have the following advantages:

  • advanced CI/CD for more complex deployment workflow

🔗Install netlify-cli

Install netlify-cli globally with npm i netlify-cli -g.
You can check it is properly installed with netlify -v.

🔗Preparing Netlify for CI/CD

In your git repository, run netlify init --manual and follow teh wizard steps.

The site ID will be saved locally in .netlify/state.json.

🔗Generate a personal access token

If this is the first time you're doing this:

Login to Netlify, then go to User Settings > Applications ( and create a new access token.

Save it, once the page is exited you won't be able to get it again.

If you lose it, you’ll need to generate a new one.

🔗Setup Netlify's config file

You won't need netlify.toml because we will use only .gitlab-ci.yml.

🔗Preparing for GitLab CI/CD

Assuming you already have a proper .gitlab-ci.yml file for you project; you then have to setup environment variables in Gitlab.

In your Gitlab project go to Settings > CI/CD and expand the Variables section.


You should have something like this:

Note: it is recommended to add .netlify/state.json in its .gitignore to avoid pushing it in the git repository.

🔗Modifying the CI/CD pipeline

Example of project .gitlab-ci.yml where I use Netlify:

I won't explain how to build a proper Gitlab CI/CD configuration file because there are already many resources for that.

I'll rather explain what you need to add:

  1. Either in before_script: or in a stage script: add npm install netlify-cli -g
  2. In pages: (stage: deploy) add to your script: this step netlify deploy --site $NETLIFY_SITE_ID --auth $NETLIFY_AUTH_TOKEN --prod --dir public/ where --dir value is the directory to deploy.

🔗Push and check

Finally use git to add and push the modifications we did earlier.

To check all went done, go your Gitlab project, navigate to CI/CD > Pipelines and view jobs and stages details.

🔗Bonus and reference

My reference is Deploying a Vue.js app to Netlify using GitLab’s CI/CD pipeline by Lawrence Braun, you can also check adding a staging preview section from this article.