Custom Deployment with VIP-CLI
Code that was developed in a repository other than an application’s wpcomvip GitHub repository can be deployed with VIP-CLI to a VIP Platform environment that has Custom Deployment enabled.
Prerequisites
- VIP-CLI is installed and has been updated to the most current version.
- A user must have at minimum either an Org admin role or an App admin role for that application.
- The target environment for the code deployment has the Custom Deployment feature enabled.
- A Custom Deployment token has been generated and its value is immediately accessible.
Validate the archived file
VIP-CLI command examples
For demonstration purposes, the <app-name> value example-app and the <env> value develop are used in the VIP-CLI command examples below. Read more about how to target environments in VIP-CLI commands.
VIP-CLI command: vip app deploy validate
Before performing a Custom Deployment, use the vip app deploy validate VIP-CLI command to scan the contents of a prepared archived file. The validation command ensures that the contents of the archived file are formatted according to the required structure of the VIP WordPress skeleton.
An archived file should not be deployed to a VIP Platform environment until the vip app deploy validate command can successfully run with no reported issues.
In this example command and output, the vip app deploy validate command is run against an archived file named codebase.zip on the user’s local machine and no errors are found:
$ vip app deploy validate codebase.zip
✓ Compressed file has been successfully validated with no errors!This example command and output demonstrate the informative error message that will be returned if issues are found within the directory structure of the archived file:
$ vip app deploy validate codebase.zip
Error: Missing `themes` directory from root folder!
Debug: VIP-CLI v3.4.0, Node v18.17.1, darwin 23.5.0 arm64Deploy the archived file
VIP-CLI command: vip app deploy
The vip app deploy command requires the WPVIP_DEPLOY_TOKEN environment variable to be passed with the value of a valid Custom Deployment token assigned to it.
When performing a Custom Deployment with VIP-CLI, a description of the deploy can be passed with the --message option. The value can be passed within single (e.g. 'value‘) or double quotes (e.g. "value"). The passed value for the deploy will appear on the “Deployments” panel of the VIP Dashboard in the column labeled “Description“.
In this example command and output the vip app deploy command is used to deploy an archived file named example-file.tar. The command targets the production environment of the “example-app” application, and the token value 1234 is assigned to the environment variable WPVIP_DEPLOY_TOKEN:
$ WPVIP_DEPLOY_TOKEN=1234 vip @example-app.develop app deploy example-file.tar
✔ You are about to deploy to a un-launched PRODUCTION site mytestsite.go-vip.net.
Type 'EXAMPLE-APP.GO-VIP.NET' (without the quotes) to continue:
· EXAMPLE-APP.GO-VIP.NET
=============================================================
Processing the file for deployment to your environment...
✓ Uploading file
✓ Triggering deployment
✅ 20240613214605-example-app.zip has been sent for deployment to example-app.go-vip.net.
To check deployment status, go to VIP Dashboard: https://dashboard.wpvip.com/apps/8886/production/code/deploymentsLast updated: September 29, 2025