If you have (or want to have) a plugin in the WordPress.org repository but want to use GitHub for your plugin development, here are the steps you can to take to develop entirely in the GitHub environment and then deploy your code to the WordPress plugin repository without maintaining two different code bases.
This tutorial assumes you are on a Mac and we’ll use the Terminal app. Additionally, I use the Tower app but it’s not necessary. You can probably use GitHub Desktop instead. I assume you don’t already have your code on Github. However, if you do, you can probably modify this tutorial to meet your needs. Lastly, I assume you already have a plugin in the WordPress repo. If not, you can read how to do that here.
So, let’s get started with deploying your code from GitHub to WordPress!
1. Start with your plugin
I’m going to start with my WooCommerce Cloak Affiliate Links plugin.
There are 2 things to note on this page:
- First, the slug of the URL:
woocommerce-cloak-affiliate-links. We will use that in step #3. - Second, just to prove things worked, take a look at the current version on WordPress.org. It’s version 1.0.11. We will update that when we deploy from GitHub to WordPress later.
2. Create a new Repository on GitHub
Now let’s create a new repository on GitHub where we can put our plugin code.
3. Add your repository details
Here’s where we will use the slug from the WordPress.org plugin page. In our case, we will use woocommerce-cloak-affiliate-links as the Repository name.
You can add a description now or later. Set the repository to Public to make connecting to GiHub easier from the command line later on.
I like to add the README.md when the repo is initialized but that’s up to you. You can also choose the license and for WordPress plugins, that would be GPLv2 (or later).
Once all that is done and you click the Create repository button, you will have something that looks like this:
4. Add a few more details
Before we navigate away from this new repo page, let’s quickly add a bit more information about our plugin. Click the Add topics link to add tags to your plugin to make it more discoverable on GitHub and click the Edit button to add a URL for your plugin. This could be a URL to your plugin page on WordPress.org.
5. Clone our new repository
Now we are going to clone our new repository into our local WordPress installation. Here, I am using the Tower app.
The most important aspect of this step is that you clone the repository into your plugins directory (just like any other WordPress plugin).
For example, after I cloned the remote repo, I had the following path in my local WordPress site:
~/wp-content/plugins/woocommerce-cloak-affiliate-links/
6. Add your plugin files
Now that you have cloned the remote plugin repository into plugins folder of your local WordPress installation, you should only see a couple of files in that folder. For example, after I cloned my new repo, I only had the following files in my /woocommerce-cloak-affiliate-links directory:
LICENSEREADME.md
Now we have to the rest of our plugin files and directories into the directory. My plugin is fairly simple and only contains 3 .php files and 1 readme.txt file.
Here’s what my directory structure looked like after I added my plugin files to the the directory (new files have blue backgrounds):
7. Commit the new files to GitHub
Now that we’ve added the new files, Tower is showing that changes have been made and we can now commit/push these changes up to our remote repo.
Before pushing your new files up to GitHub, it’s also a good time to edit the README.md file so that the main GitHub page is easier to read. I’ve also added a link to the plugin page on WordPress.
8. Look at our new GitHub page
The main page for our new plugin repo on GitHub is coming around. We’re almost done!
9. Update our Stable tag & Version
Before we deploy our changes to WordPress we should update our Stable tag & Version. Remember in step #1 we are on version 1.0.11. Now let’s set our Stable tag & Version to 1.0.12.
10. Push up last changes to GitHub
Since we edited a few files, we need to Push those changes up to GitHub.
11. Set up the deploy script
You will want to go here and download the deploy.sh file.
12. Add username to deploy.sh file
Open the deploy.sh file and add your WordPress.org SVN username (SVNUSER).
You will be prompted for your password when you run the script.
Save your changes.
13. Add file to plugins directory
Add the deploy.sh file to your local site’s plugins directory so that it’s here:
~/wp-content/plugins/deploy.sh
14. Change file permissions
Your script might not be executable by default. So open Terminal and perform the following commands:
cd ~/wp-content/plugins/
chmod +x deploy.sh
15. Time to deploy!
Next, it’s time to deploy your code from GitHub to WordPress.org!
If you haven’t done so already, cd into your plugins directory.
cd ~/wp-content/plugins/
Then type this:
sh deploy.sh
You’ll be prompted to enter your WordPress slug. That is the same slug as in Step #1 above.
You’ll also be prompted for a commit message and your WordPress.org SVN password.
Here’s what that will look like:
16. Check WordPress.org
If your deploy.sh script ran without any errors, your changes should have been successfully pushed to the WordPress.org repo! Head over to your plugin and ensure the Version is updated.
In this case, we successfully updated our plugin and our Version is now 1.0.12.
