README

One ring to rule them all - Manage your Pantheon hosting environment directly from WordPress.

Ash Nazg integrates the Pantheon Public API into your WordPress admin dashboard. Toggle between SFTP and Git mode, view debug logs, manage addons, trigger workflows, monitor metrics, and manage your Pantheon environment—all without leaving WordPress.

Why "Ash Nazg"?

The name comes from the One Ring inscription in Tolkien's works. Just as the One Ring unified power, this plugin unifies your workflow by bringing Pantheon platform management into the one place you're already working: WordPress admin.

Features

Dashboard & Monitoring

View your Pantheon environment status, site information, and connection mode at a glance. Monitor 26+ API endpoints with live status indicators showing which Pantheon features are available. Toggle between SFTP and Git mode with automatic verification.

Features:

Auto-detect environment (dev/test/live/multidev/local)
Real-time API endpoint testing with status indicators (green checkmarks, red X's)
Site and environment information from Pantheon API
SFTP/Git mode toggle with automatic polling verification
Inline site label and organization editing with pencil icon
Pantheon user info and machine token copy button in environment card
50/50 two-column layout with environment and site info cards
Screen Options to show/hide individual API endpoint groups (with master toggle)
Smart caching with "last checked" timestamps and one-click refresh

WP Admin Dashboard Widget

A "Cache Performance" widget on the main WordPress admin dashboard shows your Pantheon site's cache hit ratio at a glance—no need to navigate to the Metrics page for a quick status check.

Features:

Line chart of cache hit ratio % over the last 28 days
Summary stats: average cache hit ratio and pages served
Link to the full Metrics page
Only shown to manage_options users on Pantheon sites

Upstream Updates (WP Updates Page)

Pantheon upstream updates are now surfaced on the native WordPress Updates page (update-core.php) alongside core, plugin, and theme updates—so you don't have to remember to check the Development page separately.

Features:

Shows available upstream updates directly on WP Admin > Updates
"Apply Updates" button opens the same progress modal used on the Development page
Polls workflow status until complete, then refreshes the page

Development

Manage code deployment, upstream updates, multidev environments, and uncommitted changes from a single interface. All development operations accessible from one page regardless of your current environment.

Code Deployment:

Deploy code from dev to test or test to live
Side-by-side panels with environment sync detection
Optional "sync content from live" for test→live deployments
Change detection disables buttons when environments are in sync
Deployment notes with workflow monitoring

Upstream Updates:

Detect available upstream updates per environment
Per-environment filtering (only shows updates not yet applied)
One-click apply with workflow monitoring
Automatic cache invalidation after updates
Also surfaced on WP Admin > Updates page (see above)

Multidev Management:

Create new multidev environments cloned from any existing environment (not just dev)
Merge multidev into dev or merge dev into multidev
Delete multidev environments with confirmation
Environment status and branch information display
WP Admin links for all non-current environments
Consistent environment ordering: dev → multidevs (sorted alphabetically) → test → live

Uncommitted Changes:

View uncommitted local file changes (git status --porcelain)
View unpushed local commits (git log @{u}..)
Commit SFTP changes with commit message
File count and change type display
Recent commits history with Refresh button

Screen Options:

Show/hide Environments card
Show/hide Multidev Management card

Debug:

Raw API response sections hidden by default

Metrics

View traffic and cache performance analytics for any Pantheon environment from a dedicated Metrics page. Also available as a dashboard widget.

Features:

Three interactive line charts: Pages Served, Unique Visits, Cache Performance (hits vs. misses)
Summary Statistics card displayed above chart filters for quick reference
Duration selector: 7 days, 28 days, 12 weeks, 12 months
Environment and duration selections persisted in localStorage
Screen Options: show/hide individual charts independently; filters auto-hide when all charts hidden
Refresh button to clear cache and reload data
1-hour cache TTL for metrics data
API request/response debug panels hidden by default

Backups

Create, restore, and download backups for any environment. Manage backups across all environments from a single interface.

Features:

Environment dropdown selector for backup creation
Create backups: all, code only, database only, or files only
Configurable retention period (1-365 days)
Tabbed dev/test/live backup catalog (JS-driven tabs); default tab is current environment
Backup filenames displayed on one line with ellipsis truncation
Screen Options: age filter (all / last 7 days / 30 days / 1 year) stored per user
Restore backups with destructive operation warnings
Download backups via signed URLs (code/database/files)
Collapsible backup sets to reduce vertical space
Workflow monitoring for long-running operations

Clone Content

Copy database and/or files between environments with automatic URL search-replace for WordPress.

Features:

Source and target environment dropdown selectors
Clone database, files, or both
Automatic WordPress URL search-replace (from_url → to_url)
Environment initialization validation
Destructive operation warnings with confirmation modals
Multi-workflow monitoring (polls both DB and files simultaneously)
Automatic cache clearing after successful clones

Debug Logs

View and clear WordPress debug logs without SSH access. Automatically switches to SFTP mode if needed to access log files on Pantheon's read-only Git filesystem.

Features:

Fetch and display debug.log contents
One-click log clearing with automatic mode switching
Skips SFTP switching on local environments
File stat cache clearing for accurate deletion verification

Addons

Enable or disable Pantheon site addons (Redis object caching, Apache Solr search) directly from WordPress admin.

Features:

Toggle Redis object cache addon
Toggle Apache Solr search addon
Elasticsearch shown with "Coming Soon" badge (not yet available via API)
Live status detection: reads $_ENV on Pantheon, queries Terminus internal API on local
Screen Options: show/hide Redis, Solr, and Elasticsearch sections independently
Persistent state tracking in WordPress options
Automatic cache clearing after changes

Workflows

Trigger Pantheon workflows from WordPress, including Object Cache Pro installation via scaffold_extensions workflow.

Features:

Trigger Object Cache Pro installation (scaffold_extensions workflow)
Environment validation (dev/multidev only)
Workflow status retrieval and monitoring
Additional workflow types as discovered

Domains (Multisite Only)

For WordPress multisite installations, automatically add custom domains to Pantheon when new subsites are created.

Features:

Automatic domain addition on subsite creation
Hooks into wp_initialize_site (WP 5.1+) and wpmu_new_blog (legacy)
Skips local environments automatically
Adds domains to live environment by default
Admin notices for success/failure via transients
Synchronous operation (no workflow polling)

Settings

Configure machine token authentication, view/clear session tokens, and manage plugin settings. Tokens stored securely in Pantheon Secrets (production) or WordPress options (local development fallback).

Features:

Per-user machine token configuration (v0.4.0+)
Pantheon Secrets integration with user ID suffix
Encrypted token storage (AES-256-CBC) for database fallback
Migration from global to per-user tokens
Session token viewing and manual clearing
Auto-clears invalid tokens on 401/403 errors
Development fallback for local environments

Delete Site (Debug Mode Only)

Demonstration feature showing full Pantheon API capabilities.

Features:

Big red DELETE SITE button
Menu item: "⚠️ DO NOT CLICK" (red background)
Type "DELETE" to enable button
Two-stage confirmation (modal + JavaScript alert)
"Whew! That was a close one!" message on cancellation
Fully functional - actually deletes site via Pantheon API
Redirects to Pantheon dashboard after deletion

Excluded for Security

This plugin does not provide access to:

Organization or user management (beyond what's displayed)
Billing information or plan changes
Token generation/revocation (only usage)
Unrestricted site deletion (only via debug mode)

Requirements

Must be hosted on Pantheon (plugin uses Pantheon-specific environment variables and Secrets API)
WordPress 5.0 or higher
PHP 7.4 or higher
Pantheon machine token (per-user, v0.4.0+) stored in Pantheon Secrets (how to create)
User with manage_options capability in WordPress

Installation

Via Composer (Recommended)

composer require jazzsequence/ash-nazg

Activate the plugin through the WordPress admin or via WP-CLI:

wp plugin activate ash-nazg

From GitHub Release

Download the latest release ZIP file from GitHub Releases
Upload the ZIP file through WordPress Admin > Plugins > Add New > Upload Plugin
Activate the plugin
Navigate to Ash Nazg in the WordPress admin menu

Configuration

Setting Up Your Pantheon Machine Token

Version 0.4.0+ introduces per-user machine tokens. Each WordPress admin can have their own Pantheon machine token for better security and audit trails.

Create a machine token:
- Log into your Pantheon Dashboard
- Go to Account > Machine Tokens
- Create a new machine token
- Copy the token (you'll only see it once!)
Find your WordPress user ID:
- Navigate to Ash Nazg > Settings in the WordPress admin
- Your user ID is displayed prominently in the settings page
- You'll need this ID for the next step
Store the token (Recommended: Pantheon Secrets):

We highly recommend using Pantheon Secrets to securely store your machine token. Each user has their own secret with their user ID as a suffix:
```
terminus secret:set <site> ash_nazg_machine_token_1 YOUR_TOKEN --scope=user,web
```
Replace 1 with your WordPress user ID (e.g., ash_nazg_machine_token_1, ash_nazg_machine_token_42, etc.).

The plugin will retrieve your token using pantheon_get_secret('ash_nazg_machine_token_{user_id}').

Alternative: WordPress Database

You can also configure the token in Ash Nazg > Settings in the WordPress admin. The token will be encrypted with AES-256-CBC using WordPress salts before being stored in the database. This is less secure than Pantheon Secrets but provides a local development fallback.
Verify setup:
- Navigate to Ash Nazg in your WordPress admin menu
- The plugin will auto-detect your Pantheon environment variables
- If your token is configured correctly, you'll see environment information on the dashboard

Migrating from v0.3.x to v0.4.0

If you're upgrading from a previous version with a site-wide global token, the plugin will show a migration notice with instructions:

Global database token: Click "Migrate to My Account" to copy and encrypt the token to your user account
Global Pantheon Secret: Follow the terminus command instructions to set your per-user secret

The global token will be deleted after migration. Other admins will need to set up their own tokens.

Development

This plugin is under active development. See CLAUDE.md for technical architecture and development guidelines.

Architecture

Functional programming with Pantheon\AshNazg namespace
Traditional WordPress admin interface using Pantheon Design System (PDS Core)
API-first approach using api.pantheon.io
Secure credential storage via Pantheon Secrets (recommended) or WordPress database

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Follow Pantheon WordPress Coding Standards
Write PHPUnit tests for new functionality
Test in a Pantheon environment
Submit a pull request

Development Setup

# Clone the repository
git clone https://github.com/jazzsequence/ash-nazg.git
cd ash-nazg

# Install dependencies
composer install
npm install  # or yarn install

# Run all checks (lint + tests) - recommended before committing
composer check

# Run all linting (PHP syntax + coding standards)
composer lint

# Run PHP syntax check only
composer lint:php

# Run coding standards checks only
composer lint:phpcs
# or
composer phpcs

# Auto-fix coding standards issues
composer phpcbf

# Run tests only
composer test

# Install test environment (for WordPress integration tests)
composer test:install

# Run Playwright E2E tests (future)
npm test

Development Dependencies

Composer:
- pantheon-systems/pantheon-wp-coding-standards - Coding standards
- pantheon-systems/wpunit-helpers - WordPress testing helpers
- phpunit/phpunit - PHP testing framework
npm/yarn:
- Pantheon Design System (PDS Core) - UI components

Future Improvements

Accessibility audit (WCAG compliance)
JavaScript bundling and minification
Playwright E2E tests

FAQ

Is this an official Pantheon plugin?

No, this is a Hackathon 2026 project built by Chris Reynolds, Senior Developer Advocate at Pantheon. It was built independently and is not officially supported by Pantheon.

Will this work with other hosting providers?

No, this plugin only works on Pantheon. It relies on:

Pantheon environment variables ($_ENV['PANTHEON_SITE'], etc.)
Pantheon Secrets API for credential storage
Pantheon-specific infrastructure

Does this require a specific Pantheon plan?

The Pantheon API is available to all Pantheon customers. Some features may vary based on your plan level (e.g., multidev availability).

Is my machine token secure?

Yes, especially if using Pantheon Secrets. Starting with v0.4.0, each WordPress admin has their own machine token for better security and audit trails.

Pantheon Secrets (Recommended): Tokens stored in Pantheon Secrets are encrypted and retrieved at runtime using pantheon_get_secret(). This is the most secure option.

Database Storage (Fallback): Tokens stored in the WordPress database are encrypted with AES-256-CBC using WordPress salts (v0.4.0+). While encrypted, this is less secure than Pantheon Secrets. We highly recommend using Pantheon Secrets for production environments.

What permissions does this plugin grant WordPress admins?

WordPress users with manage_options capability can:

View environment status and information
Toggle SFTP/Git mode
Deploy code and apply upstream updates
Create/manage backups and multidev environments

WordPress admins cannot (via this plugin):

Manage Pantheon users or organizations
Access billing information
Generate or revoke machine tokens
Delete sites (except via debug mode demonstration feature)

Support

Issues: Report bugs on GitHub Issues
Documentation: See CLAUDE.md for technical architecture and development guidelines
Pantheon API: Official API Documentation
Pantheon Secrets: Pantheon Secrets Guide

License

This plugin is licensed under the GPL v2 or later.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

Credits

Developed with the power of the Pantheon Public API.

Named after Tolkien's One Ring inscription: "Ash nazg durbatulûk, ash nazg gimbatul, ash nazg thrakatulûk, agh burzum-ishi krimpatul" - One ring to rule them all, one ring to find them, one ring to bring them all, and in the darkness bind them.

Changelog

0.6.0 - Current Release

Dashboard Redesign: 50/50 two-column layout with environment card showing user info, org selector, and machine token copy button
Screen Options: Show/hide controls across Dashboard, Development, Addons, Backups, and Metrics pages
WP Updates Page Integration: Pantheon upstream updates surfaced on native WP Admin > Updates page with progress modal
Development Enhancements: Local uncommitted changes, unpushed commits, Refresh on Recent Commits, WP Admin links in environments table
Metrics Improvements: Summary Statistics above filters, localStorage persistence, per-chart Screen Options
Backups Tabs: dev/test/live tabbed UI (JS-driven); age filter via Screen Options stored per user
Addons: Elasticsearch "Coming Soon" badge, live status detection, per-addon Screen Options
WP Admin Dashboard Widget: Cache hit ratio line chart over 28 days with link to Metrics page
Release Pipeline: GitHub Actions release workflow, build-dist.sh, .distignore, Dependabot config
Menu Reorder: Ash Nazg → Metrics → Development → Addons → Workflows → Backups → Clone → Logs → Settings
SCSS Components: _code-blocks.scss for debug panels, _dashboard-widget.scss for widget styles

0.5.0

Environment Metrics Visualization: New "Metrics" admin page showing traffic and performance analytics
Chart.js Integration: Interactive line charts with Pantheon Design System colors and styling
Multiple Time Periods: View metrics for 7 days, 28 days, 12 weeks, or 12 months
Three Chart Types: Pages Served, Unique Visits, and Cache Performance (hits vs misses)
Summary Statistics: Overall totals and average cache hit ratio with per-chart breakdowns
Refresh Functionality: Clear cache and reload current metrics data
Responsive Design: Mobile-friendly charts with smooth curves and hover interactions
Debug Panels: Expandable API request/response panels for troubleshooting
Comprehensive Tests: 24 PHPUnit tests for metrics API and UI components
Chart.js in libs/: Renamed vendor directory to libs for better clarity

0.4.0

Per-User Token Storage: Machine tokens now stored per-user instead of site-wide
Token Encryption: AES-256-CBC encryption for database-stored tokens using WordPress salts
Pantheon Secrets Integration: Per-user secret keys with user ID suffix (ash_nazg_machine_token_{user_id})
Migration System: Backward-compatible migration from global to per-user tokens
Migration UI: Admin notice with progressive nag (1 week → 24 hours) and settings page migration button
Per-User Session Tokens: Separate session token caching per user for better audit trails
Security Enhancement: Better security and audit trails with individual token revocation
User ID Display: Prominent user ID display in settings for Pantheon Secrets setup
PHPUnit Tests: Comprehensive test suite for user token functionality

0.3.2

Bug Fixes: Clear logs false negative with clearstatcache(), SFTP mode switching on local environments
API Endpoint Testing: Corrected upstream-updates endpoint path in dashboard testing
Version Bump: Browser cache busting for modal.js and other JavaScript files

0.3.0 - Major Feature Release

Code Deployment: Deploy to test/live environments with panel-based UI and sync content option
Multidev Management: Create, merge, and delete multidev environments
Backup Management: Create, list, restore, and download backups from any environment
Clone Content: Copy database and/or files between environments with automatic URL search-replace
Domain Management: Automatic domain addition for WordPress multisite subsites
Delete Site: Demonstration feature (debug mode only) with big red button
Build Pipeline: SASS compilation with Pantheon Design System integration
PDS Integration: Fonts, design tokens, foundations, and branded Pantheon header
Upstream Updates: Detection and filtering per environment
Workflow Monitoring: Polling for long-running operations with progress modals

0.2.0 - Development Workflow

SFTP/Git Mode Toggle: Switch connection modes with automatic verification
Environment State Management: Persistent tracking in WordPress options
Automatic Mode Switching: Auto-switch to SFTP for file operations
Debug Log Viewer: View, fetch, and clear debug.log files without SSH
JavaScript Organization: Separate files with proper enqueuing
CSS Organization: Utility classes system, no inline styles
Comprehensive Testing: API, state management, and AJAX test suites

0.1.0 - Initial Release

Pantheon API client with authentication
Dashboard with environment detection and API endpoint testing
Site addons management (Redis, Solr)
Workflows integration (Object Cache Pro installation)
Smart caching with timestamps
Settings page with machine token configuration
WordPress coding standards and PHPUnit testing infrastructure

jazzsequence / ash-nazg

Maintainers

Package info

Statistics

Security

README

Why "Ash Nazg"?

Features

Dashboard & Monitoring

WP Admin Dashboard Widget

Upstream Updates (WP Updates Page)

Development

Metrics

Backups

Clone Content

Debug Logs

Addons

Workflows

Domains (Multisite Only)

Settings

Delete Site (Debug Mode Only)

Excluded for Security

Requirements

Installation

Via Composer (Recommended)

From GitHub Release

Configuration

Setting Up Your Pantheon Machine Token

Migrating from v0.3.x to v0.4.0

Development

Architecture

Contributing

Development Setup

Development Dependencies

Future Improvements

FAQ

Is this an official Pantheon plugin?

Will this work with other hosting providers?

Does this require a specific Pantheon plan?

Is my machine token secure?

What permissions does this plugin grant WordPress admins?

Support

License

Credits

Changelog

0.6.0 - Current Release

0.5.0

0.4.0

0.3.2

0.3.0 - Major Feature Release

0.2.0 - Development Workflow

0.1.0 - Initial Release