Ghost Release: 3.26.0

TL;DR

Ghost 3.26.0 brings important bug fixes and new AMP Google Analytics support

This release focuses on fixing several critical issues with cache invalidation, Stripe subscriptions, and webhooks. It also introduces Google Analytics support for AMP pages through a new tracking ID setting. The update improves error handling for newsletter emails and enhances settings validation, particularly for Stripe plans. Most users should upgrade to benefit from these stability improvements.

Highlight of the Release

• Added Google Analytics support for AMP pages with a new tracking ID setting
• Fixed critical cache invalidation issues for posts with no content and when editing post metadata
• Resolved Stripe subscription issues with trial periods and race conditions during configuration
• Improved settings validation, particularly for Stripe plans
• Enhanced error handling for newsletter emails with better status codes and messages

Migration Guide

Webhooks Admin API v3 Changes

If you're using the Webhooks Admin API v3, note that JSON Schema validations have been added:

• New webhooks schemas and definitions are now in place
• Validation now checks if integration_id is present when using session auth to prevent orphan webhooks
• Added isLowerCase ajv keyword support for webhooks validation

AMP Google Analytics Implementation

If you're implementing AMP pages with Google Analytics:

1. Configure the new amp_gtag_id setting with your Google Analytics tracking ID
2. Use the new {{amp_analytics}} handlebars helper in your AMP templates to output the GA configuration
3. The {{amp_components}} helper will automatically include the necessary GA script in the head when the setting is present

Upgrade Recommendations

This release contains important bug fixes for cache invalidation, Stripe subscriptions, and webhooks, making it a recommended upgrade for all Ghost users.

Particularly important for:

• Sites using Stripe for memberships/subscriptions
• Sites with AMP pages who want to implement Google Analytics
• Sites experiencing cache invalidation issues when editing post metadata

The upgrade process follows the standard Ghost update procedure and should be straightforward with no breaking changes reported. As always, it's recommended to backup your database before upgrading.

Bug Fixes

Cache Invalidation

• Fixed cache invalidation when editing post_meta fields (closes #12016)

  • The change detection wasn't working properly because it only checked the current model's _changed fields
  • Added change tracking of post_meta relation to the currently edited post model and overloaded the wasChanged method

• Fixed cache invalidation for published posts with no content (closes #12015)

  • Resolved an issue where falsy plaintext field assignment to empty string was causing confusion in the model layer
  • The '' -> null conversion was incorrectly triggering change detection when no actual changes occurred

Stripe Integration

• Fixed importing Stripe Plans with amount 0 (closes #12049)

  • Stripe plans used to default to 0, and new validation was causing issues when importing from older Ghost versions
  • Updated validation to be skipped during import process
  • Added regression test for importing plans

• Fixed Stripe Subscriptions with trial periods

  • Corrected an issue where subscriptions with trial periods were incorrectly identified as being in a setup flow
  • Now properly using the mode property of Checkout Session to determine whether handling a new subscription or updating card details
  • Added additional logging for better troubleshooting

• Fixed race condition when configuring Stripe (closes #12065)

  • Resolved timing issues that could occur during Stripe configuration

Other Fixes

• Fixed edit link for staff members (closes #12069)

  • Updated frontend links to match the admin URL change from "team" to "staff"

• Fixed webhook cleanup to handle older URLs (closes #12061)

  • Improved webhook handling to properly manage legacy URL formats

• Fixed typos in webhook error messages

• Fixed incorrect font size in editor when using code tags in headings

New Features

Google Analytics for AMP Pages

Ghost now supports Google Analytics tracking for AMP pages. A new amp_gtag_id setting has been added, allowing site administrators to configure their Google Analytics tracking ID specifically for AMP pages. This feature includes:

• A new setting migration and default for amp_gtag_id
• Updated AMP output to include Google Analytics when the setting is present
• A new handlebars helper {{amp_analytics}} which outputs the GA configuration script
• Updates to the {{amp_components}} helper to output the GA script in the head when configured

This lays the groundwork for comprehensive analytics support in AMP pages.

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Improved Settings Validation

The settings validation system has been significantly improved:

• Moved settings validation from the validation file into the model where it's exclusively used
• Set up architecture for future custom validators on individual settings
• Enhanced validation of stripe_plans setting:
  • Checks that interval is a valid string
  • Verifies name & currency are strings
• Moved stripe key validation into the Settings model to handle nullable values properly
• Added comprehensive tests for new setting validations with helpers for easier future testing

Enhanced Error Handling for Newsletter Emails

• Added statusCode from bulk email provider to API responses
• Updated error messages for different bulk email (mailgun) failure states
• Added context to preview mail API error message with mail provider's error message
• Updated error code for incorrect recipients in GhostMailer from 500 to 400 for RecipientError
• Added extra check for empty err object while checking error name for status code

Impact Summary

Ghost 3.26.0 is primarily a maintenance release that addresses several important bugs while adding Google Analytics support for AMP pages. The most significant fixes resolve issues with cache invalidation, Stripe subscriptions with trial periods, and webhook handling.

The addition of Google Analytics support for AMP pages is valuable for site owners who use AMP and want to track visitor analytics. The improved error handling for newsletter emails provides better diagnostics when email delivery fails.

For developers, the enhanced settings validation and JSON Schema validations for the Webhooks Admin API v3 provide more robust infrastructure. The fixes for Stripe integration issues are particularly important for sites using the membership/subscription features.

Overall, this release improves stability and reliability while adding a useful analytics feature for AMP pages. There are no breaking changes, making it a safe and recommended upgrade for all Ghost users.

Full Release Notes