Developer · Guide
How to Deploy WordPress With GitHub Actions
Short answer
To deploy WordPress with GitHub Actions, push your theme or plugin code to your main branch and let a workflow file copy those files to your server over SSH. Store the SSH key and server address as GitHub secrets, protect production with an environment, and test the same workflow on staging first. Then check the live site and the workflow run log.
Key takeaways
- GitHub Actions runs a workflow file from .github/workflows when you push code or trigger it by hand.
- Deploy only your own theme or plugin code, and keep WordPress core, uploads, the database and wp-config.php out of Git.
- Store the SSH private key as an environment secret, never in a file that Git tracks.
- A production environment can require approval from a reviewer before a job runs.
- On the GitHub Free plan, private repositories include 2,000 Actions minutes per month as of November 2026.
What does deploying WordPress with GitHub Actions mean?
Deploying WordPress with GitHub Actions means a workflow file copies your code to your server each time you push a change.
GitHub Actions is the automation system built into GitHub. A workflow is a YAML file that lists jobs, and each job runs steps on a runner, which is a machine that runs your commands.
This guide covers code deploys only. Your posts, pages, settings and users live in the database, so a file copy does not move them. Media files in the uploads folder also stay on the server.
What do you need before you start?
You need a GitHub repository, SSH access to your server, and a backup of the live site before your first deploy.
Your host must allow SSH access and rsync, or an SSH-based deploy action. If your host only offers SFTP or a file manager, this method will not work, so check the host docs first.
You also need a staging site if you can set one up. A staging site is a private copy of your site where you test changes before they reach visitors. Deploy there first, then repeat the same steps for production.
Before you touch the workflow, back up both parts of the site. Our guide to how to back up WordPress explains the file and database steps in order.
What should you put in Git, and what should you leave out?
Put only your own theme or plugin code in Git, and leave WordPress core, uploads, the database and secrets out.
WordPress core files, third-party plugins and themes can be reinstalled from their source, so tracking them adds churn to every update. Uploads grow with every image an editor adds, and they belong in a backup, not in a code repository.
Never commit wp-config.php or a .env file. Those files hold database passwords and secret keys, and a secret that reaches Git history stays there even if a later commit deletes the file.
Use a .gitignore file at the root of the repository:
wp-config.php
wp-content/uploads/
wp-content/cache/
node_modules/
vendor/
.env
Run git status before your first commit. If you see wp-config.php, wp-admin/ or thousands of core files, fix the ignore rules first.
How do you store SSH keys and server details safely?
Store the SSH private key and server address as GitHub secrets, and store the server address as a plain variable, not as a secret.
GitHub Docs explains that secrets are encrypted values you can store at repository, environment or organisation level, and that environment secrets reach only jobs that name that environment. Open your repository, then go to “Settings”, then “Secrets and variables”, then “Actions” to add them.
GitHub Docs also gives hard limits for secrets, checked in November 2026: you can store up to 100 repository secrets, 100 environment secrets and 1,000 organisation secrets, and each secret is limited to 48 KB in size. GitHub secrets limits
Secrets are not passed to workflows triggered by a pull request from a fork, according to the same GitHub Docs page. That rule stops a fork from reading your deploy key.
Create one SSH key pair for deploys only, with ssh-keygen -t ed25519, and add the public key to the server user that owns the site files. Keep the private key out of the repository and out of chat messages.
How do you write the deploy workflow file?
Write one YAML file in .github/workflows/deploy.yml that checks out the code, then copies it to the server with rsync over SSH.
GitHub Docs states that workflow files use YAML syntax, must end in .yml or .yaml, and must live in the .github/workflows directory of your repository. Workflow syntax for GitHub Actions
The workflow below deploys one theme folder. Change the theme name, host, user and path to match your site, and add a second workflow or job for a plugin if you deploy one.
name: Deploy theme
on:
push:
branches: [main]
workflow_dispatch:
concurrency:
group: deploy-production
cancel-in-progress: false
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
timeout-minutes: 30
steps:
- uses: actions/checkout@v4
- name: Deploy with rsync
env:
SSH_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
SSH_HOST: ${{ vars.SSH_HOST }}
SSH_USER: ${{ vars.SSH_USER }}
DEPLOY_PATH: ${{ vars.DEPLOY_PATH }}
run: |
mkdir -p ~/.ssh
echo "$SSH_KEY" > ~/.ssh/deploy_key
chmod 600 ~/.ssh/deploy_key
ssh-keyscan -H "$SSH_HOST" >> ~/.ssh/known_hosts
rsync -az --delete wp-content/themes/my-theme/ "$SSH_USER@$SSH_HOST:$DEPLOY_PATH/"
The actions/checkout action checks out your repository under $GITHUB_WORKSPACE so the job can read it, and it fetches only a single commit by default. Checkout action
Set concurrency so two deploys never run at the same time. GitHub Docs notes that the concurrency key keeps only one job or workflow in the same group running at a time. Workflow syntax for GitHub Actions
How do you deploy to staging first, then production?
Deploy to staging on every push to a staging branch, and deploy to production only after a reviewer approves the matching job.
Create two environments in your repository: go to “Settings”, then “Environments”, then “New environment”, and name one staging and one production. GitHub Docs notes that an environment name may not exceed 255 characters and is not case sensitive. Managing environments for deployment
Add required reviewers to the production environment only. GitHub Docs states that you can list up to 6 people or teams, and only one of them needs to approve the job for it to proceed. Managing environments for deployment
A job that names an environment must pass its protection rules before it runs or reads the environment secrets, according to the same GitHub Docs page. That is why the SSH key for production belongs in the production environment, not in a repository secret.
| Target | Trigger | Approval | Secrets |
|---|---|---|---|
| Staging | Push to the staging branch | None | Staging environment secrets |
| Production | Push to main, or manual run | 1 required reviewer | Production environment secrets |
| Rollback | Manual run of the last good commit | 1 required reviewer | Production environment secrets |
If you manage several sites, the same staging-first habit scales. See how to manage multiple WordPress sites for a single-dashboard routine.
How long does a deploy take, and what does it cost?
A small theme deploy usually takes 1 to 3 minutes, and it costs nothing extra on a public repository or inside your free minutes on a private one.
GitHub Docs states that Actions use is free for public repositories on standard GitHub-hosted runners and for self-hosted runners. GitHub Actions billing
For private repositories, the same GitHub Docs billing page lists 2,000 minutes per month on the GitHub Free plan, 3,000 minutes on GitHub Pro, and 50,000 minutes on GitHub Enterprise Cloud, as of November 2026. GitHub Actions billing
GitHub Docs also lists the hard time limits, checked in November 2026: a job on a GitHub-hosted runner can run for up to 6 hours, a job on a self-hosted runner for up to 5 days, and a whole workflow run for up to 35 days. GitHub Actions limits
A deploy that takes longer than a few minutes usually means the rsync step is copying too much. Check that uploads, cache and node_modules are ignored, and that the rsync source path points at one theme or plugin folder.
How do you check that the deploy worked?
Check the workflow run log, then load the live site and confirm the change you shipped is visible.
Open the “Actions” tab in your repository, open the run, and read each step. A green check mark means the job finished, and a red mark means a step failed. Click the failed step to read the exact error line.
Then check the site itself. Load the changed page in a private browser window, and clear any page cache first so you see the new files. If your host or plugin caches pages, flush that cache after the deploy.
On the server, you can also confirm the files and the WordPress version with WP-CLI. The Make WordPress Hosting handbook lists wp core version, wp core verify-checksums and wp plugin list as checks you can run without opening the admin area. WP-CLI handbook
If the deploy changed code that affects speed, run a fresh speed check after the cache is warm. See how to speed up WordPress for what to measure next.
What should you do when a deploy fails?
Read the failed step in the run log first, fix that one cause, and re-run the workflow from the same commit.
Common causes fall into a few groups. Work through them in this order, and change only one thing between re-runs so you know what fixed it.
- The workflow file has a YAML error. GitHub shows the error before any job runs, so fix the indent or the missing colon and push again.
- The checkout step is missing. Without it, the runner has no files to copy, so add
actions/checkout@v4as the first step. - SSH fails. Check the host, user and key, and confirm the public key is on the server for the right user.
- The path is wrong. Compare the rsync destination with the real theme path on the server, letter by letter.
- The job timed out. GitHub Docs notes that a workflow run can wait up to 30 days for an environment approval, so a long wait usually means a reviewer has not approved it yet. GitHub Actions limits
If a bad deploy reaches production, re-run the workflow from the last good commit. That copies the old files back, which is why every deploy should come from a commit you can name.
If the failure is on the server side, your host can tell you whether SSH or disk space is the cause. Pick a host with SSH and WP-CLI support before you build this pipeline; see how to choose WordPress hosting for the questions to ask.
What does the server need to run the deployed code?
The server must meet the WordPress version your code was written for, or the new files may fail after a clean deploy.
WordPress.org recommends PHP 8.3 or greater, MariaDB 10.11 or greater or MySQL 8.4 or greater, and HTTPS support, as of November 2026. WordPress requirements
WordPress still runs on PHP 7.4 and MySQL 5.5.5 in legacy setups, but WordPress.org warns those versions have reached end of life and may expose a site to security problems. WordPress requirements
After a deploy that updates WordPress core, plugins or themes, run the database upgrade step.
The Make WordPress Hosting handbook lists wp core update, wp core update-db, wp plugin update --all and wp theme update --all as the update commands. It warns you to back up first because some commands cannot be undone. WP-CLI handbook
The full command list lives in the WP-CLI reference, which lists every wp subcommand with its options. WP-CLI commands
What mistakes should you avoid?
Avoid deploying from an unreviewed branch, committing secrets, and pointing rsync at the whole site root.
Never put a private key, password or token in a workflow file, a commit message or a log line. Secrets stay in GitHub secrets, and the workflow reads them only through the ${{ secrets.NAME }} syntax.
Never use rsync --delete against the WordPress root or the uploads folder. That flag deletes files on the server that are not in the repository, so a wrong path can wipe live media or core files in seconds.
Do not trigger production deploys from every push to every branch. Limit the production workflow to main or to tags, and use pull request checks for the rest.
Do not skip the staging run because the change looks small. Small changes break sites too, and a staging run costs a few minutes while a broken production site costs far more.
Frequently asked questions
Can GitHub Actions deploy the WordPress database too?
No, not with a file copy. Your posts, pages, settings and users live in the database, and rsync only moves files. Move database changes by hand, with a migration plugin, or with WP-CLI commands on the server, and always back up the database before you change it.
Do I need a paid GitHub plan to deploy WordPress?
No, not for a small site. Actions are free on public repositories with standard runners, and the Free plan includes 2,000 minutes per month for private repositories as of November 2026. A short theme deploy uses only a few minutes, so most single sites stay inside the free amount.
Is it safe to store an SSH key in GitHub Actions?
Yes, if you store it as an environment secret and limit it to one server user. GitHub encrypts secrets and only gives them to jobs that name the right environment. Use a dedicated deploy key, never your personal SSH key, and replace it if it ever leaks.
What happens if two people push at the same time?
Without a concurrency group, both deploys can run at once and overwrite each other in any order. Set a concurrency group on the deploy job so only one deploy runs at a time. The second run then waits its turn instead of fighting the first one.
Can I roll back a bad deploy with GitHub Actions?
Yes. Find the last good commit, then run the workflow from that commit, either by pushing a revert or by running the workflow manually against it. The rsync step copies the old files back over the bad ones. Keep the deploy history so you always know which commit is live.
Does this work on shared hosting?
It works only if the host gives you SSH access and lets you run rsync. Many shared hosts do not offer SSH, or they limit it to certain plans. Check the host docs for SSH and rsync support before you build the workflow, and pick a plan that includes them if yours does not.
Sources
- Workflow syntax for GitHub Actions GitHub Docs
- Managing environments for deployment GitHub Docs
- Secrets reference GitHub Docs
- Actions limits GitHub Docs
- About billing for GitHub Actions GitHub Docs
- Requirements WordPress.org
- WP-CLI Make WordPress Hosting
- Checkout v4 GitHub
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
