External Repositories
Setup WordPress
Configure a WordPress repository for Pantheon's external repository integration with the required file structure and platform settings.
This page describes how a WordPress repository configured for Pantheon differs from a standard WordPress installation. Use it as a reference when preparing your GitHub or GitLab-hosted WordPress repository.
Requirements
Before you begin, make sure you have:
- A Pantheon account with external repositories access enabled
- A GitHub or GitLab repository
- Familiarity with Git and your CMS's configuration
Summary of Differences
A Pantheon WordPress repository is a complete WordPress installation with six categories of changes from a vanilla WordPress download:
Directory Structure
Items marked (Pantheon) are additions or modifications. Everything else is standard WordPress core.
Modified Files
pantheon.upstream.yml
This file configures the Pantheon platform infrastructure. For an site connected to an external repository, you may alternatively use pantheon.yml (same format).
| Setting | Purpose |
|---|---|
api_version | Pantheon config API version (always 1) |
php_version | PHP runtime version |
database.version | MariaDB version |
enforce_https | HTTPS enforcement mode (transitional or full) |
protected_web_paths | Paths blocked from public web access |
Source: pantheon.upstream.yml
Must-Use Plugins
WordPress on Pantheon requires a wp-content/mu-plugins/ directory containing the Pantheon MU-plugin. This provides:
- Page cache integration with Pantheon's Varnish/edge cache layer
- Site health checks specific to Pantheon
- Update notices customized for the Pantheon workflow
- Login form modifications (adds a "Return to Pantheon" button)
- WP-CLI integration for Pantheon-specific CLI commands
- Multisite support
- Filesystem method set to
direct - Plugin compatibility layer with automatic fixes for 15+ popular plugins
The loader.php file is the entry point that loads the pantheon-mu-plugin/pantheon.php plugin from its subdirectory.
The MU-plugin only activates its features when $_ENV['PANTHEON_ENVIRONMENT'] is set.
Source: Pantheon MU Plugin
loader.php source: loader.php
Checklist
Use this checklist to verify your WordPress repository is ready for Pantheon's external repository integration:
More Resources
- WordPress on Pantheon - Comprehensive guide to running WordPress on Pantheon
- Using Git with WordPress - Learn Git workflows specifically for WordPress development
- WordPress Configurations - Managing plugins, themes, and WordPress-specific configurations
- WP-CLI on Pantheon - Command-line tools for managing WordPress sites
- pantheon.yml - Platform configuration file reference
- external repositories Usage - Working with pull requests, merge requests, and deployments