Why and how to use GitHub for WordPress development

How to setup GitHub for WordPress

WordPress development seems like an easy task until you reach a point when you have multiple pages, different features and lots of other important things going on. At that point, you need several developers working on a project, so you can add more functionalities to keep engaging your users and providing them with resonating information. All this teamwork will require collaboration on the same codebase, reviewing the work done and keeping track of the changes.

GitHub comes to the rescue, offering a wide range of ready solutions for collaboration and versioning for WordPress projects.

I’ll walk you through all the steps on how to use GitHub for WordPress so you can streamline your development process.

What is GitHub used for? 

Git allows you to modify code while keeping the history of all changes on your computer. GitHub, on the other hand, is a “hub” for your repositories online.

You can use GitHub to:

  • Safeguard your code modifications so you can always revert to some point or find out why some changes were made.
  • Merge code done by multiple developers. If you work in a team, GitHub will help you organize your work and not override other developers’ work while you modify the same files.
  • Have different “branches” of development — like having different versions of the same product. You may have a “develop” branch for the features that you’re currently working on and a “main” branch for already tested features that are deployed to production. We’ll get into more detail about branching later.

Store all your code in a remote location. For me, that’s the best thing about GitHub. You can safely collaborate on your solution with other team members and be sure that your work is stored in a reliable place and accessible worldwide.

Why you should use GitHub with WordPress

WordPress development mostly consists of two parts: themes and plugins.

  • Themes give you the ability to control how your website presents the content to the users and have extra features during content creation.
  • Plugins have additional capabilities and can be reused across multiple themes and projects.

To put it simply, themes are project-specific configurations and plugins are WordPress-wide functionalities that are not tied to a specific theme or project.

And for both types of WordPress development, we need to store code and keep it up to date. So a WordPress-GitHub integration is a great way of achieving these goals.

Additionally, GitHub has capabilities to automatically deploy any changes in your repository to a web server using GitHub Actions, which will help to speed up the development process and make it more reliable.

How to set up GitHub for WordPress: Step-by-step

Follow these steps to achieve the most reliable results. If you already have a GitHub account or some of the steps were done before, just skip them and move to the next ones.

1. Create a GitHub repository

1.1. Go to https://github.com.

GitHub home page

1.2. Click on “Sign up” in the top right corner.

“Sign up” button in the top right corner of GitHub website

1.3. Fill in your email address and create a secure password.

1.4. After an account is created, you’ll receive a confirmation email from GitHub with a launch code. Just copy and paste it into the corresponding field to confirm your email.

1.5. Click on “Skip personalization” if you don’t want Github to know more about you or your company. It doesn’t affect any of the website functionality and is mostly intended for other users to be able to see information about you.

“Skip personalization” link at the bottom of GitHub page

1.6. That’s it with the account. Once you are in, click on the “Create repository” button from the left sidebar.

“Create repository” button in the sidebar in GitHub
1.7. On the next screen, provide a repository name. Make sure that the “Private” option is selected. Other options can be left as they are. Then press on “Create repository.”

Important fields to fill in while creating a GitHub repository

1.8. To enable the ability to communicate with GitHub from your local computer, clone the repository or push changes, you need to configure an SSH key in the GitHub settings. Go to your profile. Click on the avatar in the top right corner, then click on “Settings.”

“Settings” navigation link in the sidebar of GitHub repository

1.9. Next, proceed to “SSH and GPG keys” and click on “New SSH key.”

“New SSH key” button in the GitHub repository settings

1.10. Add your public SSH key to the next screen. You can choose any “Title” but it’s preferable if you have your computer name as “Title”.

1.11. Leave “Key type” as “Authentication key”. If you can’t find your SSH key, most likely you don’t have it generated in your local machine. Proceed with this tutorial on how to create an SSH key.

2. Publish the project files to the repository

I recommend adding only your theme — and not your entire project — to the repository. This way, you don’t need to worry about WordPress updates.

Here’s how.

2.1. Switch your working directory to your theme in Console/Terminal.

cd path/to/your/theme

2.2. Open your repository page on GitHub. Follow the instructions that GitHub suggests on that page. Don’t forget to use SSH.

