WP Engine Pipelines WordPress Starter

A template repository for building WordPress sites with WP Engine Pipelines.

Overview

This repository provides a starting point for WordPress development with WP Engine Pipelines. It follows the wp-content structure pattern where you commit only your custom themes, plugins, and mu-plugins. WordPress core and platform dependencies are handled automatically by the build process in your WP Engine pipeline.

Prerequisites

• Composer installed locally

Quick Start

1. Click "Use this template" to create your repository
2. Clone your new repository locally
3. Run composer install to download the starter theme
4. Add your plugins and themes (via Composer or manually)
5. Commit all files, including installed dependencies
6. Push to trigger a build

Note: Remove .github/CODEOWNERS after creating your repo — it's used for template maintenance and isn't needed in your project.

Repository Structure

├── config/           # WordPress configuration constants
├── plugins/          # Your WordPress plugins
├── themes/           # Your WordPress themes (required)
├── mu-plugins/       # Your must-use plugins
├── composer.json     # Dependency management
└── composer.lock     # Locked dependency versions

Requirements

Themes (Required)

The default TwentyTwentyFive theme is included via Composer — run composer install and commit the result before pushing.

Warning

At least one committed WordPress theme is required in the themes/ directory. Builds will fail if none is present.

Plugins (Optional)

Place WordPress plugins in the plugins/ directory, or install via Composer.

Must-Use Plugins (Optional)

Place mu-plugins in the mu-plugins/ directory. WP Engine's required mu-plugins are automatically installed during the pipeline's build process.

WordPress Configuration

Important

Do not store secrets (credentials, API keys) here. Sensitive values can be set in the WP Engine User Portal.

config/config.php is available for non-sensitive WordPress constants. The file is loaded after platform-managed constants, so platform values take precedence and cannot be overridden.

Use a guard before every define() call:

if ( ! defined( 'MY_CONSTANT' ) ) {
    define( 'MY_CONSTANT', true );
}

The starter config/config.php includes a commented-out example to get you started.

What NOT to Include

The following are managed by WP Engine and should NOT be committed:

• WordPress Core (wp-admin/, wp-includes/, etc.)
• wp-config.php
• uploads/
• Object cache drop-in (object-cache.php)
• WP Engine mu-plugins

Using Composer

This template uses WPackagist to install plugins and themes from WordPress.org.

Installing Dependencies

composer install

Adding a Plugin

composer require wpackagist-plugin/plugin-name

Adding a Theme

composer require wpackagist-theme/theme-name

Important: Commit Dependencies

The pipeline's build process does not run composer install. You must commit all installed files (themes, plugins) to your repository. Use Composer for local dependency management, then commit the results.

WordPress Version Management

By default, WP Engine automatically manages your WordPress core version and applies patch updates. You can optionally pin your site to a specific major version of WordPress using the composer.json configuration.

Specifying a WordPress Version

To set a specific WordPress major version, add the wordpress_core_version field to your composer.json:

{
  "extra": {
    "wpengine": {
      "wordpress_core_version": "6.9"
    }
  }
}

Version Format

• Major versions only: Use the format "6.9" or "7.0"
• Patch-level versions are not supported: Values like "6.9.4" are invalid
• Automatic patch updates: The platform automatically applies security and patch updates within the specified major version

Platform Default Behavior

If the wordpress_core_version field is absent or empty, the platform applies its default WordPress version with automatic updates. No configuration is needed if you prefer this behavior.

Supported Versions

Generally, the last 3 major versions will be supported. Please reach out to support if you encounter any issues.

Local Development

For local development, you need a separate WordPress installation. This repository provides only wp-content files.

Recommended options:

• Local by WP Engine
• Docker with a WordPress image
• Standard LAMP/LEMP stack

Symlink or copy this repository's directories into your local WordPress wp-content/.

The WP Engine Pipeline

The following occurs when you push to a repository once you have configured a pipeline for it in the WP Engine User Portal:

1. The pipeline clones your code.
2. WP Engine's required plugins and mu-plugins are merged with your themes, plugins, and mu-plugins. WP Engine requirements overwrite committed code when paths conflict.
3. The pipeline packages the bundled code.
4. The package is deployed.

Troubleshooting

Push fails with HTTP 400 error

If your first push fails with an error like:

error: RPC failed; HTTP 400 curl 22 The requested URL returned error: 400
fatal: the remote end hung up unexpectedly

This typically occurs when pushing large initial commits (themes with fonts/images). Increase Git's HTTP buffer size:

git config http.postBuffer 524288000

Then retry your push.

License

MIT License - see LICENSE for details.