WordPress Development

Deploying WordPress Themes and Plugins with GitHub Actions

Deploying WordPress Themes and Plugins with GitHub Actions

For a long time, my deployment process for client themes was “save the file, drag it into FileZilla, refresh the browser”. It worked, mostly. Then one afternoon I uploaded a half-finished template file by accident while syncing a folder, and a client’s homepage showed a PHP error for twenty minutes before I noticed. Once you deploy WordPress with GitHub Actions, that kind of mistake becomes very hard to make.

That was the push I needed to set up proper deployments. Now, every change goes through Git, and a GitHub Actions workflow builds the assets, runs some basic checks and deploys to the server. If something goes wrong, the history shows exactly what changed, and rolling back is one click.

This article walks through a practical setup for deploying a custom WordPress theme or plugin with GitHub Actions. It’s aimed at freelancers and small teams who don’t need a complex platform but want something more reliable than manual uploads.

What we’re deploying, and what we’re not

The first decision is what lives in Git. For most WordPress projects, I version only the custom code:

  • The custom theme, or child theme
  • Custom plugins
  • Must-use plugins
  • Configuration files that aren’t secret

I don’t put WordPress core, third-party plugins, uploads or the database in the repository. Core and plugins are managed through the dashboard, WP-CLI or Composer. Uploads and the database are content, not code, and they move in the opposite direction, from production to development.

Keeping the repository focused on custom code keeps it small and makes deployments fast and predictable.

The shape of the workflow

A basic deployment workflow does four things:

  1. Checks out the code when changes are pushed to a specific branch.
  2. Builds front-end assets, such as compiling Sass or bundling JavaScript.
  3. Runs quick checks, like PHP syntax and coding standards.
  4. Copies the built files to the server over SSH.

GitHub Actions workflows live in the repository under .github/workflows as YAML files. Here’s a complete example for a theme:

run: find . -name "*.php" -not -path "./node_modules/*" -print0xargs -0 -n1 php -l

Let’s go through the important parts.

Triggering on the right branch

The on: push: branches: [main] line means the workflow runs whenever code is pushed to main. A common pattern is to have two workflows, or two jobs: one that deploys the staging branch to a staging site, and one that deploys main to production.

That gives you a natural process: develop on a feature branch, merge to staging and check it there, then merge to main to go live.

Building assets

If your theme uses a build step, run it in the workflow rather than committing built files. That keeps the repository clean and ensures production always gets assets built from the current source.

The npm ci command installs dependencies exactly as specified in package-lock.json, which is more reliable than npm install for automated builds.

If your theme has no build step, skip those lines.

Basic checks before deploying

Even simple checks catch the most embarrassing mistakes. The PHP syntax check runs php -l on every PHP file and fails the workflow if any file has a syntax error. That alone would have saved me that twenty-minute homepage error.

You can add more, such as running PHP_CodeSniffer with WordPress coding standards or a test suite, but start small. A workflow that takes ten minutes to run will tempt people to bypass it.

Handling secrets

Never put server credentials in the repository. GitHub has encrypted secrets for this, under the repository’s Settings, then Secrets and variables, then Actions. In the example above, these secrets are used:

  • DEPLOY_KEY. The private half of an SSH key created specifically for deployments.
  • KNOWN_HOSTS. The server’s SSH host key, so the workflow can verify it’s connecting to the right server.
  • SSH_USER, SSH_HOST, THEME_PATH. Connection details and the target folder.

Create a dedicated deploy key rather than using your personal key:

Add deploy_key.pub to the authorized_keys file of the user that owns the theme files on the server. Paste the contents of deploy_key into the DEPLOY_KEY secret. Then delete the local copy of the private key.

Get the known hosts entry with:

Using a dedicated key means you can revoke deployment access without affecting anyone’s personal access, and the key can be restricted to a specific user with limited permissions.

Deploying with rsync