Step by step instructions to set up a Git repository on your computer

2.3. Now you have all your theme files in the Github repository. Keep working on the project and regularly commit and push your changes. My recommendation is that you should push your code daily.

3. Set up GitHub Actions to automate workflows

GitHub Actions — an automation tool provided by GitHub — allows developers to automate their software workflows directly within their GitHub repositories. It means you can do some extra work on your code when it gets into the repository. It could be code verification, dependency management and many other things.

One of the most useful features of GitHub Actions is auto-deployment. If you set it up, then every time a new code is pushed to the GitHub repository, it gets automatically published into your WordPress hosting. To configure it, you need to add a folder “.github/workflows” to your project and create .yml files inside.

Here is a sample file to start with. The name doesn’t matter, but we just choose to name files based on the environment where the code should be deployed.

dev.yml
name: Deploy to staging
on:
workflow_dispatch:
push:
branches:
- develop

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Use the GITHUB_WORKSPACE environment variable
run: ls -la "${GITHUB_WORKSPACE}"

- name: Set up Node.js
uses: actions/setup-node@v3
with:
node-version: ${{ env.NODE_VERSION }}
cache: 'npm'

- name: yarn, build
run: |
yarn
yarn build

- name: Check if composer.json exists
id: check_files
uses: andstor/file-existence-action@v2
with:
files: 'composer.json'

- name: Get Composer Cache Directory
id: composer-cache
if: steps.check_files.outputs.files_exists == 'true'
run: |
echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT

- name: Set up dependency caching for faster installs
uses: actions/cache@v3
if: steps.check_files.outputs.files_exists == 'true'
with:
path: ${{ steps.composer-cache.outputs.dir }}
key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
restore-keys: |
${{ runner.os }}-composer-

- name: Run composer install if composer.json exists
if: steps.check_files.outputs.files_exists == 'true'
run: composer validate --no-check-publish && composer install --prefer-dist --no-progress

- name: Archive Release
uses: thedoctor0/[email protected]
with:
type: 'zip'
filename: 'release.zip'
exclusions: '*.git* /*node_modules/* .editorconfig'

- name: Upload artifact for deployment job
uses: actions/upload-artifact@v3
with:
name: release
path: ./release.zip

deploy:
runs-on: ubuntu-latest
needs: build
environment: stage
env:
DEPLOY_TEMP_DIR: /tmp/${{ github.repository }}-${{ github.run_id }}/

steps:
- name: Download artifact from build job
uses: actions/download-artifact@v3
with:
name: release

- name: List downloaded files
run: ls -la

- name: Output deployment temp directory
run: echo "Deployment temp directory $DEPLOY_TEMP_DIR"

- name: Output target path
run: echo "Deployment target path ${{ vars.TARGET_PATH }}"

- name: Copy file via SCP
uses: appleboy/[email protected]
with:
host: ${{ secrets.SSH_HOST }}
port: ${{ secrets.SSH_PORT }}
username: ${{ secrets.SSH_USER }}
password: ${{ secrets.SSH_PASS }}
source: release.zip
target: ${{ env.DEPLOY_TEMP_DIR }}

- name: ssh-job
uses: nekiro/[email protected]
with:
host: ${{ secrets.SSH_HOST }}
port: ${{ secrets.SSH_PORT }}
user: ${{ secrets.SSH_USER }}
password: ${{ secrets.SSH_PASS }}
command: |
ls -la ${{ env.DEPLOY_TEMP_DIR }}
rm -rf ${{ vars.TARGET_PATH }}
unzip -o ${{ env.DEPLOY_TEMP_DIR }}/release.zip -d ${{ vars.TARGET_PATH }}
rm -rf ${{ env.DEPLOY_TEMP_DIR }}

