WP DevOps is a Git-to-WebHost deployment solution for WordPress.
It allows for building, testing and deploying WordPress using CircleCI 2.0 for continuous integration from a Git provider like GitHub to Pantheon (and soon WPEngine) as web host(s).
Of course WP DevOps supports BitBucket and most any other Git provider too.
To use WP DevOps requires the following:
- Version controlled in a Git repository at GitHub, BitBucket, GitLab or some other Git provider.
- This could also mean your own custom Git provider.
- A project configured at CircleCI to enable builds whenever you push new commits to your Git repo .
- Dependency management with Composer meaning a
composer.jsonfile in the Git repo's root directory. - A
project.jsonfile in repo root containing your source code layout and info about your deployment hosts.
-
Add the following values in the included sections to your project's
composer.jsonfile:{ "repositories": [ { "type": "git", "url": "https://github.com/wplib/wp-devops" } ], "require-dev": { "wplib/wp-composer-installers": "1.2" }, "extra": { "installer-paths": { ".circleci/wp-devops": [ "type:wordpress-devops", "wplib/wp-devops" ] } }, "scripts": { "post-install-cmd": [ "php -f '.circleci/wp-devops/init.php'" ], "post-update-cmd": [ "php -f '.circleci/wp-devops/init.php'" ] } }
-
Run
composer installfrom your terminal command line in the root directory of your Git repository.composer install --ignore-platform-reqsThis will create a
.circlecidirectory containing aconfig.ymland awp-devopssubdirectory contain the scripts from this Git repository.Note:
--ignore-platform-reqsis not always needed but Composer fails if your local computer does not have all the required software to actually host your project. In our option ignoring platform requirements should have been the default option and the Composer team should have added a--require-platform-reqsswitch instead. But the Composer folks did not ask our opinion. :-)
-
Create a
.gitignorefile in your repo root and/or add the following to you existing.gitignorefile:/.circleci/circleci.token /.circleci/wp-devops /.circleci/logs/*
-
Add your project at CircleCI. You can do so at the URL that follows after you replace
ORGwith your own GitHub org slug:https://circleci.com/add-projects/gh/ORG.NOTE: We use GitHub's
ORGstructure in our example as most projects use GitHub but other Git servers may use a different structure and so you will need to determine how CircleCI's URLs relate if you do not host your projects on GitHub. Or just use CircleCI's menus to navigate to the right place.
-
Add a user key that has permissions to write to your Git repository. You can do so at the URL that follows after you replace
ORG/REPOwith your own Git URL path:https://circleci.com/gh/ORG/REPO/edit#checkout.NOTE: We use GitHub's
ORG/REPOstructure in our example as most projects use GitHub but other Git servers may use a different structure and so you will need to determine how CircleCI's URLs relate if you do not host your projects on GitHub. Or just use CircleCI's menus to navigate to the right place.
-
Create a text file named
circleci.tokenin your.circlecidirectory contain your own personal token which you can create at circleci.com/account/api
-
Create an SSH key. GitHub has a great simple guide for how to create an SSH key.
NOTE: We generally use something like
circleci-pantheon-PROJECT_NAME-your@email.addresswhenssh-keygenasks for a name so we can use for this use only and not have to update other all services where we used one SSH key, assuming we ever a security issue with our private key.NOTE: However, using a unique name may require you to update your
~/.ssh/configfile and provide special configurations for it. Doing that is beyond the scope of these instructions, though.
-
Add the private file of the SSH key you just created to CircleCI. You can do so at the URL that follows after you replace
ORG/REPOwith your own Git URL path:https://circleci.com/gh/wplib/wp-devops/edit#ssh.NOTE: We use GitHub's
ORG/REPOstructure in our example as most projects use GitHub but other Git servers may use a different structure and so you will need to determine how CircleCI's URLs relate if you do not host your projects on GitHub. Or just use CircleCI's menus to navigate to the right place.NOTE: The private key is the file without an extension whereas the public key has an extension of
.pub.NOTE: CircleCI needs the private key since it will need to act as a client to Pantheon's SSH server.
-
Add the public version of your SSH key to the Pantheon dashboard:
-
Create a
project.jsonor add to an existing one in your repo root and add the following, modifying it for your specific use-case:{ "source": { "frameworks": { "wordpress": { "root_path": "/www", "core_path": "/www/wp", "content_path": "/www/content", "vendor_path": "/www/vendor" } }, "repository": { "provider": "github", "url": "ssh://git@github.com:ORG/REPO.git" } }, "deploy": { "provider": "pantheon", "site_id": "SITE_ID", "site_id:where_found": "SITE_ID is found in Pantheon dashboard URL for a site: https://dashboard.pantheon.io/sites/SITE_ID#dev/code", "site_name": "SITE_NAME", "site_name:where_found": "SITE_NAME is found in a Pantheon site's URL: http://dev-SITE_NAME.pantheonsites.io", "frameworks": { "wp_devops": { "ref_type": "tag", "tag": "0.2.0" }, "wordpress": { "root_path": "/", "core_path": "/", "content_path": "/wp-content", "vendor_path": "/vendor" } }, "files": { "exclude": [ "/index.php", "/wp-config.php", "/wp-config-wplib.box.php", "composer.json" ], "delete": [ "/readme.html", "/license.txt", "/wp-config-sample.php", "/wp-content/plugins/hello.php", "/wp-content/themes/twentyseventeen/*", "/wp-content/themes/twentyseventeen" ], "keep": [ "/wp-content/mu-plugins/pantheon.php", "/wp-content/mu-plugins/pantheon", "/wp-content/mu-plugins/index.php", "/wp-content/plugins/index.php", "/wp-content/themes/index.php", "/wp-content/index.php", "/wp-config-deploy.php" ] }, "hosts": { "develop": { "branch": "develop" }, "testing": { "branch": "master" }, "staging": { "branch": "master", "after": "deploy_dev_to_test" }, "production": { "branch": "master", "after": "deploy_test_to_live", "files": { "delete": [ "/wp-config-local.php" ] } } } }, "hosts": { "production": { "provider": "pantheon", "name": "live", "label": "Staging (Pantheon's 'LIVE')", "repository": { "url": "git clone ssh://codeserver.dev.SITE_ID@codeserver.dev.SITE_ID.drush.in:2222/~/repository.git", "url:where_found": "GIT SSH clone URL from [Connection Info] button at top right in site's dashboard." } }, "staging": { "provider": "pantheon", "name": "test", "label": "Staging (Pantheon's 'TEST')", "repository": { "url": "git clone ssh://codeserver.dev.SITE_ID@codeserver.dev.SITE_ID.drush.in:2222/~/repository.git", "url:where_found": "GIT SSH clone URL: For Pantheon, this is the same URL from production above, for all hosts." } }, "testing": { "provider": "pantheon", "name": "dev", "label": "Testing (Pantheon's 'DEV')", "repository": { "url": "git clone ssh://codeserver.dev.SITE_ID@codeserver.dev.SITE_ID.drush.in:2222/~/repository.git", "url:where_found": "GIT SSH clone URL: For Pantheon, this is the same URL from staging above, for all hosts." } }, "develop": { "provider": "pantheon", "name": "develop", "label": "Developer testing - Requires Multidev and is available for agencies and larger accounts", "repository": { "url": "git clone ssh://codeserver.dev.SITE_ID@codeserver.dev.SITE_ID.drush.in:2222/~/repository.git", "url:where_found": "GIT SSH clone URL: For Pantheon, this is the same URL from testing above, for all hosts." } }, } }
-
The last step should be to commit your changes and push, which should trigger a rebuild on CircleCI. You can find status on your builds at
https://circleci.com/gh/ORG/REPO.
Any questions? Just ask on Slack.
Our vision is to make the best practices of setting up and running continuous integration, testing and deployment brain-dead easy. More to come on how we will make this happen in the near future...
We plan to expand WP DevOps to support as many Continuous Integration Providers as possible and to support as many Web Hosts as possible. Along those lines we'll be adding documentation as we evolve this solution. If you have an interest in helping us or contributing financially to have us add specific support sooner, please contact us via our Slack.
Copyright 2018 NewClarity Consulting, LLC
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.