Automatically Deploy to WordPress.com Using GitHub Actions

WordPress.com provides you with a great experience out-of-the-box, from superb SEO to social media sharing, custom web fonts, and so much more.

At WordPress.com, we also cover very advanced needs, such as connecting GitHub to sites on a Business or eCommerce plan. This allows you to automate deployment using GitHub Actions, which can become a huge productivity boost for developers. You’ll be happy to know that GitHub and WordPress.com work beautifully together.

Prerequisite: Start your WordPress.com site now

Tutorial Overview, GitHub Deployment Automation

This is a tutorial that explains how to achieve deep customization of your WordPress.com site using SFTP access, including how to deploy custom themes and plugins. Moreover, we’ll explain how you can automate the deployment of those changes by simply connecting your GitHub repository to WordPress.com. Whenever you push changes to a specific branch of your GitHub repository, those changes will automatically be deployed to your site at WordPress.com as well.

Create SFTP Credentials at WordPress.com

At WordPress.com, create SFTP Credentials for your site. SFTP access is available to administrators on the WordPress.com Business and eCommerce plans.

WordPress.com SFTP creds settings page

Log In Over SFTP, Manually Review Directory Structure

In the screenshot below, which was taken from Filezilla (a popular SFTP client), you can see the primary extensibility features in WordPress, i.e., themes and plugins. Themes are in /wp-content/themes; plugins are in /wp-content/plugins.

If you recreate this structure in a Git repository starting from the /wp-content directory, then whenever you push changes to the GitHub repository, they will be deployed automatically to your site at WordPress.com.

Some core directories and files have a question mark (?) icon next to them. This denotes they are part of your site’s core installation. We do not allow modifying core files as they are required for your site to function properly.

Filezilla SFTP client example screenshot

Create GitHub Repository

I’ve created an example GitHub repository named: wp-github-actions-test-site. Inside this repository, I’ve added a custom theme and a custom plugin that I’ll deploy automatically as part of this tutorial. I have already pushed these changes to the main branch of my example repository. Using my example (screenshot below), please create a GitHub repository for your site at WordPress.com.

Creating GitHub repo example screenshot

Create New Branch: wordpress.com

Create a new branch with the name wordpress.com, such that you have two branches: main and wordpress.com. Whenever you push changes to the wordpress.com branch, you want those changes to be deployed automatically to WordPress.com. You can create the new branch using GitHub’s interface, as seen below, or from the command line. The choice is yours.

GitHub repo branch structure example screenshot

Create GitHub Action

On the main branch, create a workflow by copying and pasting the code snippet (provided below). Please copy & paste the snippet with no modifications into .github/workflows/wordpress.com.yml

Note: It is easiest to use GitHub’s interface for this, as shown here.

Creating GitHub Action workflow example screenshot
GitHub Actions WordPress automation example workflow script screenshot

WordPress.com Workflow Code Snippet

Copy & paste into .github/workflows/wordpress.com.yml

name: Deploy to WordPress.com
on:
  push:
    branches: [ wordpress.com ]
jobs:
  FTP-Deploy-Action:
    name: FTP-Deploy-Action
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@master
        with:
          fetch-depth: 2
      - name: FTP-Deploy-Action
        uses: Automattic/FTP-Deploy-Action@3.0.1
        with:
          ftp-server: sftp://sftp.wp.com/htdocs/
          ftp-username: ${{ secrets.FTP_USER }}
          ftp-password: ${{ secrets.FTP_PASSWORD }}
          known-hosts: "\
            sftp.wp.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQAB\
            AAABAQDwfT/YEhOKO2Z0+XrjRqUS5Q2Ali6AlhOhZtzlIfMOvm03Sype\
            DJH70tlUHasS+nm0SnZ01fOiEeAXa91ZhMihIYUT3nTGuiA2J3uVYsyS\
            CJefvhWc0kg1FbEus3V3cVmx4e3XctdkzLbOgPNngypZocbP+8yCpbx6\
            Kb9lihmgTjgGn2QzbK1enRSzsN/CbjVhej9jwukbrWqdCrQsKAsoZ2p6\
            YCtcKbHS+Yy4RwcO9PxZUBkeMXUrejms027bRcdVfwf55hWSD9xYEHpE\
            HupkSL4ofWs3UKeRGz+jCCzl7Nu0S6VSwK4Zzll0auHI0Hwh8WKTJbSn\
            1gxCdF93/rmP\
          "

Create GitHub Secrets

The workflow code snippet references two secrets:

- ${{ secrets.FTP_USER }}
- ${{ secrets.FTP_PASSWORD }}

Create these two secrets in your GitHub repository using the SFTP credentials that you obtained at WordPress.com in an earlier part of this tutorial. Please define both the FTP_USER and FTP_PASSWORD secrets.

GitHub Actions workflow secret example screenshot
GitHub Actions secrets settings in workflow

Push Changes, Test Deployment Automation

