Deploying a Gatsby site to Netlify using CircleCI

Gatsby is a static website and application generator that makes building powerful React-based frontend applications easy and effective. With over fifty thousand stars on GitHub (51.5k as at the time of this writing), Gatsby stands as one of the most widely used React frameworks. Gatsby is so popular that most hosting platforms offer custom support for the framework. Netlify is one of those platforms. While Netlify’s custom support for Gatsby provides smooth deployments, there is one major drawback. Netlify controls most of the deployment process, which means that your team cannot perform custom tasks like running automated tests.

In this tutorial, you will learn how to take over the deployment process by using CircleCI as your continuous deployment server. With the setup you will create using this tutorial, you will be able to perform any custom step required in your build process before eventually deploying to Netlify.

Prerequisites

To follow this tutorial, a few things are required:

1. Node.js installed on your system (version 12.13 or newer)
2. A Netlify account
3. A CircleCI account
4. A GitHub account

With all these installed and set up, you can begin the tutorial.

Creating a new Gatsby site

The first thing you need is a Gatsby site to be deployed to Netlify. Run the following command at whatever location you choose within your system:

npm init gatsby

This command invokes the Gatsby installer and opens an interactive CLI session where you are prompted to answer a couple of questions to have your project set up. Answer the questions according to the list below. Note that the bolded text is a text response or option selected for the question while italics text is an action to be performed.

• What would you like to call your site: Netlify Gatsby Site
• What would you like to name the folder where your site will be created: Press the Enter key to accept the default
• Will you be using a CMS: No (or I’ll add it later)
• Would you like to add a styling system: No (or I’ll add it later)
• Would you like to install additional features with other plugins: Select Add Markdown and MDX support, click Done, then press the Enter key
• Shall we do this: Press the Enter key to confirm the Yes option

Here is the CLI output for the project creation process:

