In this brief guide we will look at how you can build and host your Gatsby site for free on Gitlab Pages.

Prerequisites

• Have a Gatsby project
• Have your Gatsby project on Gitlab

Build Configuration

Once you have created a Gatsby project on Gitlab you need to create a file called .gitlab-ci.yml and place it in the root folder of your project.

At the top of the file we use the latest node image, and a the time of writing that is 14.3.0

image: node:14.3.0

Next we define the build stage itself. In the script section we have to commands: npm install and npm run build. First we install all the npm dependencies and then we build the Gatsby site. In the package.json file you need to define the script command build with the following: gatsby build.

pages:
  script:
  - npm install
  - npm run build

To make sure Gitlab registers your files you have to put the files in a folder called public. By default the gatsby build command places your build files in a folder called public. To make sure the folder is moved to Gitlab Pages we need to add the folder to artifacts with in the build file:

artifacts:
    paths:
    - public

By defining a cache section in the build configuration we can also speed up the build process. There is no need to install all the npm dependencies on each run. To save a cache of the node_modules we add the following section:

cache:
    paths:
      - node_modules  

Optional: If you only want to build and deploy your Gatsby site when code is commited to your master branch you need to add the following:

only:
  - master 

Complete Build File

image: node:14.3.0

pages:
  script:
  - npm install
  - npm run build -- --prefix-paths
  artifacts:
    paths:
    - public
  cache:
    paths:
      - node_modules  
  only:
  - master

Gitlab Setup

After adding .gitlab-ci.yml your Gatsby should be available automatically on Gitlab Pages on the url https://GITLAB_USERNAME.gitlab.io/REPOSITORY_URL.

Custom Domain

If you want to add your own domain you have to go to Gitlab Pages settings for your project which can be found at Settings -> Pages -> New Domain. Fill out your domain and click Create New Domain.

After adding the domain you have to add a CNAME entry to your domain. E.g if your custom domain is example.com and your Gitlab username is user , you have to create a CNAME entry from example.com to user.gitlab.io. (notice the dot at the end after io). Gitlab also need to verify that you own the domain. The verification is done by adding a TXT entry to your domain. The verification should be of the format: _gitlab-pages-verification-code.example.com and with a value gitlab-pages-verification-code=VERIFICATION_VALUE .

When the steps above is done you should have your Gatsby site hosted at Gitlab, with HTTPS and with your custom domain.

Example

If you want to check out an example you can look this Gatsby portfolio site.

If you want to support this blog you can do so by signing up to DigitalOcean using this referral link.