Skip to content

Add S3 hosting guidance for Blueprint resources - #3754

Merged
fellyph merged 3 commits into
WordPress:trunkfrom
ekamran:shifteq/add-s3-blueprint-resource-docs
Oct 27, 2026
Merged

fellyph merged 3 commits into
WordPress:trunkfrom
ekamran:shifteq/add-s3-blueprint-resource-docs

Conversation

@ekamran

@ekamran ekamran commented Jun 4, 2026 •

Copy link
Copy Markdown
Contributor

What this changes

Adds Amazon S3 hosting guidance for Blueprint URL resources, including:

  • S3 object URL format for Blueprint, plugin, and theme assets
  • public read bucket policy example
  • CORS configuration for Playground requests
  • an installPlugin Blueprint example using pluginData
  • a ?blueprint-url= example for S3-hosted Blueprint files

Related issue

Fixes #962

Summary by CodeRabbit

  • Documentation
    • Added a guide for hosting URL resources on Amazon S3, with setup instructions and examples for loading plugin and theme ZIPs and Blueprint JSON.
    • Clarified how CORS, public access settings, and object privacy affect access to hosted resources.

@ekamran
ekamran requested review from a team, Copilot and zaerl June 4, 2026 18:10
@github-actions github-actions Bot added the [Type] Documentation Improvements or additions to documentation label Jun 4, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds documentation explaining how to host Blueprint-related URL resources on Amazon S3 so Playground can fetch them successfully.

Changes:

  • Documented S3 object URL usage for url resources
  • Added example public-read bucket policy and CORS configuration for playground.wordpress.net
  • Added Blueprint examples for installPlugin with pluginData and ?blueprint-url= pointing to S3

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@ekamran

ekamran commented Jun 4, 2026

Copy link
Copy Markdown
Contributor Author

I’ve pushed a follow-up that tightens the S3 guidance based on review feedback. It now scopes the public bucket policy to Blueprint/plugin/theme prefixes, adds a Block Public Access note, documents the dotted-bucket HTTPS concern with an AWS reference, and includes a concrete installTheme example alongside the installPlugin example. I also re-ran git diff --check and the English docs build with npm run build -- --locale en.

@adamziel
adamziel requested a review from fellyph June 12, 2026 11:42
@adamziel

Copy link
Copy Markdown
Collaborator

Looping in @fellyph

@ekamran

ekamran commented Sep 12, 2026

Copy link
Copy Markdown
Contributor Author

@fellyph following up on Adam's ping above, this is still ready for review whenever you get a chance, the target file has not changed since.

@fellyph

fellyph commented Oct 26, 2026

Copy link
Copy Markdown
Collaborator

Two non-blocking suggestions to clarify the S3 guidance:

  1. Make the Block Public Access note more specific. Explain that BlockPublicPolicy must permit adding the public-read policy and RestrictPublicBuckets must permit anonymous reads. Account-level or organization-level restrictions can still block access even when the bucket settings allow it. The ACL-related protections (BlockPublicAcls and IgnorePublicAcls) can remain enabled for this bucket-policy approach; readers do not need to disable all four protections. AWS documentation.

  2. Distinguish CORS from access permissions. Add a sentence explaining that restricting AllowedOrigins to https://playground.wordpress.net controls browser cross-origin reads; it does not make these publicly readable objects private or prevent downloads by other clients. For a self-hosted Playground, readers should add the origin making the requests to AllowedOrigins. AWS CORS documentation.

The current recommendations otherwise look sound. The plugin Blueprint and theme step validate against both the published Blueprint schema and the repository validator. This verification did not include provisioning an S3 bucket or an end-to-end S3 installation.

Name the two Block Public Access settings that must be off for the public
read policy (BlockPublicPolicy, RestrictPublicBuckets), note that the ACL
settings can stay on and that account or organization settings still apply,
and say that AllowedOrigins only limits browser reads, with self-hosted
Playground origins added there.
@ekamran

ekamran commented Oct 26, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @fellyph, both suggestions are in 874d5bc:

  • Block Public Access: the note now names BlockPublicPolicy and RestrictPublicBuckets as the two settings that must be off, says the ACL settings can stay on, and that account-level or organization-level settings can still block access.
  • CORS: a new sentence says AllowedOrigins only controls which websites can read the objects from a browser, does not make them private, and that a self-hosted Playground needs its own origin added.

I checked the wording against the AWS pages you linked; like your review, this did not include provisioning a bucket.

@coderabbitai

coderabbitai Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review.

Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 30d27f0d-82bc-4e20-b40c-6d0087fdd77d
Commits

Reviewing files that changed from the base of the PR and between 1c2ec75 and 874d5bc.

Files selected for processing: 1
  • packages/docs/site/docs/blueprints/04-resources.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

Walkthrough

The Blueprint resources guide now explains how to host resources on Amazon S3. It covers object URLs, bucket access and CORS settings, and examples for loading plugin and theme ZIPs and Blueprint JSON files.

Changes: Amazon S3 hosting guide

Layer / File(s) Summary
S3 URLs and access configuration
packages/docs/site/docs/blueprints/04-resources.md
Documents virtual-hosted and path-style S3 URLs, public-read bucket policy requirements, Block Public Access settings, and CORS configuration.
Loading hosted resources
packages/docs/site/docs/blueprints/04-resources.md
Shows how to install a plugin or theme ZIP through a url resource and load a Blueprint JSON file with ?blueprint-url=.

Priority: Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: Minimal · up to 874d5

No concrete current-head defect remains in the reviewed documentation changes.

Pre-merge checks: Passed 5
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly and concisely describes the main change: adding Amazon S3 hosting guidance for Blueprint resources.
Linked Issues check Passed Issue #962 requires S3 guidance for Blueprint, plugin, and theme resources. The changed documentation provides regional object URL formats, bucket and region substitutions, a scoped public-read policy…
Out of Scope Changes check Passed The reviewed change is limited to packages/docs/site/docs/blueprints/04-resources.md. The added URL, policy, CORS, security, plugin, theme, and Blueprint examples directly support issue #962. No unr…
Docstring Coverage Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Full details: Linked Issues check

Explanation

Issue #962 requires S3 guidance for Blueprint, plugin, and theme resources. The changed documentation provides regional object URL formats, bucket and region substitutions, a scoped public-read policy, Block Public Access guidance, CORS settings, an installPlugin example with pluginData, an installTheme example with themeData, and a ?blueprint-url= example. It also links AWS settings documentation and explains public access and self-hosted Playground origins.

Full details: Out of Scope Changes check

Explanation

The reviewed change is limited to packages/docs/site/docs/blueprints/04-resources.md. The added URL, policy, CORS, security, plugin, theme, and Blueprint examples directly support issue #962. No unrelated change is shown.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

Finishing Touches
🧪 Generate unit tests (beta)
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@zaerl

zaerl commented Oct 26, 2026

Copy link
Copy Markdown
Contributor

@fellyph, can you please remove me as a reviewer on this PR? Much appreciated

@fellyph
fellyph removed the request for review from zaerl October 27, 2026 14:22
@fellyph

fellyph commented Oct 27, 2026

Copy link
Copy Markdown
Collaborator

@zaerl Sure, I will check other PRs that you are tagged in.

@fellyph fellyph left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @ekamran !

@fellyph
fellyph merged commit 04a510d into WordPress:trunk Oct 27, 2026
62 checks passed
@ekamran
ekamran deleted the shifteq/add-s3-blueprint-resource-docs branch October 27, 2026 15:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Type] Documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add S3 instructions to documentation

5 participants