Continuous integration and deployment (CI/CD)
Continuous integration and continuous deployment (CI/CD) is supported in the development workflow on the WordPress VIP Platform. Build processes can be used to optimize static resources, bundle CSS and JS, use composer to fetch and install dependencies, and other related tasks. The continuous integration services CircleCI or Travis CI can be configured to run these build processes, then to deploy a built copy to a VIP environment.
Note
Travis and CircleCI are resources shared by multiple VIP customers. Customers who use these resources should make an effort to keep their codebases lean for the benefit of themselves and others. Customers who encounter frequent delays can reach out to VIP Support to investigate if the delays are caused by an issue other than high demand for the shared resource.
It is the customer’s responsibility to develop a method to build (e.g. run npm install
), transpile, optimize, concatenate, and minify an application’s code. It should be possible for the method used to be automatically run by a script on a CI service, without intervention from a human.
Ensure that any versioning updates (needed for cache busting, etc.) are part of the build process or part of the commit that triggers the build. Review the documentation on concatenating assets to fully understand the complexities of combining built assets, page caching, and concatenated JS and CSS. Adjust asset build and deploy scripts to avoid any deploy-related issues that might affect new and immediately prior versions of asset files.
When running the build process for production, i.e. production-built
, ensure that the build process does not include development dependencies. The CI script should test the build, and flag any issues to the customer and their team.
Custom scripts and a CI service other than CircleCI and Travis CI can be used; the instructions below and scripts referenced are provided as a convenience only.
The following example describes how a production site is developed and deployed using a build and deploy flow:
- Create a branch from
production
for a new feature. - Make the necessary modifications to the source files and commit them to the branch.
- Commit any changes to the dependencies (e.g.
package.json
,package.lock
), but.gitignore
the directories and files that npm modifies (e.g./node_modules/
and anything else that gets built). - Create a pull request, get it reviewed and approved, then merge to
production
. - Build: The build steps are run on the CI service.
- Deploy: VIP’s deploy script commits and pushes the build code to the
production-built
branch, then it is immediately deployed to a production site.
Pushing code to branches
The deployable built branch should end in -built
, e.g. if a working branch is production
(for a production environment) then a built branch should be production-built
. For a develop environment, the working branch should be develop
and the built and deployed branch should be develop-built
.
Never push code to the build branches (e.g. production-built
). Code should only be pushed to a working branch (e.g. production
), which should then build the code and push a commit to the build branch.
For customers with the ability to request a VIP code review, the source code committed to the non-built branch will be reviewed.
Third-party dependencies brought in by the build process will not be reviewed (e.g. Javascript dependencies added via npm or yarn, or PHP SDKs/plugins/libraries added via Composer).
Deploying built files from .gitignore
By default, files and directories referenced in .gitignore
file in a repository will not be pushed to production-built
. This includes files generated by the build process.
To allow the built files to be pushed to a built
branch, create and use a .deployignore
file. This file acts as a replacement for all .gitignore
files in a repo. When preparing the deployment, VIP’s deploy script removes all .gitignore
files and uses .deployignore
as the canonical, global .gitignore
instead.
To use a .deployignore
file:
- Make a copy of the root
.gitignore
file and name it.deployignore
. If a.gitignore
file does not yet exist in a repository, a new one can be created based on the vip-go-skeleton.gitignore
file. - Review any other
.gitignore
files in the repo and make sure that any relevant rules are copied over to the.deployignore
file. Paths may need to be updated in order for these rules to start from the root of the repo. - Remove any rules that reference built or auto-generated files that do need to be deployed.
- (Optional) Add any rules that reference source files that do not need to be deployed.
An example of a basic .gitignore
file:
# node_modules should almost never be committed.
node_modules
# /plugins/my-ui/src is omitted here since we do want that committed for development purposes.
# This is where our built files are generated. We do not need to commit it.
/plugins/my-ui/dist
The .deployignore
file that is generated from the .gitignore
file in the example above:
# node_modules should almost never be committed.
node_modules
# Our source files don't need to be deployed.
/plugins/my-ui/src
# /plugins/my-ui/dist is omitted here since we do want it deployed.
If a customer is not using VIP’s build system, the .deployignore
file will have no effect; referenced files and directories will still be deployed. To control which files are not deployed, use the Build and Deploy functionality described on this page, or include some logic to control what gets built and what gets ignored by git (or removed) before pushing to the production-built
or production
branch, in your own CI scripting on that other build system.
Deploying built files without a CI service
Typically, the step to build files in a CI service is scripted by the nature of CI tasks. However, if for any reason a CI service is unavailable it is still possible to deploy built files.
- Clone the repository.
- Checkout the working branch with the code that needs to be built (e.g.
production
). - Run the build process (e.g.
npm install
). - Create another clone of the repository, and check out the built branch that is configured to deploy to the environment (e.g.
git checkout production-built
). - Copy changes from the development copy to the deployment copy using a tool like rsync.
- Verify the changes. They should only include built code and not development modules and dependencies.
- Commit and push the changes to the remote repository of the deployment branch (e.g.
git push origin production-built
). - VIP’s infrastructure will detect the changes and deploy the built code to the environment(s) configured to that branch.
Last updated: August 03, 2023