VIP Go platform specific
This document is for sites running on VIP Go.
- Access to the VIP repository
- What can be put in the VIP repository?
- VIP Go MU plugins
- Developing in the Github Repo
- How does the code get deployed?
- Plugins on VIP Go
- How do I access my code?
- About themes on VIP Go
- What versions of WordPress and Jetpack does VIP Go use?
- How do new versions of WordPress get released?
On the VIP platform, each site’s code lives within a repository (repo) in the WordPress.com VIP GitHub organization. By default, this repository will be private but can be public if required. Once the repository is created, it can be used for development, or simply to push work to it as a Git remote and use any existing infrastructure (e.g. Beanstalk, Bitbucket, etc.)
The codebase consists of core WordPress, with modifications made via a handful of mu-plugins that are available via GitHub. All other custom code should be committed to the Git repository. When developing your site, it is vital that the same mu-plugins are used in the test environment.
Access to the VIP repository #
There is no limit to how many GitHub users from an organization, development team, or agency can access the repo. VIP is happy to give nominated users
admin access to the repo, allowing user management or application integration.
Alternatively, VIP can add GitHub collaborators to a repo on a client’s behalf. To do so, please send through their GitHub usernames and whether they should have
admin access to the repo.
What can be put in the VIP repository? #
The repository for each VIP site (see vip-skeleton for an example) has the following directory structure:
- client-mu-plugins: for always active, global plugins (similar to mu-plugins) — see our plugin documentation for more information.
- images: Store your site’s favicons here, per this documentation. All other public-facing images should be uploaded or imported to the WordPress dashboard or stored as part of your
- languages: For
.motranslation files, which specify the translated strings for the site. See below for how to upload languages.
- plugins: Your site’s plugins — more details here.
- private: Provides access to files that are not directly web accessible, but can be accessed by your theme or plugin code.
- themes: Themes to be made available to your sites. We recommend keeping the default theme available for testing purposes.
- vip-config: For custom configuration changes and additional
sunrise.phpcode. This folder’s
vip-config.phpfile is used in place of
All of these directories are required and should not be removed. These directories will also be available on production web servers. Any additional directories created in your GitHub repository that are not included in the above list will not be mounted onto your site, and so will not be web-accessible.
The plugins and themes directories are mapped to
wp-content/themes/ and should be treated like any other WordPress install.
vip-config directory contains a file named
vip-config.php. This is where to put things usually found in
wp-config.php. Not all settings can be changed, as we have optimized certain aspects of the WordPress install, but it is handy if you need to define something like an API key or secret. Note that most of WordPress is not available when this file is loaded and code should be limited to pure PHP.
languages directory is mapped to
wp-content/languages, and should contain the
.mo files which specify the translated strings for the site. In order to upload the language files for a particular language, follow these steps. In this example, we’ll be uploading Italian:
- Download the Italian WordPress distribution from here.
- Unpack it to, for example,
cp -r /path/to/wordpress/wp-content/languages/* /path/to/your-repo/languages/
(IMPORTANT! If you have custom translations in any currently present it_IT.* files, you might want to back those files up. You can then backport those custom translations in the new it_IT.po and regenerate it_IT.mo from it. If you need to do this and need assistance, let us know in a ticket, and we’ll be happy to help.)
- After that, you’ll have to commit, push up, and deploy the changes.
- To upload other languages, follow the same steps, downloading that particular language WordPress distribution in step 1.
apple-touch-icon*.png variant files are mapped to files with the same name within the
images directory of the client repository. See the Favicons section below.
private directory is mapped to
/private/, which is not web accessible; this might be used to store files streamed via PHP, e.g. a paid, commercial plugin which needs a purchase record checked before starting the download.
To account for multisites that use different domains, the specific order of lookup for
apple-touch-icon*.png variant files is:
- 1×1 transparent pixel
$http_host is the domain name.
Multisites that use subfolder (e.g.
example.com/site-a) do not have specific support, since requests for the root icon would be to
Submodules are a common way to include code by referencing another Git repository, you can read more about submodules on the official Git SCM site. We support the use of public Git Submodules, however private Git Submodules, i.e. submodules which you need to authenticate to access, are not supported.
VIP Go MU plugins #
The VIP Go MU (“Must Use”) plugins are deployed to all VIP Go WordPress applications. The MU plugins codebase provides VIP Go WordPress applications with integration to the VIP Go infrastructure, e.g. cache management, as well as various helper functions and performance enhancements commonly used by applications hosted on our platform.
Our MU plugins are open sourced, and you can follow the development on our GitHub repository here:
If you simply want a “built” copy of the code, avoiding the complexities of submodules, then the simplest way to get that is from our “built” repository:
Your local development environment must include a copy of our MU plugins.
Developing in the Github Repo #
If you choose to develop in a separate repo before pushing to the VIP repo, here are a few things to consider:
- Just like on WordPress.com sites, the VIP team may occasionally need to push security/performance related hotfixes to the
wpcomviprepo. (We usually do these through PRs for greater visibility.) It’s important that you have a process in place that merges the changes back to your main development repo.
- It’s probably a good idea to have your development repo mirror the structure of
wpcomviprepo directly to minimize complexities when pushing/pulling between them. Similarly, it’s a good idea to sync all commits as well (instead of doing large batched commits).
- For external dependencies (e.g. plugins), you can use submodules or subtrees (although, note that private submodules are not supported).
How does the code get deployed? #
Each VIP Go site or environment tracks a specific branch of your repository. For example, the production environment will track the
master branch; if you have requested other sites they will each have a specific branch they are tracking.
If you have a child environment, the branch will always auto-deploy. For the production environment, the
master branch will auto-deploy in the time leading up to and during the initial code review. For sites on Full or Enhanced review levels, once the initial review has been completed, we will enable the GitHub Pull Request workflow, which is covered here.
Plugins on VIP Go #
See our separate document on installing and activating plugins on VIP Go.
See the separate document
sunrise.php on VIP Go.
How do I access my code? #
See Accessing your code.
About themes on VIP Go #
Themes in the VIP Go environment live in
WP_CONTENT_DIR . '/themes/'. So if your organization is called Acme Kite Co., for example, your theme path might be
If you anticipate setting up multiple themes for your site or if you are a developer working on different themes for different sites, you might need a naming scheme that further distinguishes themes, e.g.
Child Themes #
Child theme-ing works the same in this case as child theming on self-hosted WordPress sites. Just add another theme to your Git repository at
/themes. Because the themes on WordPress.com aren’t available in the Git repository, they will need to be added before they can be used as parent themes.
No required code in functions.php and no vip-init.php #
Unlike WordPress.com VIP, there is no required code in the theme’s
functions.php file, nor do you need a
Use Underscores for a head start
The Underscores project will generate a starter theme that can be used to get a head start on your theme development. It includes lean, well-commented, modern, HTML5 templates, minimal CSS that’s ready for you to build on, and a variety of tools to help you work efficiently in customizing your theme
/private folder in your repo, if used, will provide access to files that are not web accessible, but can be accessed by your theme or plugins. We provide a constant,
WPCOM_VIP_PRIVATE_DIR, which contains the path to the private folder, and you should always use this to access the
For example, if you place a file at
/private/sites.json you can access that within your theme with:
file_get_contents( WPCOM_VIP_PRIVATE_DIR . '/sites.json' );
Please note that this constant is only available inside theme or plugin code; using it in
vip-config.php is too early and will not produce the desired behaviour.
No visitor will be able to access that file at any URL, unless deliberately exposed via the theme or a plugin.
Like all code directories on VIP Go, the
/private directory is not writable by PHP so you cannot save uploaded files to it.
/private folder is mapped to
/private, in the root of the filesystem, on the VIP Go server.
What versions of WordPress and Jetpack does VIP Go use? #
Your website will be running the latest stable version of WordPress and Jetpack at all times.
In advance of a major version update for WordPress core or Jetpack (e.g. from 5.1 to 5.2) to VIP Go, as the beta testing period begins, WordPress.com VIP will post to the VIP Lobby. The deployment of minor versions will not receive a Lobby post. Security updates will be deployed as soon as practicable, and will not receive a Lobby post.
We provide the facility to test beta and release candidates of Jetpack of Jetpack on VIP Go.
During the run-up to a new version of WordPress, we invite our clients to run their non-production sites against
trunk (here is the core WordPress project explanation of
trunk and other SVN terms). If you’d like one or all of your non-production sites to track
trunk, please get in touch. Sites tracking trunk will be updated to the latest
trunk revision at least once a day, but we cannot guarantee the timing of this update.
How do new versions of WordPress get released? #
As a new release is tagged on WordPress.org we will begin rolling it out to our customers. This is a rolling upgrade process and is normally completed within 48 hours of an official release. A small subset of sites are tested before the wider release to ensure stability. WordPress.com VIP continually monitors all VIP sites to ensure they are up and serving a reasonable response code, and this process continues as we roll out releases to our customers.
As a release approaches, you should test your site against WordPress core betas and release candidates as they are released, to ensure the upgrade process goes smoothly.