WordPress GitHub Integration: How to Connect WordPress to GitHub

WordPress GitHub integration means connecting a Git repository to a WordPress site so code moves between the two automatically instead of by hand over FTP. Set it up once and every push updates the site, every change has a history, and a bad release can be undone.

This guide covers all four directions people need: what the integration is, how to connect WordPress to GitHub, how to deploy from GitHub to WordPress, and how to push an existing site up to a repository. The InstaWP method comes first because the deployment layer is part of the host. Four other methods follow.

What is WordPress GitHub integration?

WordPress GitHub integration is the practice of keeping your theme, plugin or site code in a GitHub repository and moving it into a live WordPress site through Git rather than manual file transfer. Every change is committed and version controlled, and a deployment tool pulls the latest code into the right folder on the WordPress server.

It always has two halves, and most confusion about it comes from conflating them.

• The repository. Where your code lives and where branches, pull requests and review happen. GitHub, GitLab and Bitbucket all do this job.
• The deployment layer. The piece that listens for new commits and puts the files into wp-content. A plugin, a CI pipeline or your host provides it, and it is the half people usually have to build themselves.

What it is not: hosting WordPress on GitHub. GitHub Pages serves static files, and WordPress needs PHP and MySQL. GitHub holds the code, something else has to run it.

With InstaWP Git Deployments the second half comes with the hosting account. Register a repository once as a Deployment and the platform handles cloning, branch tracking, the destination folder and any commands that run afterwards.

Why connect WordPress to GitHub?

Connecting WordPress to GitHub replaces a slow, error-prone manual process with one that is automated, version controlled and reversible. FTP and cPanel uploads give you no record of what changed, no clean way to collaborate, and no undo. Git fixes all three.

• Track every change to your codebase, with a full history of who changed what and when.
• Work in branches to build and test features without touching production.
• Collaborate without conflicts using pull requests and code review.
• Undo a bad release by reverting the commit and redeploying, or by restoring a snapshot taken before the deploy.

Picture building a new WooCommerce feature while a teammate tweaks SEO settings. With Git you each work in isolation, merge cleanly, and never overwrite each other. Here is how the traditional approach compares to a Git-based one.

What you need before you start

Three things, and only the first two are required.

If you want something to deploy without writing a plugin first, InstaWP keeps a minimal public repository you can fork: InstaWP/sample-wordpress-plugin. It is a single plugin.php and a README, which is exactly enough to watch a deployment land in wp-content/plugins and see the plugin appear in WP Admin.

How to connect WordPress to GitHub

Four steps: create the repository, register it in InstaWP as a Deployment, attach that Deployment to a site, and paste the InstaWP webhook URL into your repository settings. After that the connection is live and every push is picked up.

Step 1: Create your GitHub repository

If you do not already have one, go to GitHub and create a new repository. Name it after the thing it holds, such as sample-wordpress-plugin or client-theme, because that name is what you will recognise in the Deployments list later.

• Initialize with a README.md and a .gitignore file (optional).
• Clone it to your local machine using GitHub Desktop or the terminal.

Then add some code. A plugin needs only a header comment to be recognised by WordPress, which the Plugin Handbook header requirements set out in full. This is enough:

<?php
/*
Plugin Name: Hello World
Description: A simple Hello World plugin.
Version: 1.0
Author: Your Name
*/

function hello_world_footer() {
    echo '<p>Hello World from GitHub!</p>';
}
add_action( 'wp_footer', 'hello_world_footer' );

Commit and push it to your GitHub repository.

Step 2: Add a Deployment in InstaWP

A Deployment is a saved connection between InstaWP and your Git repository. In your InstaWP dashboard, go to Settings, open Deployments, then click Add New in the top right.

A modal opens asking for a few fields. Here is what each one does.

Click Add and the repository is registered. Full field reference is in the docs on how to add a Deployment.

Step 3: Connect the Deployment to your WordPress site

Now attach the Deployment so the code has somewhere to land. Open a site from the Sites page, choose Git Deployment, select the repository you just added, and click Save. Then click the copy icon to grab the webhook URL, which is the one thing you need in the next step.

Full steps are in the docs on how to connect a Deployment to a site.

Step 4: Set up the webhook in your repository

The webhook is what tells your Git host to notify InstaWP whenever you push. In GitHub, go to Settings, then Webhooks, and click Add webhook.

1. Paste the webhook URL you copied from InstaWP into the Payload URL field.
2. Set Content type to application/json.
3. Choose to trigger on push events.
4. Click Add webhook.