In this file, you will find several key components:

  1. When to start the deployment. At the beginning, there is the “on:” keyword and after that “push: branches: – develop” — meaning that, when anything is pushed to the “develop” branch, then this script should run.
  2. What to do during deployment. Everything under the “jobs: build:” keyword. Most of the instructions can be reused between any projects as they basically tell GitHub to set up Nodejs and Composer, install dependencies and other things. Pay attention to the part with a name: “yarn, build” because it’s the place where you list your project-specific build steps. Here is just “yarn” to install dependencies and “yarn build” to run assets building.
  3. How to publish the code. The job with the name “jobs: deploy:” is where you’ll find steps instructing how to connect to your hosting and where to copy files. Since this process most likely requires a secure connection to your hosting, all of the credentials are specified through placeholders such as ${{ secrets.SSH_KEY }} .

The secrets for your deployment are configured in “Settings” -> “Secrets and variables” -> “Actions.”

How to access the “Secrets and variables” page from the GitHub sidebar

The next step is to click on “New repository secret” and add the same name that you have in your configuration file (placeholders that we have in dev.yml”).

Keep all your secrets only there and never add them to your GitHub repository directly. Even if you commit a file and then remove it, it is still available in Git history, so your sensitive information can be discovered later.

You have now added an auto-deployment to your Development hosting. If you have Staging and other environments, just have different configuration files for them (staging.yml, prod.yml) and specify which branch you want to deploy changes from.

You can always deploy any branch to your hosting just by triggering deployment manually, thanks to “workflow_dispatch” settings under “on:” section. In order to run the deployment:

  • Go to “Actions,” select your workflow and click on “Run workflow.”
  • Select your branch and click on “Run.” This way, you can deploy your specific branch to the Development server for testing — without a need to merge with the “develop” branch. Sometimes it’s handy to have such an ability.

How to run deployment manually in GitHub Actions

I recommend exploring GitHub Actions in more detail. There is a big library of ready configurations for different types of technologies and tasks. The more you automate, the less you need to do it by yourself and fewer errors you will find along the way.

Now you’ve set up your GitHub repository for WordPress, learn how to make the most of it.

GitHub best practices for WordPress and any type of coding project 

The following best practices are useful for WordPress projects of any size and shape. Most of the tips are universal so can be applied to any type of project that involves coding, such as development using a headless CMS.

These are my favorite best practices for using GitHub:

  • Avoid merge conflicts
  • Push code regularly
  • Establish a code review process

And here’s how to implement them.

1. How to avoid merge conflicts in GitHub

Meme on a merge conflict in GitHub

A merge conflict happens when you want to merge changes from a repository, but the local files that you are working on were already modified by someone else. Most of the conflicts happen when you change one line of code but the same line was already modified by your colleague.

When Git has a hard time understanding which changes are more important and how to combine them together, it suggests you resolve them manually. And this sometimes requires a significant amount of time and effort. The best strategy is to avoid merging conflicts altogether.

These are my favorite steps to avoid merge conflicts in GitHub:

  1. Do not work on the same page or module at the same time as your teammates. Tell everyone that you’ll start working on a certain functionality and ask them not to modify it.
  2. Before starting any work, pull all new changes from the repository. Probably your teammates have already finished their work and you can safely continue modifying the same module, but don’t forget to bring their changes into your branch.
  3. Don’t change irrelevant functionalities. Sometimes it’s very tempting to do a small code refactor while you’re working on one piece of code just because you have noticed a problem in a different section. Don’t do it, as there is a high chance that someone else is working on it. At least ask if that’s ok if you change it.
  4. Split your code into small files. Having a few hundred lines of code is more than enough for most of the functionality. This way, you reduce the chances of modifying the same files that your colleagues are working on.

2. How to establish a code push practice

You should push your code regularly to a repository. Ideally every day. Here’s why:

  • Getting your code into a repository puts it in a safe place. In case of a hardware or software malfunction, you can always recover your work.
  • Your team can see the progress of a task in a transparent manner.
  • You’ll have to split the work into reasonable chunks that can be finished, committed and then pushed within the same day. This is a great approach to the software development process because it allows us to gradually develop any functionality.

The biggest blocker to the regular code push practice is that most developers don’t feel comfortable pushing not fully finished code into a repository. It’s like revealing an unfinished work of art to the world. To reduce unnecessary attention to what is still a work in progress, I recommend creating a separate branch for every task in progress. This way, each developer can have a separate space that no one else is looking at regularly, but still leveraging the benefits of a repository.

3. How to establish a code review practice

