Written in familiar PHP, WP Yak (WPY) is a simple, but powerful deployment tool for WordPress Plugin & Theme Development
Tested only for GitHub (BitBucket & GitLab pending). Don't use yet.
Using remote git repos on GitHub, BitBucket or your own self-hosted instance of GitLab, you can automate your deployment workflow between development, staging and production servers.
Whether you're building a theme, plugin, mu-plugin or combinations of those for a client website, WP Yak will automatically deploy the latest code intended for a server, based on your configuration. Here's an example:
git branch | workflow stage | server |
---|---|---|
master | Development | https://dev.yoursite.com |
review | Code Review | - NA - |
custom | Custom Stage | https://custom.yoursite.com |
staging | Staging | https://staging.yoursite.com |
production | Live/ Production | https://yoursite.com |
- While developing in a team:
git push origin master
will deploy code tohttps://dev.yoursite.com
- Once the code is reviewed internally and is ready for client review:
git push origin staging
will deploy code tohttps://staging.yoursite.com
- Once the clients' reviewed everything and gives a go ahead for going live:
git push origin production
will deploy code on the live site,https://yoursite.com
Instead of cloning and maintaining the whole repository on servers, WP Yak tries to only deploy the code without the scm data (or the .git
directory, etc). Using git archive
, WP Yak is able to only copy the files at a particular branch or tag, without the commit history:
git archive --remote=git@github.com:your-organisation-or-username/your-plugin.git
GitHub doesn't allow git archive
, but fortunately, GitHub supports svn clients. So, we use the svn equivalent of git archive
, svn export
. See: http://stackoverflow.com/a/18324428/1589999
Of course, if you wish to maintain the whole repository on your servers, you can disable the slim deploy. To do that, set the SLIM
constant to false
in wp-yak-config/constants.php
.
This way, WP Yak will use git pull
and maintain a local copy with commit history inside the wp-yak/wpd-repos/
directory and copy over the latest code to the deploy path. This is done, instead of maintaining the repo in the actual deploy path (say wp-content/themes/your-theme
) to prevent over-writing by a manual upload. Without this, if someone uploads the theme/ plugin manually, the scm information will be overwritten and the deploy would break. With this mechanism, a manual upload will be overwritten in the next push!
Make sure that the following are installed:
git
svn
for Slim Deploys using GitHub
- Install WP Yak
- Setup schema for GitLab
- Configure repos
- Setup constants
Right now there're no automattic installation methods, you'd have to clone this repo or archive its master
branch using git
or svn
or upload the files manually.
If you're using EasyEngine, follow these steps, after logging in via ssh, clone this repository to your webroot
git clone git@github.com:Yapapaya/wp-yak.git /var/www/yoursite.com/htdocs/
(Optional)Move wdp-config
outside the web root for security, especially if you're using tokens
mv /var/www/yoursite.com/htdocs/wp-yak/wp-yak-config /var/www/yoursite.com/wp-yak-config
If your remote repository is on GitHub or BitBucket, you can skip step 1.2 and start with 1.3.
If your remote repository is on a self-hosted instance of GitLab CE, you need to set up schema for it.
vim /var/www/yoursite.com/htdocs/wp-yak-config/webhook-schema.php
or
vim /var/www/yoursite.com/wp-yak-config/webhook-schema.php
The schema for GitLab looks like this
// Payload Schema for GitLab Instance
// your Gitlab instance's domain
'git.yoursite.com' => array(
// your GitLab instance's IP range in CIDR format
// use http://www.ipaddressguide.com/cidr to get it
"ip_whitelist" => '127.0.0.0/32',
"ip_param" => 'HTTP_CF_CONNECTING_IP',
"token" => array(
"header" => 'HTTP_X_Gitlab_Token',
"hashed" => false,
),
"ref" => array(
"param" => array( 'ref' ),
"pattern" => '/^refs\/head\//',
),
"branch_name" => array(
"param" => array( 'ref' ),
"pattern" => '/^refs\/head\/(.*)$/',
),
"git_archive" => true,
),
The key for each schema is the domain name of the remote. The keys inside the schema:
ip_whitelist
A whitelisted range of IP'sip_param
The header that contains the IP of the remote. Leave it empty if your server directly talks to remote without a proxy in between. In the example above, theHTTP_CF_CONNECTING_IP
is where CloudFlare stores the webhook's original IP address.token
GitHub and GitLab (but not Bitbucket) allow you to set an additional security token that is sent as a header.header
The header that contains the security tokenhashed
GitHub hashes the security key, GitLab doesn't. Set it to false, if it isn't hashed or true, if it is.ref
Schema for the ref (branch/tag) the payload is for.param
The parameter that contains the ref informationpattern
The regex pattern to match against to know that it is a branchbranch_name
Schema for the branch name in the payloadparam
The parameter that contains the branch namepattern
The regex pattern to match against to get the branch namegit_archive
Whether the remote supportsgit archive
command. Is true for everyone except GitHub
To setup deployments with your own Gitlab instance, just change the key (to the domain name) and optionally,set the ip_whitelist
. To account for Cloudflare or similar proxies, set the ip_param
. Nothing else needs to be changed.
Open repository configuration
vim /var/www/yoursite.com/htdocs/wp-yak-config/repositories.php
or
vim /var/www/yoursite.com/wp-yak-config/repositories.php
For each of your repos, create a config item in the $config
array. There are enough examples in the file itself. Each item is intern an array with the following keys
git_url
The git url of the repo in the formatgit@github.com:your-organisation-or-username/your-theme.git
type
('theme'
,'plugin'
,'mu-plugin'
) The type of project that will be deployed.branch
The name of the branch to deploy.token
(optional) For security, gitLab & GitHub allow you to set a secret token when setting up webhooks.
Open constants file
Open repository configuration
vim /var/www/yoursite.com/htdocs/wp-yak-config/constants.php
or
vim /var/www/yoursite.com/wp-yak-config/constants.php
define( 'LOG', true );
(not implement, yet) This logs all the requests, for debugging or any other reason.
define( 'LOGFILE', '/path/to/directory' );
(not implement, yet) Log to a custom file, instead of the default.
define( 'SLIM', true);
By default, WP Yak performs slim deploys using git archive
or svn export
(for GitHub). This means that the whole repository is not maintained on the server. This can save up a lot of space and data and is similar to downloading a zip file of the specified branch or tag without the commit history (the .git
directory).
Set this to false
, if you want to or need to maintain the whole git repository on your servers.
Generate ssh key pairs on each of your servers (if not done already) and add the public key as deploy key for each of your repos.
Setup a webhook on your remote git repository. For the webhook url, if your repository is git@github.com:your-organisation-or-username/your-theme.git
, use the following format:
https://yoursite.com/wpd/wpy.php?deploy=your-theme
where the value of the deploy
parameter of the querystring is the same as the name of the repository without the .git
suffix.
Now, write code as usual and push to a branch. If the branch is mapped to a server, the code will get automatically deployed.
No cloning or other setup needed. WP Yak will automatically clone, initialise, pull, etc as needed.