Automated build and deploy

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:

1. Branch from master for a new feature.
2. Make the necessary modifications to your source files and commit them to the branch.
3. Commit any changes to your 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 master .
5. Build (Your build steps run on the CI service).
6. Deploy (Our deploy script commits and pushes the build code to the master-built branch 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.

Building code

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 develop-built.

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.

However, 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 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 .gitignore instead.

If you’d like to use a .deployignore file, you should do the following:

1. Make a copy of your root .gitignore file and name it .deployignore. (If you don’t have one, feel free to use this one as a starting point.)
2. Review any other .gitignore files in your repo and make sure any relevant rules are copied over to the .deployignore file. You may need to update paths for these rules so that they 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.

As an example, here’s an trimmed-down .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. Don't need to commit it.
/plugins/my-ui/dist

And the .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-built or 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:

1. Clone your repo.
2. Checkout the working branch with the code you need to build (e.g. master).
3. Run your build process (e.g. npm install).
4. Create another clone of your repo, and checkout the deployment/built branch (e.g. git checkout master-built).
5. Copy changes from the development copy to the deployment copy using a tool like rsync.
6. Verify your changes: they should only include built code (and not development modules and dependencies).
7. Commit and push the changes the remote repository (e.g. git push origin master-built).
8. At this point, our infrastructure detects the changes and deploys them to your application.