A code review is a process of manually checking someone’s code by a lead developer or other teammates. The goals are to:

  • Ensure that best practices are followed in the code.
  • Enforce the company’s coding standards.
  • Learn any new functionality that is being implemented.
  • Report bugs at an early stage of the development process.

It is very important to have a code review before the code is merged into a development branch. It prevents other developers from starting to use non-reviewed code. Also, some bugs may affect other parts of the project and cause more bugs and other side effects.

The easiest way to establish code review is to adopt a GitFlow-like naming convention for your branches. Every project should have “main” and “develop” branches.

  • “Main” contains a production-ready code
  • “Develop” has a work-in-progress that is being continuously developed and tested
  • Every new feature should have its own branch with a name like “feature/<name-of-feature>”

The review process starts with completing a solution inside the “feature/<name-of-feature>” branch. Then in order to get the code from this branch to be merged with the “develop” branch, you need to pass a code review. On GitHub, this process is called “Pull Request”, which literally means “Take my code if you like it.”

To make a pull request (in short, PR), push your branch to a repository and go to the “Pull requests” page. If you recently pushed your branch, then GitHub will most likely show it at the top of the page.

“Compare & pull request” button after a new branch is pushed in GitHub

In this case, click on “Compare & pull request.” Otherwise, press “New pull request” and manually select your branch and where you want to merge it.

Comparing changes before creating a pull request in GitHub

Either way, you end up on a page to create a pull request.

Open a pull request page in GitHub

While you’re creating a PR, keep in mind:

  • The PR title is usually auto-filled from your last commit message. Change it if it doesn’t show what your PR is about. I recommend having the name of the task as a title.
  • In the description, you can briefly list features that were implemented or some other information. GitHub has the ability to configure custom templates that will be used for every PR, which will allow you to set company-wide standards for PRs.
  • Below the description, there is a list of all files that were modified. It’s the last chance to make sure you didn’t commit anything by mistake.

Click on “Create pull request”. After that, your PR is created. Next, you can:

  • Copy the URL and share it with your teammate who is going to perform the code review.
  • Assign the code review to someone through the “Assignee” sidebar.

Assigning a code reviewer in GitHub

The code review process itself contains several steps. A code reviewer goes over every file that was modified and checks if the changes are correct. If something is not, the reviewer should leave a comment explaining what is wrong.

Leaving a comment during a code review process in a GitHub repository

After the first comment is ready, you need to click on “Start a review.” That initiates the review process. All further comments will be added to this review.

Process of finishing your review in GitHub

  • After you’re done with your review, press “Finish your review” and choose if you Approve or Request changes.
  • Then “Submit review.”
  • After that, your colleague will see all the comments and can either fix the issues or start discussing the required changes.
  • At the end of this process, when everything is finalized, go through the review process one more time and select “Approve” after review.
  • The last step is to actually merge the PR.

Merging of a pull request in GitHub

Let’s help you with your WordPress and GitHub needs

Our team has developed SEO-ready WordPress websites using GitHub for many years. For every project, we use our well-tested GitHub configuration, which speeds up the development process while allowing us to create solutions with the best quality. We can work with an existing GitHub configuration or improve it according to our internal standards.

Ready to leverage the benefits of using GitHub for WordPress development? Explore our web development services — or drop us a message to book a consultation now.

Anton I

Anton Iakushyn

Anton Iakushyn is a Web Services Lead at Productive Shop. He has a deep knowledge of programming technologies such as PHP, JavaScript, WordPress, Next, React, Angular and many other platforms required for successful web development. His priority is always the quality of the solutions that he creates with his team. Having more than 15 years of experience, Anton understands the core ideas behind every aspect of web development. Prior to Productive Shop, he was leading multiple teams developing projects for startups in industries such as finance, banking, entertainment and even AI. Anton graduated with a university degree in aerospace engineering so he has a passion for exploration and the ability to handle great challenges. When he’s not at work, Anton enjoys hiking, fishing, BBQing and traveling. He also likes to try new activities such as yachting — and once, he even piloted a small plane!

Get the latest blog updates from Productive Shop! Subscribe to our blog:

    Top