VIP Go has built-in support for CI/CD integration. Our system allows you to use a Continuous Integration service like CircleCI to run your build processes (which may include tasks like optimizing static resources, bundling CSS and JS, using composer to fetch and install dependencies, etc.) and then deploy a built copy to your environment.
The following example describes how a production site is developed and deployed using a build and deploy flow:
- Branch from
masterfor a new feature.
- Make the necessary modifications to your source files and commit them to the branch.
- Commit any changes to your dependencies (e.g.
.gitignorethe 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
- Build (Your build steps run on the CI service).
- Deploy (Our deploy script commits and pushes the build code to the
master-builtbranch and from there it is immediately deployed to your production site).
You can find the source code for the deploy script here. We have specific instructions for CircleCI here. If you wish to use your own script or your own CI service, you are welcome to do so; the instructions below and scripts referenced are provided as a convenience only.
It is up to you and your team to develop a method to build, e.g. run
npm install, transpile, optimize, concatenate, minify, etc., your code. You should develop the method so that it can be automatically run by a script on a Continuous Integration (CI) service, without intervention from a human.
You should also ensure any versioning updates (needed for cache busting, etc.) is part of the build process or part of the commit that triggers the build. Please be sure to review our documentation on concatenating assets to fully understand the potential pitfalls of combining built assets, page caching, and concatenated JS and CSS, and adjust your 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.
master-built, you should ensure that your build process does not include development dependencies. You might also want to ensure that your CI script tests the build, and flags any issues to your team.
Pushing code to branches
Your deployable built branch should end in
-built, e.g. if your working branch is
master (for your production environment) then your built branch should be
master-built. For your develop environment your working branch should be
develop and your built and deployed branch should be
You should never push code to your build branches (e.g.
master-built). You should only ever push to your working branch (e.g.
master), which should then build the code and push a commit to your build branch.
If you are on a plan where we review your code, we will review the source code that your team writes and commits to your development (non-built) branch.
Deploying built files from
By default, files and folders referenced in your repo’s
.gitignore file will not be pushed to
master-built, including files generated by your build process.
To allow the built files to be pushed to your
built branch, you can create and use a
.deployignore file. This file acts as a replacement for all
.gitignore files in your repo. When preparing the deploy, our script removes all
.gitignore files and uses
.deployignore as the canonical, global
If you’d like to use a
.deployignore file, you should do the following:
- Make a copy of your root
.gitignorefile and name it
.deployignore. (If you don’t have one, feel free to use this one as a starting point.)
- Review any other
.gitignorefiles in your repo and make sure any relevant rules are copied over to the
.deployignorefile. You may need to update paths for these rules so that they 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.
As an example, here’s an trimmed-down
# 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. Don't need to commit it. /plugins/my-ui/dist
.deployignore file derived from that:
# 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.
Note that when you’re not using our build system, then the
.deployignore file will have no effect; referenced files and directories will still be deployed. If you want to control which files are not deployed, then you should 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
master branch, in your own CI scripting on that other build system.
Deploying files without a CI service
You may need to deploy files when your CI service is down or broken. The step that you use to build files in your CI service should be scripted, by the nature of CI tasks. You should be able to follow this process:
- Clone your repo.
- Checkout the working branch with the code you need to build (e.g.
- Run your build process (e.g.
- Create another clone of your repo, and checkout the deployment/built branch (e.g.
git checkout master-built).
- Copy changes from the development copy to the deployment copy using a tool like rsync.
- Verify your changes: they should only include built code (and not development modules and dependencies).
- Commit and push the changes the remote repository (e.g.
git push origin master-built).
- At this point, our infrastructure detects the changes and deploys them to your application.
You do not need to open a Pull Request unless you would like a quick validation review from the VIP team.