GitHub’s webhooks documentation covers the fields in more depth, including the Recent Deliveries tab. That tab is the first place to look if a push does not trigger anything.

The same step on GitLab and Bitbucket

The Add Deployment documentation names GitHub, GitLab and Bitbucket explicitly. The InstaWP half never changes: paste a repo URL, copy a webhook URL. Only the provider’s webhook screen differs.

One caveat worth stating plainly: the InstaWP deployment docs walk the GitHub screens only. GitLab and Bitbucket work the same way and the InstaWP side is identical, but for the webhook screen you are following your provider’s docs rather than an InstaWP screenshot.

How to deploy from GitHub to WordPress

The connection is made, so deploying is mostly a matter of pushing code. Three things are worth knowing: how to trigger a deploy without a push, where the logs are, and how to change a deployment later.

Step 5: Push your code and watch it land

1. Open your local code.
2. Change something, for example bump the plugin version to 1.1.
3. Commit and push to the branch the Deployment tracks.

GitHub fires the webhook, InstaWP pulls the commit into the destination folder, and any post-deployment commands run. Log into WP Admin with Magic Login to check. One detail the docs call out and it is easy to trip on: the first time a plugin arrives you still activate it once by hand. After that, pushes update the files in place with no further activation.

Step 6: Run a deployment manually when you need to

You can also deploy on demand: when you need the current commit without making a new one, or to re-run a deploy after fixing a failed post-deployment command. Open the Git Deployment panel for the site, select the repository, and trigger it.

For a Deployment attached to a template the flow differs. Push, open the template from the Templates page, confirm the Git Deployment and click Save, then create a new site from that template. The docs on how to run a deployment walk both paths with screenshots.

Step 7: Read the deployment and command logs

Every deployment, and every post-deployment command it runs, writes to a log inside InstaWP. Open the site, go to Site Tools, and view the logs. This is where the output of composer install, npm run build or a WP-CLI command appears, which is the difference between debugging a failed deploy and guessing at it.

The run command documentation covers the same log view from the commands side, and the WP-CLI command reference is where to check what a wp subcommand does before you wire it into a deploy.

Step 8: Edit or remove a deployment later

From Settings, then Deployments, the edit icon on any deployment lets you change the repository URL, switch the branch, repoint the destination folder or update the post-deployment commands.

Edit rather than rebuild when you rename a repo, cut over from develop to main for a release, or repoint at a different plugin folder. You can create as many deployments as you need across different sites and templates. Full reference: manage a deployment.

Four other ways to deploy WordPress from GitHub

Method 1 above is the InstaWP route. These four cover everything else, and they differ in setup time, automation and how much you maintain yourself.

Method 2: Use a Git deployment plugin

You can use the best Git deployment plugins for WordPress git integration as these plugins can pull a single theme or plugin from a repository into the site. Simple to start with, works on most hosts. The limits are real: one theme or plugin at a time, no multi-environment workflow, no pull-request previews, and one more plugin to keep updated.

For the sake of this guide, we using Deployer for Git plugin. Install and activate the plugin on your WordPress site.

In its settings, connect your GitHub account or paste a repository URL, adding a personal access token for private repos. Choose theme or plugin, then select the repository and branch.

Click Install, and enable push-to-deploy so a webhook updates it on each push. Activate the theme or plugin in WordPress as normal.

Method 3: Deploy with GitHub Actions and SSH or rsync

Write your own workflow that connects to your server over SSH and runs rsync or git pull on push. Total control, and you own every part of it: the pipeline, the SSH keys and secrets, and rollback. This suits teams with DevOps capacity and their own infrastructure.

Add your server’s SSH private key and host details to repository secrets, under Settings, then Secrets and variables, then Actions.

1. Create .github/workflows/deploy.yml triggered on push to your main branch.
2. In the job, check out the code, then use an SSH or rsync action to copy files to your server’s wp-content path, or run git pull on the server.
3. Add any build steps, such as composer install (see the Composer documentation) or npm run build.
4. Commit the workflow. Every push now deploys over SSH, and rollback is yours to handle.

Method 4: Deploy manually over SSH

SSH into the server, clone the repository once, and run git pull when you want to update. Free and dependency-light, but manual, easy to forget, and with no automation, previews or safety net beyond your own discipline.

1. Enable SSH on your host and connect from your terminal.
2. Navigate to the target folder, for example wp-content/themes, and git clone your repository the first time.
3. On each update, SSH in and run git pull.
4. Run any follow-up commands by hand, such as wp plugin activate or composer install.
5. Repeat on every change. No webhook, no preview, no automated rollback.