Rsync copies only files that have changed, which makes deployments fast. The flags used:

  • -a preserves permissions and timestamps and copies recursively.
  • -z compresses data in transit.
  • –delete removes files on the server that no longer exist in the repository, so deleted templates don’t linger.
  • –exclude-from skips files listed in a .deployignore file.

The .deployignore file keeps development files off the server:

Be careful with –delete. Make sure the target path is exactly the theme folder, never wp-content or the site root. A wrong path combined with –delete can remove a lot of files very quickly. Test the first deployment with –dry-run added to see what would happen without changing anything.

After deployment

Some projects need steps after files are copied:

  • Clearing the page cache, so visitors see the new theme files immediately.
  • Running database migrations, if your plugin includes them.
  • Flushing rewrite rules, if you’ve changed custom post types or routes.

You can run WP-CLI commands over SSH from the workflow:

Keep these steps small and safe. A failed post-deploy step should never leave the site broken.

Rolling back

The simplest rollback with this setup is to revert the commit in GitHub and push. The workflow runs again and deploys the previous version. Because rsync with –delete makes the server match the repository, the server returns to its earlier state.

For larger projects, you might use a release-based approach, where each deployment goes into a new timestamped folder and a symlink points to the current release. Rolling back is then just changing the symlink. That’s more complex to set up, but it makes deployments atomic, meaning visitors never see a half-deployed state. For a typical theme, rsync is fast enough that this rarely matters.

Protecting the main branch

Automation only helps if people use it. In GitHub’s branch protection settings, you can require pull requests before merging to main and require the workflow’s checks to pass. That prevents someone pushing a quick fix directly to production without review.

For a solo developer, that might feel like overkill, but even then a pull request gives you one last moment to read the diff before it goes live.

Common problems

Permission denied on deploy. The deploy user doesn’t own the target folder, or the public key isn’t in the right authorized_keys file. Check ownership on the server and test the key manually from your machine.

Host key verification failed. The KNOWN_HOSTS secret is missing or wrong. Re-run ssh-keyscan and update it.

Files deployed but site unchanged. Usually caching. Clear page, object and CDN caches, and check that asset version numbers change so browsers fetch new files.

Builds work locally but fail in Actions. Usually a Node version mismatch. Set the same version in the workflow as you use locally, and commit package-lock.json.

Is it worth it for small projects?

Yes, in my experience. The first setup takes an hour or two. After that, copying the workflow to a new project takes minutes. In return, you get a complete history of every deployment, automatic checks that catch obvious errors, no more forgotten uploads and an easy way to hand projects to other developers.

It also changes how you work. When deploying is a push, you deploy smaller changes more often, which means each one is less risky. That’s the real benefit.

Adding a staging step

Once the basic workflow is running, the most useful upgrade is a staging deployment. Create a second workflow file that triggers on pushes to a staging branch and deploys to the staging server, using its own set of secrets. GitHub Environments let you group those secrets and even require a manual approval before the production job runs.

That gives you a simple, visible path for every change: open a pull request, merge it into staging, check the result on the staging site, then merge staging into main. Clients can review changes on staging before they go live, and you have a record of who approved what. For small agencies, that approval trail alone often justifies the setup, because it ends the “I never asked for that change” conversations. The first time you deploy WordPress with GitHub Actions and watch a broken commit get stopped before it reaches the server, the hour of setup will feel well spent.

Frequently asked questions

Can I deploy to shared hosting this way?

If the host offers SSH access, yes. If it only offers SFTP, there are GitHub Actions that deploy over SFTP or FTPS, though rsync over SSH is faster and more reliable.

Should I commit the vendor folder for Composer dependencies?

Generally no. Run composer install –no-dev in the workflow, like npm ci, and deploy the result.

How do I deploy a plugin instead of a theme?

The same workflow works. Change the target path to the plugin’s folder in wp-content/plugins.

What about the database?

Code moves up from development to production. Content moves down from production. Changes to database structure should be handled by code, such as a plugin’s upgrade routine, not by copying databases between environments.