The Shifter team would like to share with you a guide for how to create Gatsby sites using WordPress while running your builds with GitHub Actions and ultimately deploy them to Netlify. This demo uses a custom GitHub Action for Shifter and Netlify, and content from WordPress is sourced using WPGraphQL.
Before we get started, let’s answer a few common questions and offer some background.
Why Gatsby and Shifter?
Gatsby sites that source data from WordPress still need a place to host those WordPress sites. That’s where Shifter comes in. Gatsby isn’t a CMS like WordPress and it’s not trying to be a one either. Yes, you can source content from local files written in Markdown, JSON, and more, but it’s still not a content management system. Shifter offers a hosting solution for WordPress that runs as needed. When you edit content, create posts, or run your Gatsby build, the WordPress environment spins up giving your Gatsby site access to the data it needs.
There are a lot of reasons why WordPress is a great option for sourcing Gatsby data. A few of the most notable reasons are that it’s open-source like Gatsby, there’s a lot of knowledge and extensions available, and it’s popular with a vibrant community just like Gatsby.
Isn’t Shifter a static site generator for WordPress?
Yep! Shifter is a static site generator for WordPress but it’s more than that. Using Shifter, you can host your WordPress site and generate a static version from that existing WordPress theme with no-coding, framework, or rebuilding required. You can get the benefits of static with the same WordPress dashboard and admin experience.
The primary way Gatsby and Shifter can work together is to provide a place to host WordPress. The static site generator feature that Shifter offers could be an added bonus if your Gatsby site gets static assets directly from WordPress. Static assets such as images can be links from the static site Shifter creates.
You mentioned Netlify, why’s that in the mix?
We’ve documented some of the benefits and method for deploying to Netlify in the past. There’s a few options already such as our shifter-netlify-build script for deploying static WordPress sites to Netlify if you want to use more of the features they offer like Netlify Forms.
In this case, Netlify offers us a place to deploy our Gatsby site after the build happens using GitHub Actions. This final step in our workflow is just one option but any service that supports similar features can also be used.
What are GitHub Actions?
GitHub Actions are a suite of workflow and automation tools that GitHub offers. There’s a marketplace offering paid actions or open-source ones like that one we created for Shifter. The actions we created are designed to start and stop WordPress. Since WordPress sites on Shifter only run as they are needed for access to the backend of WordPress this action starts the site so Gatsby Build can query all the data it needs.
We are also using a GitHub action created by Netlify which uses their CLI. After Gatsby build happens is the Netlify CLI pushes a manual deploy.
Deploying to Gatsby Cloud?
With the launch of Gatsby dot com, deploying to Gatsby Cloud is something that could be added to this workflow example in the near future. That would replace deploying to Netlify and running your builds using GitHub actions.
There are lots of perks and benefits for choosing Gatsby Cloud as your hosting provider for Gatsby sites. The most notable would be; Gatsby Build, Preview, and Reports.
Gatsby Builds, currently in beta at the time of this writing, is expected to be generally available soon. It’s a build environment designed for Gatsby so you can expect faster build times. For example, comparing the container used by GitHub Actions to build your site is a base Ubuntu image which requires installing dependencies during each build process. Gatsby Build could offer an image with basic requirements dramatically reducing that time.
Gatsby Preview, is available now and offers real time updates for viewing live content changes from your headless CMS. In our case, it would be editing WordPress content and Gatsby displaying those content changes in the cloud using Preview, all without running a local development environment. This is invaluable for teams who manage content. It provides access to view and approve content changes without running your builds or running Gatsby develop locally. Perfect for non-technical users or really anyone who enjoys saving time.
The third reason would be performance reports. Each build on Gatsby Cloud offers a Google Lighthorse report and compares it to the previous build.
Okay, let’s get started! Here’s what we’ll cover.
To recap: Shifter hosts the WordPress site. Gatsby is developed locally and version-controlled on GitHub. Netlify is where the Gatsby build is hosted.
Here’s a visual example of the workflow.
Setting up your WordPress site on Shifter
Create a Shifter account if you don’t already have one. Create a new site in that account. For sourcing content from Gatsby, the free tier from Shifter is available to use.
Please note we have a free tier and a free trial. If you created a new account and did not validate that account the trial only lasts 7 days. Validating your account keeps it free but the site will not be removed after the trial period.
If you were able to create a new site on Shifter, log into your WordPress site. If you have an existing site you can migrate using the recommended All-in-One WP Migration plugin and use our guide for that or you can start fresh with a blank site. If you are creating new content, please keep in mind that some queries in the Gatsby site may not exist.
For this demo, we will be making the content from our WordPress site available as well in the .wpress format which can be imported into your site using All-in-One WP Migration. The .wpress export can be located here if you want to use that.
Now that you’ve created a WordPress site on Shifter you need to note the site ID which can be found in the site settings in the Shifter dashboard. You’ll need to add this to your GitHub Action.
That’s all we need to do with WordPress for now. You can create a static site for fun if you want or just power down the container.
Setting up your Gatsby Site
For this demo, we forked Jason Bahl’s Gatsby demos site which was built to use WPGraphQL. He’s also the creator of WPGraphQL so we have to give the biggest of shout-outs for making most of this demo possible.
Start by git cloning the Shifter Gatsby starter to your local machine. If you migrated the demo content from our WordPress site all the queries in Gatsby should work.
If you have the starter Gatsby site on your local machine, open up the files in your preferred IDE or text editor. If you want to start developing locally there is one file you need to focus on. That is the gatsby-config.js file.
In gatsby-config.js there are a few variables at the top of the file. If you are developing locally you may need to edit these. They are the wordPressUrl, and wordPressGraphQlUrl variables. We set ours to use Shifter Local’s default web address. If you are using Shifter Local these may be the same but if you are using another tool this may be different.
The URL you use to access WordPress locally and the URL you use to access the GraphQL is what you need. Also, you do not need to edit the REPLACE_… variable. That’s the variable name. you can ignore it.
At this point, you should be able to run npm install and npm run develop, or if you have the Gatsby CLI installed, run gatsby develop.
If everything checks out and you were able to successfully build
A quick note about local development
It’s not required but you can also set up a local WordPress site using Shifter Local. It’s a docker based container for running WordPress and it matches the Shifter hosting environment. You can run any local WordPress site though. If you are a WordPress developer I’m sure you have your preferred method.
If you do set up your Gatsby site and you want to develop locally with Shifter Local, you’ll need to modify the Gatsby run develop command. Since Shifter Local uses a self-signed HTTPS certificate Gatsby will throw an error during the development build process. The flag you need to add is the following.
NODE_TLS_REJECT_UNAUTHORIZED=0 npm run develop
This asks Node.js to ignore the self-signed certificate so you can start the development build and watch. If your gatsby develop command fails run start it could be this reason. In my case, I got a few errors and thought it was my code but I was just missing that.
For more info on adding env vars to your gatsby develop and build processes check out their docs.
Setting up access for deploying to Netlify
We’ll need a place to deploy this Gatsby site and that’s where Netlify comes in. When our builds are complete those files are pushed to Netlify for the world to see.
Create an account on Netlify if you don’t already have one or log into your existing account. Navigate to the user settings and applications page.
Here you need to create a new personal application token that will be able to access your Netlify account. Personal access tokens can do things on your behalf like create sites in Netlify. The way we’ll use this personal access token is in the GitHub Action. When we push our Gatsby code to GitHub, the action is triggered and builds the Gatsby site. When the build has finished the files are pushed to Netlify and that action is allowed to access the Netlify account because we’ve given it access using this token.
Next, create a new site on Netlify using their create a site from GitHub feature. The GitHub repo you’ll use is the gatsby site you deployed. You can give this site a name if you want or use the auto-generated name that Netlify creates for you. After creating a site Netlify will assign it an App ID. This can be found in the settings tab of your Netlify site. So far, you should have a Shifter site ID, your Netlify personal access token, and your Netlify app ID. You’ll need all of these for GitHub.
With Netlify setup and your Shifter site set up, you can now move onto setting up your Gatsby site locally.
Setting up your Gatsby site on GitHub and using GitHub Actions
With your local site running in development mode, check-in your files to version control. In this case, we are using git and we’re pushing to GitHub. Create a repo on GitHub and push your code there.
A quick tip, if you have not tried Hub for GitHub yet I recommend giving it a try. It’s a helpful tool for creating repos without leaving the command line.
With your Gatsby site code on GitHub, navigate to the settings tab. There you’ll find a section called secrets. This is where you can store super-secret information like your Shifter site ID, username, password, and your Netlify auth token.
From the notes we’ve collected you need to add the following secrets.
That’s the personal access token you created on your Netlify account and the app ID of the site you created. It’s also your Shifter username and password, and site ID from your WordPress site hosted on Shifter.
These variables are securely stored on GitHub and they are used by Github Actions.
Shifter GitHub Actions Explained
We included the GitHub Actions config file as a part of our Gatsby starter but if you want to check it out it’s located in the .github/workflows/main.yml file.
This file details all the requirements for each action such as how to run Gatsby build, what URLs to search and replace, when to start and stop the WordPress container on GitHub, and where to deploy the build.
If you have an existing Gatsby site and you’re running WordPress on Shifter, you can reference this file to get started or use the Shifter GitHub Action in the marketplace.
Source from this demo:
Shifter on the GitHub Actions Marketplace:
If you are new to GitHub Actions like we were, check out everything that’s available here:
The number of available actions to use is growing all the time or give it a try and create your own!
Viewing Shifter GitHub Actions.. in action
If you have everything set up and ready to go, when you commit and push code to GitHub the action should be triggered. If it does trigger but failed to complete you can view the actions log to see where it failed.
While I was testing this early on my builds failed and it was related everything from typos in my Gatsby site to adding the wrong site ID. Simple things that were all easily resolved.
You can even expand each step in your Action to view the logs. For example, you can watch the Gatsby build happen in real-time as it’s happening.
I’m certain this post / how-to guide could be shorter and more concise. We ask for your feedback for helping us do just that. If you have any suggestions while following this guide let us know as we would like to improve it for everyone.
If you had trouble with any step in the process also don’t hesitate to reach out. We also host Shifter community events at local meetups. Reach out and let us know what your local meetup is and we’ll see if we can be there!
If you happen to be in Japan, you are welcome to participate in the ShiftUp!, our community event for Shifter users hosted in Kobe and Tokyo.
There’s also WordCamps we can help in person at. Follow us on Twitter for sponsor events where we may be hosting a sponsor booth.
We hope to see you soon!