Method 5: Use a third-party deployment service

DeployHQ and Buddy connect to GitHub and deploy to your host over SSH or FTP. Both are capable, and both are an extra paid tool to configure on top of hosting, neither WordPress-specific. Their strength is deploying to several different hosts from one place, which is exactly the case a single host’s built-in deployment cannot serve.

1. Create an account with the service and connect your GitHub repository.
2. Add your server’s SSH or SFTP credentials as a deployment target.
3. Map the repository path to your server’s wp-content path and choose the branch.
4. Configure build or post-deploy commands if the service supports them.
5. Enable automatic deployments so each push to that branch triggers a deploy.

When InstaWP is not the right choice

Three cases where one of the methods above beats Method 1.

• One plugin or theme on a host you cannot move. The client is on a host with a contract and all you want is for one theme to update from a repo. Installing WP Pusher or Git Updater is a smaller change than migrating the site. Method 2.
• You already have a working CI/CD pipeline and people who run it. If your team has Actions deploying to infrastructure you control, with your own test and rollback stages, changing the deploy target buys you little. Method 3.
• You deploy the same code to several unrelated hosts. A deployment layer built into one host cannot push to a different provider’s server. That is what DeployHQ and Buddy are for. Method 5.

The case for Method 1 is narrower than “always” and stronger for it: you want the deployment layer, hosting, staging and backups in one account rather than four tools you integrate yourself.

Public vs private repositories

InstaWP deploys from both. The connection steps are the same either way, including the webhook. The difference is entirely in how the Deployment itself is configured: a private repo needs the SSH URL and an SSH key so InstaWP can read the code.

Copy the public half of that key pair into your repository under Settings, then Deploy keys. GitHub’s guide to managing deploy keys explains why a deploy key is the right credential here: it grants access to one repository rather than to your whole account.

Full walkthrough: the private repository section of add a Deployment.

How to roll back a bad deployment

“Roll back instantly” only means something once you have seen the steps, so here they are. Two routes, and they undo different things.

Route 1: revert the commit and redeploy (code only)

Use this when the deploy delivered exactly what you committed and the commit was wrong. Because your Deployment tracks a branch, putting the branch back puts the site back.

# find the commit that broke it
git log --oneline -5

# undo it as a new commit, keeping history intact
git revert <bad-commit-sha>
git push origin main

The push fires the same webhook as any other, so the previous code is pulled back into the destination folder. If there is no webhook on that branch, trigger the deployment manually (Step 6 above). Prefer git revert over git reset: a revert is a new commit that undoes the old one, so history other people have already pulled stays valid.

Route 2: restore a snapshot or backup (the whole site)

Reverting a commit puts the files back, not the database. So it will not help if the deploy ran a migration, a plugin wrote options on activation, or content changed. For that you need a point-in-time copy of the whole site.

1. Before a risky deploy, save the site as a snapshot. The docs on how to create snapshots cover the options, and snapshots overview explains what a snapshot contains.
2. If the deploy goes wrong, restore the site from that snapshot, or from an automatic backup if one covers the window.
3. Fix the code in the repository, then deploy again.

Preview every pull request on a fresh WordPress site

This is the part worth reading even if you skim the rest. A Deployment does not have to point at a site. Point it at a template and the relationship inverts: rather than a push updating one existing site, a push means the next site built from that template already contains your latest code.

Combined with GitHub Actions, every pull request gets its own disposable WordPress install carrying the branch code, torn down when the PR closes. A reviewer opens a URL instead of pulling a branch and setting up locally.

Setting it up is three moves. Save a site as a template (the docs cover how to create a template), attach the Deployment to it, then paste the template’s webhook URL into your repository the same way you did for a site.

Then create a site from the template, temporary or reserved, and it comes up with your latest commit already in place.

Public and private repositories both work here. The connect to template documentation states the connection steps are identical for both, and only the Deployment’s own configuration differs. Full walkthrough there.

Concretely, this is what lets you review a pull request on a real site instead of a screenshot, demo an unmerged feature to a client, test a plugin against a specific WordPress and PHP version, and run QA on a clean install every time rather than one that has drifted. It is also the mechanism behind plugin and theme demos and a WaaS workflow.

Automate deployments with GitHub Actions

GitHub Actions turns the template setup above into something that runs without anybody clicking: a fresh site when a pull request opens, login details posted as a PR comment, and the site deleted when the PR closes.