Now that you have everything configured properly, update your local copy of the GitHub repository using Git from the command line. Start by fetching all updates, then pull changes into the main branch, merge them into the wordpress.com branch, and finally push those changes to the wordpress.com branch. In doing so, you will test the GitHub Action workflow to make sure things are working properly.

$ git fetch --all
$ git checkout main && git pull
$ git checkout wordpress.com && git merge main
$ git push --set-upstream origin wordpress.com

At this point, you can visit the Actions tab at GitHub to review and observe status. Since you pushed to the wordpress.com branch, the workflow you created should already be running. When it’s finished, the status icon will turn green with a checkmark indicating your changes were deployed successfully to WordPress.com.

GitHub Actions workflow ran success screen within repository

In this case, the workflow is deploying your last change, which was to “Create the wordpress.com.yml” file itself — from a previous step in this tutorial.

In the future, when you merge and then push any changes, such as theme or plugin updates, from the main branch into the wordpress.com branch, they’ll be deployed to WordPress.com automatically. Yay! 🎉

Business and eCommerce Plans at WordPress.com

At WordPress.com, you’ll be well-equipped without installing custom themes or plugins. However, if you want to take your site to the next level, both our Business and eCommerce plans support several additional features. These plans include increased storage, custom themes, custom plugins, and SFTP access, making the GitHub integration described in this tutorial possible.

Start your WordPress.com site now

The Rise of WordPress Frontend Options, Themes vs. REST API + JS/React: Decoupling WordPress

The opportunity to move to a decoupled or headless WordPress system is an emerging discussion because of the broad range of possibilities it opens for developers with complex architecture needs. Decoupling, or separating the backend from the frontend with a framework like Strattic, also delivers a level of complexity that should be factored in when planning a project’s development. Certain projects can benefit from decoupling, while the fully integrated WordPress platform better serves most use cases.

When the words “Learn JavaScript Deeply” were spoken by Matt Mullenweg in 2015, the world hadn’t yet fully realized the scope of what would soon be possible. Then, when the WordPress REST API was released as part of core in 2016, the platform made a giant leap into the future. Of course, Gutenberg, the WordPress editor introduced in late 2018, highlighted what could be accomplished with this new feature as it uses the REST API to create and update posts by communicating with the WordPress core backend. Both the REST API and a modern JS framework built on React are shipped with every copy of WordPress and are now integral components.

This evolution of WordPress means that today, developers are no longer limited to PHP. Instead, developers can create apps built on React and other JavaScript frameworks, served by Node, and powered by the WordPress REST API. This enables WordPress development by frontend developers who don’t write PHP, as well as integration between WordPress and other frontend technologies and systems. 

Key Issues To Consider 

First, a reminder of some key issues worth seriously considering as you weigh decoupling, versus using WordPress as a complete solution. 

  • Performance – Many developers want to decouple in the belief that this increases performance or scale. This, however, rarely proves itself in reality.  Decoupled front-ends must be scaled separately from the WordPress backend. A good host largely solves scaling in traditional architectures. A top-tier enterprise WordPress platform, such as WordPress VIP, will also scale endpoints for decoupled architectures and can serve Node apps at the same scale as anything else being served.  However, decoupled front-ends present their own points of failure, their own caching mechanisms, and generally increase performance risk.  For example, if the site is down, is the front-end causing the problem?  If so, which part of it?  Or is it the API?  
  • Total Cost of Ownership (TCO) – Even teams with mature JS capacity typically find that decoupled experiences have higher TCO than traditional ones. This is primarily due to duplicate hosting, multiple technologies, split teams, multiple codebases, multiple caching strategies, and more. The overall cost of support and build of a decoupled project is almost always higher than a traditional integrated WordPress build. It is essential to consider cost in terms of the whole lifecycle of the project.
  • Solved problems / ecosystem – Out-of-the-box WordPress architectures have more access to integrations and community solutions than custom front-ends.  Sure, React supports many community extensions and integrations, but when we limit the scope to the kinds of extensions required for content apps, WordPress’ extensions and integrations are almost always easier and cheaper to figure out. Examples include AMP and other delivery channels, authentication/SSO, many platform integrations, and even features such as “preview” become an issue that needs to be solved anew for decoupled sites.

Available Toolkit

Today’s decoupled WordPress toolkit is quickly growing, and it includes the following popular solutions.

  • GraphQL / WPGraphQLGraphQL is a Query Language built to craft more precise and lightweight queries to bring only the data you need from the REST API into your front-end application. WPGraphQL extends this framework to be specific to WordPress.
  • GatsbyJS – GatsbyJS is a React and GraphQL-powered static site generator built for speed.
  • FrontityFrontity is a React framework for WordPress. Out of the box, it is set up to consume content from the WordPress REST API, giving developers a big head start by providing many of the most common queries already built-in.
  • StratticStrattic is a static site generator and hosting platform tuned for WordPress.

When Decoupling is an Option

