How to Deploy a WordPress Theme from GitHub (Without FTP)

You edit a WordPress theme, the change works locally, and then you have to get it onto the live site. For most small business sites that still means the same ritual: zip the folder, open the file manager, upload, unzip, and hope nothing was missed.

It works until the day it does not, and the way you find out is a phone call from the client.

This is how theme deployment actually works, what a deploy has to do to be safe on a site with no staging server, and the plugin we built to do it.

Why FTP is the wrong tool for a theme you edit every week

FTP is fine for a file you touch twice a year. A custom theme is not that. If the site is built without page builders — which is how we build every client site — the theme is the site, and it changes constantly.

Three things go wrong with the manual route:

• It is partial. Uploading changed files one by one leaves orphans behind: a template you renamed still sits on the server and keeps being used.
• There is no undo. Once the files are overwritten, the previous version exists only on your machine, if it exists at all.
• Nothing checks the result. The upload finishing is not the same as the site still working. A fatal error in one file takes the whole site down, and FTP will report success.

The last one is what makes this worth automating. Not the time saved — the failure you do not notice.

What a safe theme deploy actually has to do

Replacing a theme folder on a live site is a sequence, and skipping any step is where the risk lives:

1. Fetch the code from a known source, at a known version or branch.
2. Extract and validate it. A theme folder without style.css is not a theme, and installing it would break the site.
3. Back up the theme that is currently live, in full, before touching anything.
4. Install by replacing the folder completely, so renamed and deleted files actually disappear.
5. Verify by requesting the site and checking it responds.
6. Roll back automatically if it does not.

Steps 3, 5 and 6 are the ones that get skipped, and they are the only ones that matter when something goes wrong.

The rule: assume the deploy will fail

On a large project the safety net is somewhere else — a staging environment, a CI pipeline, a developer on call. A restaurant or a rental operator in Grand Cayman has none of that. There is one site, it is live, and the person who might notice a problem first is a customer trying to book.

So the design rule is the opposite of the usual one. Do not optimise for the deploy that works. Optimise for the one that does not: make sure that the worst case leaves the site exactly where it started.

That is the whole reason the backup happens before the install and the verification happens after. A deploy that cannot prove the site still answers should not be allowed to stand.

Deploying from GitHub instead of from your laptop

Pulling the code from a repository rather than uploading it from a machine fixes a second problem: what is live is whatever is in the branch, not whatever happened to be in the folder of whoever did the upload.

That matters more now than it did two years ago. When an AI assistant writes the change — Claude Code, Antigravity, Cursor, whichever — the code lands in the repository. The repository is the source of truth. Going through a local zip puts a human step in the middle of an otherwise clean path, and human steps are where files get missed.

Public and private repositories

A public repository needs no credentials. A private one needs a GitHub token: a classic token with the repo scope, or a fine-grained token with Contents: Read-only on that repository. Nothing broader than that — read access to one repository is all a deploy requires.

What this does not cover

Worth being explicit, because deploy tools are often sold as more than they are:

• It deploys a theme. Not plugins, not the database, not uploads.
• It is not a staging environment. It makes the live deploy survivable; it does not give you somewhere to test first.
• Content stays in WordPress. Posts, pages and media are unaffected — only the theme folder is replaced.
• Your server has to be able to write to wp-content/themes directly and reach api.github.com. On restrictive hosting, neither is guaranteed.

The plugin

We built AG Theme Sync for GitHub because we needed it on our own client builds, and we published it because a tool that solves a real problem is worth more in public than in a private repository.

It is free, GPL-licensed, and it does exactly the sequence above: one click from the admin bar, full backup, post-install verification, automatic rollback. It has been submitted to the official WordPress plugin directory and is waiting on review; in the meantime the ZIP and the install steps are on our plugins page.

See the plugin and download it →

If you only change one thing

You do not need our plugin to be safer than you are today. Before your next theme change, do this: copy the current theme folder somewhere you can find it, and after you upload, open the site in a private window and check a real page loads.

That is the backup and the verification, done by hand. Everything a deploy tool does is that, made reliable enough that nobody has to remember it.

A shorter version of this appeared on Andre’s LinkedIn. Related: the hidden input that broke a WordPress booking form.