Automated build and deploy on VIP Go

VIP Go platform specific

This document is for sites running on VIP Go.

Learn more

Overview #

This document covers the steps to run a deploy process for built code on the VIP Go hosting platform. This build process should only be used for CSS, JS, and static resources, not for PHP (e.g. no composer install), or SVG files. It is not necessary to configure a build and a deploy process for VIP Go, and many teams will find this process unnecessary to their development workflow.

The following example describes how a production site is developed and deployed using a flow which includes a build step and a deploy step:

  1. Branch from master for a new feature
  2. Develop cleanly with only your source code committed to your new branch (at this point you won’t commit NPM installed modules, nor transpiled code, nor compressed images, etc)
  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 (you are responsible for configuring the build process for your site)
  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)

We have specific instructions below for Travis CI or Circle CI. If you wish to use your own script, or to use your own CI service, you are welcome to do so, the instructions below and scripts referenced are provided as a convenience only.

↑ Top ↑

How is Javascript reviewed when using automated build and deploy? #

If you are on a plan where we review your code, we will review the Javascript that your team writes. We will not review the third party dependencies brought in by the build process.

You should commit all code that your team writes to your VIP Go GitHub repository, instead of including it during the build process.

In some rare cases we will review all the Javascript code for a site, including dependencies, and in this case we will ask you not to use this build and deploy process, instead committing all JS directly to your VIP Go GitHub repository.

↑ Top ↑

How do I build my 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.

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.

↑ Top ↑

What branches should I deploy built code to? #

Your deployed 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.

↑ Top ↑

Should I commit directly to my built branches? #

No. 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.

↑ Top ↑

Configuring builds on Circle CI #

It’s a good idea to read the Circle CI getting started documentation (but don’t add the suggested Circle CI config at this point).

The following instructions reference the master and master-built branch, but can be adapted for other branches, e.g. develop and develop-built.

  1. Contact VIP to have us configure Circle CI for your repository, including adding a machine user to deploy the builds.
  2. Generate a personal deploy key. This key can be generated locally, as it will be used only by CircleCI to communicate with your GitHub repository; it does not come from or communicate with our servers.
  3. Add the key to your repository under “Settings > Deploy Keys”. (This requires you have admin access to your repository.)
  4. Add the key to your CircleCI account.
  5. Create a new PR, and add or adapt a config for Circle CI:
    • If you have no Circle CI config in your repository, copy this config to .circleci/config.yml in your repo; you will need to add the build command(s) you’re using in the section under “@TODO: Configure build steps”
    • If you already have a Circle CI config, you’ll need to:
      1. Add the build command(s), referencing the section in our example config commented with “@TODO: Configure build steps”
      2. Add the two sets of two lines referenced by the “REQUIRED:” comments
    • Add the deploy key’s fingerprint to the repo’s /.circleci/config.yml file in the master branch.
  6. Once you hear back from VIP that your repository is set up for Circle CI, trigger a build by merging a PR to master, this can be a non-significant change like a code comment… it should be built by Circle CI, committed to your master-built branch, and pushed up to GitHub (verify the branch now exists on GitHub and contains the changes you made)
  7. Contact VIP again to have your environment changed to deploy from master-built
  8. …that’s it!

Note that files in the theme’s .gitignore file will not be pushed to master-branch. Any folders or files that CircleCI will build and push to master-branch should therefore not be listed in this file, nor should they be pushed to the master branch. We’re working on simplifying this process so that built assets/files can be safely ignored locally but still deployed to the master-built branch.

↑ Top ↑

Configuring builds on Travis CI #

It’s a good idea to read the Travis CI getting started documentation, but don’t add the Travis CI config at this point.

  1. Visit https://travis-ci.com, authenticate with your GitHub account, and add your repository to Travis CI
  2. Create or adapt a config for Travis CI:
    • If you have no Travis CI config in your repository, copy this config to .travis.yml in your repo; you will need to add the build command(s) you’re using in the section under “@TODO: Configure build steps”
    • If you already have a config, you’ll need to:
      1. Add the build command(s), referencing the before_script section in our example config commented with “@TODO: Configure build steps”
      2. Add the two sets of two lines referenced by the “REQUIRED:” comments
  3. Ensure you have a machine user, this is a regular GitHub user account which is used purely for scripted functions, e.g. used by Travis CI to commit and push the built code (GitHub call this user a “machine user”):
    • If you have no dedicated “machine user” account, create a new GitHub account, named appropriately.
    • If you already have a machine user for your team, then use that account for the following steps.
  4. Setup a key pair for your machine user:
    1. Use the commandline on your local machine to create a public private key pair (documentation)
    2. Set the public portion of the key pair as a deploy key with write permissions on the GitHub repository (documentation)
    3. Add the private key as a setting on your Travis repository (see “Adding a deploy key in repository settings on Travis CI” below)
  5. Merge a PR to your master branch… it should be built by Travis CI, committed to your master-built branch, and pushed up to GitHub (verify the branch now exists on GitHub and contains the changes you made)
  6. Contact VIP to have your environment changed to deploy from master-built
  7. …that’s it!

Adding a deploy key as a repository variable on Travis CI #

Please read these instructions through before executing the steps.

Add the public portion of the key as a deploy key on your GitHub repository; GitHub documentation on deploy keys.

Set the private portion of the key as a repository variable in the Travis settings. You will need to replace newlines with \n and surround it with double quotes, e.g. “THIS\nIS\A\KEY\nABC\n123\n”; Travis documentation on repository variables in settings.

You must set the “Display value in build log” toggle for the repository variable to “off”.

You must name the Travis setting that contains the key BUILT_BRANCH_DEPLOY_KEY.

↑ Top ↑

Other Notes #

↑ Top ↑

Where is the source code for the deploy script? #

You can see the source code on our Github repo Automattic/vip-go-build.

↑ Top ↑

My CI service is down or broken, how do I deploy files? #

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 the application 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. Checkout the built branch (e.g. git checkout master-built).
  5. Verify your changes; they should only include built code (and not development modules and dependencies).
  6. Commit and push the changes the remote repository (e.g. git push origin master-built).
    • Note: you do not need to open a PR, unless you would like a quick validation review from the VIP team.
  7. Once the code is pushed, the VIP Go infrastructure will detect the changes and deploy them to your application.

Ready to get started?

Drop us a note.

No matter where you are in the planning process, we’re happy to help, and we’re actual humans here on the other side of the form. 👋 We’re here to discuss your challenges and plans, evaluate your existing resources or a potential partner, or even make some initial recommendations. And, of course, we’re here to help any time you’re in the market for some robust WordPress awesomeness.