Some of the most relevant reasons developers choose a decoupled approach for complex WordPress projects include:

  • Portability – The app or digital experience needs to be extremely portable or agnostic of the back-end technology.
  • Diverse data sources – The app or digital experience pulls data from more than a small handful of sources, with WordPress being only one of those, and where the WordPress source is probably not the most central of those sources.
  • Leveraging an existing JS-oriented dev team – Frequently, teams of JS developers, especially newly minted ones, want to build Node apps and leverage modern front-ends like React. While the current team’s capabilities are worth considering, this reason may or may not be outweighed by other factors. In addition, there is plenty of exciting work for modern JS developers to do within WordPress itself.
  • Moving into the future of modern JS frameworks – Sometimes, teams want to leverage modern frameworks because the technology is newer, supports app-like behaviors natively in the browser, and it is relatively easy to hire qualified modern JS devs.  These are valid considerations, especially if there are other business reasons to invest in this capacity. However, it is crucial to avoid automatically assuming that modern JS does everything better, cheaper, or faster than WordPress’s mix of PHP and modern JS.

AccuWeather: Making Brilliant Use of Decoupling

This marriage of technologies is the result of leveraging the long-term stability of WordPress with its vast ecosystem with modern frameworks such as React. When used appropriately, this union enables the creation of brilliantly complex applications. One example of this in use is the extremely popular AccuWeather. 

AccuWeather is recognized as the most accurate source of weather forecasts and warnings in the world, serving roughly 1.5 billion people daily. The system comprises weather forecasts, local media partnerships, enterprise solutions, APIs, news, videos, podcasts, and weather data. 

AccuWeather uses a decoupled WordPress stack that includes over 750+ million WordPress requests per day and 50+ billion data calls per day. 

So what advantages were gained by AccuWeather moving to this architecture? 

  1. By retaining the use of WordPress, they can utilize the backend UI/UX experience for the content team. While content is only one part of AccuWeather, it is an ever-growing piece of the brand and company. Using the WordPress backend, the editorial team can work with the most widely adopted and accessible CMS platform, which is used by 40% of the web.
  2. By decoupling the front-end from the back-end, rapid site redesign was made possible without worrying about making massive changes to the platform’s CMS side. 
  3. Finally, the decoupling makes the content easily accessible by other applications. Various development teams, such as app or enterprise teams, can present the content anywhere. For example, they can include a newsfeed with localized content in AccuWeather apps or present targeted video in a widget on a partner site. 

While AccuWeather makes extensive use of the REST API, many other companies and projects can benefit from utilizing and extending the REST API. For example:

  • A vendor may utilize the API for large-scale content migration.
  • A CMS dev team may extend the API to to create mobile apps, or facilitate communication that helps complete 3rd-party integrations.
  • Much like Laravel, WordPress offers developers an extensible REST API framework. A company can easily add new routes and endpoints, giving them a more predictable and structured way to interact with site content or other backend data. They’ll spend less time building tools to access data, and more time creating better user experiences.

One Final Consideration

If all of this seems like the perfect solution for every future project, there’s one final thing to consider before making that jump. 

Decoupling requires a developer or team of developers throughout the entire lifecycle – Developers need to not only be involved in the creation of the project, but will also be needed to manage the site throughout its lifecycle. The client will rarely be able to manage this on their own. While many fully integrated WordPress websites can be left in the care of the site owner, a decoupled WordPress site is usually far too complex for the average site owner to maintain, keep updated, and ensure security and forward compatibility.

Decision Worksheet

Use an internal decision worksheet, such as the one we’ve provided here, to help determine if your project should move forward with a decoupled architecture or not. The more times you answer “No” to the questions, the more caution you should exercise before moving forward. You may still decide that decoupled is the best option, even if you’ve answered ‘No’ to many of the questions, but more deliberation might be needed in that instance.

The Best Choice For You

WordPress leverages the best of a stable, mature product with the promise of evolving with ever-changing modern technological future platforms. Some projects may benefit from the WordPress platform’s integrated approach, while others might require a decoupled architecture. When making decisions, consider the following:

  1. Ask why – Identify the key drivers of your decision, and be honest about this. Are you choosing the more complex decoupling method because it’s the latest cool technology, or is it because it best serves the project?
  2. Consider the total cost of ownership – The TCO over the whole project lifecycle, including multiple hosting, increased complexity, more technical debt, etc., may be significantly higher than you expect.
  3. Look ahead – The landscape around JavaScript and WordPress is changing and expanding rapidly. Can you position your team and your application to thrive in the years and months to come?
  4. Embrace JavaScript – Regardless of your decision to decouple or not, embracing JavaScript will enable you to do exciting things, even within WordPress internally. Learn JavaScript Deeply…still as true today as the day Matt first spoke those words.

Many factors will influence your decision, but WordPress will always be there, either integrated or decoupled, to move your project forward in the best possible way.

Written in collaboration with Donna Cavalier & Jason Caldwell from WordPress.com, and Ryan Sholin & Matt Perry and WordPress VIP.