What would you like to call your site?
✔ · Netlify Gatsby Site
What would you like to name the folder where your site will be created?
✔ 2021/ netlify-gatsby-site
✔ Will you be using a CMS?
· No (or I'll add it later)
✔ Would you like to install a styling system?
· No (or I'll add it later)
✔ Would you like to install additional features with other plugins?
· Add Markdown and MDX support


Thanks! Here's what we'll now do:

    🛠  Create a new Gatsby site in the folder netlify-gatsby-site
    🔌 Install gatsby-plugin-mdx
  
? Shall we do this? (Y/n) › Yes

After answering the questions, the project creation begins. By the end of the process, you will have a Gatsby project created in the netlify-gatsby-site folder. Use these commands to run the project:

cd netlify-gatsby-site
npm run develop

This boots up the Gatsby site at the local URL http://localhost:8000. Enter this address in your browser to go to the site.

Setting up the GitHub project

The next step is setting up your Gatsby project on GitHub. Once GitHub setup is complete, you can then set up the project on Netlify and CircleCI. Before pushing your project to GitHub, you need to install the Netlify CLI package as a development dependency in your Gatsby project. This is recommended for deployments in CI environments to avoid breaking changes. At the root of your Gatsby project run this command to install the dependency:

npm install --save-dev netlify-cli

You can now push your project to GitHub. Once your project is on GitHub, create a new branch. Give this branch any name you want; for the tutorial I will name it netlify-deploy-ignore.

You may be wondering why you need this branch. Netlify needs a project branch to automatically trigger an application’s deployment. When changes are pushed to this branch, Netlify will initiate the deployment process. You want to avoid a situation where both Netlify and your CircleCI pipeline are running two deployment processes in parallel. This new branch acts as a decoy for Netlify to monitor. Do not push changes to this branch. Its purpose is to “distract” the Netlify deployment process so that you can use CircleCI for deployment. You can make this a protected branch on GitHub so that no one on your team pushes to it by mistake.

Creating the Netlify application

To create a new Netlify application, go to your Netlify dashboard and click the New Site from Git button. Next, select GitHub as your provider and search for the project.

Select the project and go to the next step to select a branch for Netlify to deploy from. Select your decoy branch.

Next, click the Deploy site button so that Netlify performs the very first deployment of your site. Click the link, which should look like: sitename.netlify.app.

There are two configuration values you will need to get from your Netlify app and account to perform automated deployments in your CircleCI pipeline.

• The APP ID for the application you just created can be found in the Site Details section of your Netlify app.
• The Personal Access token allows access to your Netlify account from your deployment pipeline. Generate an access token at User Settings > Applications.

Save your access token in a secure place because Netlify will not allow you another view of this value after you create. You will only be able to change it.

Setting up the project on CircleCI

Time to set up your project on CircleCI. Add the .circleci folder to the root of your project. In it, add an empty config.yml file. You will be adding the configuration to this file in the next section. Push your changes to the GitHub project.

Next, go to the Add Projects page on the CircleCI dashboard to add the project.

Click Set Up Project. This will load a dialog where CircleCI automatically detects your configuration file.

Click Let’s Go to trigger your build pipeline for the first time. The build will fail because you have not added code to the configuration yet. You will perform this step later on.

Before you write the configuration you will need to add the Netlify APP ID and access token as environment variables on your CircleCI project.

Make sure your project is the currently selected project on the Pipelines page. Click the Project Settings button. On the settings page, select Environment Variables from the side menu. On this new page, click the Add Environment Variable button and enter this information:

• NETLIFY_SITE_ID is the APP ID from your Netlify application.
• NETLIFY_ACCESS_TOKEN is your Netlify personal access token.

Writing the deployment configuration

The last step in the process is to write the deployment configuration. Open the config.yml file and add this configuration:

version: 2.1
jobs:
  build:
    working_directory: ~/repo
    docker:
      - image: cimg/node:12.16
    steps:
      - checkout
      - run:
          name: Update NPM
          command: "sudo npm install -g npm"
      - restore_cache:
          key: dependency-cache-{{ checksum "package-lock.json" }}
      - run:
          name: Install Dependencies
          command: npm install
      - save_cache:
          key: dependency-cache-{{ checksum "package-lock.json" }}
          paths:
            - ./node_modules
      - run:
          name: Gatsby Build
          command: GATSBY_CPU_COUNT=2 npm run build
      - save_cache:
          key: gatsby-public-cache-{{ .Branch }}
          paths:
            - ./public
      - run:
          name: Deploy to Netlify
          command: ./node_modules/.bin/netlify deploy --site $NETLIFY_SITE_ID --auth $NETLIFY_ACCESS_TOKEN --prod --dir=public
workflows:
  version: 2
  build-deploy:
    jobs:
      - build:
          filters:
            branches:
              only:
                - main

In this configuration, the project is checked out of the repository and the project dependencies are installed and cached. After caching the dependencies, the Gatsby build command npm run build runs to create a production build of the application in the public directory at the root of the project. This folder is then cached.

Finally, the Netlify CLI deploys the site using the $NETLIFY_SITE_ID and $NETLIFY_ACCESS_TOKEN variables. The workflow configuration then ensures that only the main branch triggers a deployment to Netlify.

Before you push this configuration for CircleCI to deploy the site, go to the src/pages folder of your project and change the Gatsby message in the index.js file from you just made a Gatsby site to you just deployed a Gatsby site with CircleCI. This new message will show that there has been a change in the deployed application.

Commit all your changes and push to GitHub.

This will automatically trigger the deployment pipeline and a successful build.

Click the build to review the deployment details.

With this successful build, visit your website again to verify the changes you deployed. It should display the new message.

Awesome!

To confirm that Netlify is not running a parallel deployment, check your Netlify deployment logs. There is only one deployment in the Production deploys, the first one that was triggered by the branch netlify-deploy-ignore. The rest don’t show a branch because they were triggered by the CircleCI pipeline.

Conclusion

There you have it, custom deployment of a Gatsby site to Netlify using CircleCI. This setup gives your team more control over Gatsby deployments to Netlify and provides the flexibility you need to run more custom steps in the process.

If you prefer Heroku to Netlify as your hosting platform, we also have a tutorial for using CircleCI pipelines for custom deployment to Heroku.

Happy coding!

---

Fikayo Adepoju is a LinkedIn Learning (Lynda.com) Author, Full-stack developer, technical writer, and tech content creator proficient in Web and Mobile technologies and DevOps with over 10 years experience developing scalable distributed applications. With over 40 articles written for CircleCI, Twilio, Auth0, and The New Stack blogs, and also on his personal Medium page, he loves to share his knowledge to as many developers as would benefit from it. You can also check out his video courses on Udemy.

Read more posts by Fikayo Adepoju