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.

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:

1. Create a branch from production for a new feature.
2. Make the necessary modifications to the source files and commit them to the branch.
3. 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).
4. Create a pull request, get it reviewed and approved, then merge to production .
5. Build: The build steps are run on the CI service.
6. 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:

1. 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.
2. 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.
3. Remove any rules that reference built or auto-generated files that do need to be deployed.
4. (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.

1. Clone the repository.
2. Checkout the working branch with the code that needs to be built (e.g. production).
3. Run the build process (e.g. npm install).
4. 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).
5. Copy changes from the development copy to the deployment copy using a tool like rsync.
6. Verify the changes. They should only include built code and not development modules and dependencies.
7. Commit and push the changes to the remote repository of the deployment branch (e.g. git push origin production-built).
8. VIP’s infrastructure will detect the changes and deploy the built code to the environment(s) configured to that branch.