Four parts: a site saved as a private snapshot, a Deployment pointed at it, an InstaWP API token stored as a repository secret, and a workflow file. InstaWP generates the workflow from the snapshot, so you copy rather than write it.

The token comes from Profile, then Account, then API Token. Store it in the repository as a secret named INSTAWP_TOKEN, never in the workflow file itself.

The workflow itself is short:

name: InstaWP WordPress Testing

on:
  pull_request:
    types: [opened]

jobs:
  create-wp-for-testing:
    runs-on: ubuntu-latest
    steps:
      - uses: instawp/wordpress-testing-automation@main
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          INSTAWP_TOKEN: ${{ secrets.INSTAWP_TOKEN }}
          INSTAWP_TEMPLATE_SLUG: github-template-demo
          REPO_ID: 3
          INSTAWP_ACTION: create-site-template

That creates a WordPress instance from the named template and comments the access details on the pull request. Set INSTAWP_ACTION to destroy-site-template in a second job triggered on closed to clean up. The action is open source at instawp/wordpress-testing-automation, so you can read exactly what it does before granting it a token.

Reference: the InstaWP docs on GitHub Actions, and GitHub’s own Actions documentation for workflow syntax.

If you would rather not use the action, the InstaWP CLI does the same job in two lines of any pipeline:

- run: npm i -g @instawp/cli@beta
- run: instawp create --name pr-${{ github.event.number }} --json
  env:
    INSTAWP_TOKEN: ${{ secrets.INSTAWP_TOKEN }}

The --json output includes the live URL to post back on the pull request. The CLI in CI/CD documentation covers the rest of the flags. No SSH keys to rotate, and no runner waiting on Docker to boot.

WordPress Git workflows and CI/CD

Connecting a repo is the mechanism. The workflow around it decides whether Git makes your WordPress work calmer or just adds a step. Three decisions carry most of the weight.

Map branches to environments

For most WordPress teams, trunk-based with short-lived feature branches beats a heavy GitFlow setup: one long-lived main, and feature branches measured in days. Long-running branches and WordPress mix badly, because plugin and content state drifts underneath them. And because a Deployment tracks a specific branch, mapping branches to environments is just a matter of creating more than one.

Decide what belongs in Git, and what does not

This is where WordPress differs from most stacks, and where most WordPress Git setups go wrong. WordPress keeps configuration and content in a database and user uploads on disk. Neither belongs in a repository. What belongs in Git is the code you write and the dependencies you declare.

The practical consequence: point each Deployment at a specific plugin or theme folder rather than the site root. A deployment scoped to /wp-content/plugins/my-plugin cannot clobber another plugin, an upload or wp-config.php, however wrong the commit.

Split the checks between CI and a real site

Linting, PHP syntax checks, unit tests and a Composer install belong in GitHub Actions, where they are fast and need no database. Anything that needs a real WordPress, an activation hook, a migration, a block that only breaks in the editor, a theme regression, needs an actual site. That is the split the template workflow exists to serve. A persistent staging site is still worth having alongside per-PR ones, because some bugs only appear on a site with real content and history.

When staging is approved, the last hop is staging to production. The docs cover syncing changes from staging to live without overwriting live edits, which is the case Git alone does not solve because the database is involved.

How to push an existing WordPress site to GitHub

Everything so far moves code from GitHub into WordPress. The reverse is just as common: you have inherited a site whose code has never been in version control. To push a WordPress site to GitHub you pull the files down, decide what to track, commit, and push to an empty repository. The decision in the middle is the one that matters.

What to commit, and what to leave out

Do not commit a whole WordPress install. Track the code you wrote and let WordPress and Composer supply the rest.

A starting .gitignore for a site-level repository:

# secrets and environment
wp-config.php
.env

# user content
wp-content/uploads/
wp-content/upgrade/
wp-content/cache/

# build output and dependencies
node_modules/
vendor/
*.log

# editor and OS noise
.DS_Store
.idea/

If you are versioning one plugin or theme, the simpler move is to make the repository the plugin folder itself. The ignore list gets shorter and the Deployment’s destination folder maps one to one with the repo. The Plugin Handbook and Theme Handbook describe the folder structures WordPress expects.

What about the database?

It does not go in Git, and this is the most common misunderstanding of the whole workflow. Git versions code. The database holds content, settings and most plugin configuration, and it changes every time someone publishes a post.

So the workflow has two lanes that never merge. Code moves through Git in one direction, repository to site. Database and uploads move through snapshots, backups and staging sync tools in the other, live site to staging. Trying to make Git carry the database is how people overwrite a client’s content with a two-week-old copy.

