How to Build and Host Your Gatsby Site on Gitlab Pages
In this brief guide we will look at how you can build and host your Gatsby site for free on Gitlab Pages.
- Have a Gatsby project
- Have your Gatsby project on Gitlab
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
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:
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-ci.yml your Gatsby should be available automatically on Gitlab Pages on the url
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
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
When the steps above is done you should have your Gatsby site hosted at Gitlab, with HTTPS and with your custom domain.
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.