The steps

1. Enable SFTP or SSH access and download the folder you want to track. The InstaWP CLI addresses sites by name if you would rather stay in the terminal (see the CLI overview).
2. Work on a copy. If the site is live, clone it or snapshot it first and pull the files from the copy, so nothing you do can touch production.
3. Add the .gitignore before the first commit. A committed wp-config.php stays in the history even after you delete it.
4. Run git init, then git add ., then git commit -m "Import existing site code".
5. Create an empty GitHub repository, then git remote add origin <url> and git push -u origin main.
6. Open the repository and confirm there is no wp-config.php, no uploads folder and no vendor directory. Ten seconds, and it catches the mistake that matters.

From here you can close the loop: register that repository as a Deployment and future changes flow back into WordPress using the four steps at the top of this guide.

Managed WordPress hosting with Git built in

What decides whether this workflow is pleasant is what sits underneath it. If the host gives you no staging environment, no shell access and nothing to restore from, a deploy pipeline only delivers code faster to a place you cannot debug.

On InstaWP managed WordPress hosting, the developer access this workflow depends on is not a higher tier. SSH, WP-CLI, SFTP, a web terminal, Git deploy and PHP version switching are on every plan. That matters more than it sounds: a post-deployment command is a shell command, and a host that gives you no shell cannot run one.

Each of those is a step your pipeline would otherwise own. Staging is where the develop branch deploys. A snapshot is your rollback. The CDN purge is a post-deploy step. Uptime and SSL monitoring is how you learn a deploy broke something before the client does. Assembling that from a cheap host plus four services is possible, and it is four more things to keep working. Full tier breakdown: managed WordPress hosting and the pricing page.

When a deployment fails

A deployment that silently does nothing is the frustrating case, because there is no error on the site to read. Start with the logs in Site Tools, then work through these.

• Permission denied (publickey) on a private repo. The InstaWP docs flag one specific cause, and it is worth knowing before you touch a working deployment: recreating a deployment mints a new SSH key pair, which invalidates the deploy key already in your GitHub settings. Pulls then stop, quietly. The fix is not to recreate it again, it is to copy the deployment’s current public key and re-add it under Settings, then Deploy keys. Both the connect to site and connect to template docs call this out, which is a fair signal of how often it happens. It is also why you edit a deployment rather than rebuild it when you only need a different branch.
• The wrong URL type. Public deployments take the HTTPS URL. Private deployments take the SSH URL and only the SSH URL. Pasting HTTPS into a private deployment gives an authentication failure that looks like a key problem but is not.
• The webhook never fired. If nothing appears in the deployment log at all, the notification never arrived. Check Recent Deliveries on the webhook in your repository settings, which shows every attempt and its response. Usual culprits: an event other than push, a content type other than application/json, or a push to a branch the Deployment does not track.
• The files arrived but nothing happened. Either the destination folder is wrong, so the code is on the server but not where WordPress looks, or a post-deployment command failed and the command log has the output. Also remember from Step 5: a plugin arriving for the first time still needs one manual activation. That is expected, not a failed deploy.

Best practices to avoid breakage

• Snapshot before you deploy. The cheapest step and the one most often skipped. Without it, a rollback is a rebuild.
• Use branches for development and testing. Test feature branches on WordPress staging sites and merge to main only after QA. Different branches can feed different sites for parallel work.
• Limit deployment scope with folder targeting. Deploy to /wp-content/themes/my-theme rather than the site root, so other plugins, uploads and configuration stay untouched.
• Automate the finishing steps. Post-deployment commands mean nothing is forgotten after a deploy. See run a command, and check your plan includes the field.
• Separate dev, staging and production. Keep production untouched until staging is signed off, then sync staging to live without overwriting live edits. Create a staging site for the develop branch.
• Trigger Actions deliberately. Fire on specific events such as pull_request: opened, keep credentials in repository secrets, and avoid deploying to production on every push.
• Never commit secrets. wp-config.php and .env go in .gitignore before the first commit. Anything committed once stays in the history.

Start with the connection, then automate

WordPress GitHub integration is not one feature, it is a connection you make once and then build on. Register the repository, attach it to a site, add the webhook, and you have version history and an undo path where you previously had an FTP client. Per-pull-request sites, branch-to-environment mapping and commands that run themselves all layer on those same four steps.

If you are still dragging plugin files into FileZilla, the first hour is the whole cost. Create a site, connect a repository, push once.

FAQs