ci(ios): publish tagged releases as binary targets via Buildkite by jkmassel · Pull Request #502 · wordpress-mobile/GutenbergKit

jkmassel · 2026-05-11T22:13:08Z

Summary

bin/release.sh stops at "bump versions on trunk and push" — no more git tag, no more gh release create.
A new :rocket: Publish Swift release $NEW_VERSION Buildkite step, gated on build.env("NEW_VERSION") != null, takes over: builds + signs the XCFramework, uploads to S3, rewrites Package.swift to .release(version:, checksum:), tags, and creates the GitHub Release.
Mirrors the wordpress-rs tag-release flow (release/validate/update_swift_package/publish_release_to_github lanes; tag's commit lives off trunk, only the tag ref is pushed).

There's a bit of awkward duplication/mess in this PR – once we can remove the committed JS/HTML files, we can delete a bunch of release code – I'll probably move most of it to Fastlane to align with our other projects, which will iron out a lot of the oddities this PR introduces (like pretending Android doesn't exist...). I wanted to keep this PR small and focused, which resulted in some oddities.

Why

Tagged releases currently ship Package.swift in .local mode, so SPM consumers (WordPress-iOS pins v0.15.0) resolve the JS bundle from ios/Sources/GutenbergKitResources/Gutenberg/ — which is why those 61 files are still committed despite #495 wiring up XCFramework distribution for PR builds.

Once a tag's Package.swift points at the prebuilt XCFramework on CDN (this PR), and WordPress-iOS bumps to a tag cut under the new flow, the committed iOS bundle and the two commented-out lines at .gitignore:200-202 can finally be dropped.

How a release works after this

Step 1 — local (same as today, minus the tag/release):

```bash
make release VERSION_TYPE=patch
```

Bumps package.json / GutenbergKitVersion.swift / GutenbergKitVersion.kt, runs make build, commits as chore(release): X.Y.Z, pushes to trunk. Done. The script prints the SHA of the commit it just pushed — pin that SHA when triggering the Buildkite build below.

Step 2 — Buildkite:

Open https://buildkite.com/automattic/gutenbergkit/builds/new
Branch: trunk
Commit: the SHA printed by Step 1 (pin it — leaving it blank lets a concurrent merge tag the wrong commit)
Environment Variables: NEW_VERSION=vX.Y.Z

The build runs:

:white_check_mark: Validate Swift release — fast-fails on malformed tag names or if the tag/Release already exists. Tag check uses git_tag_exists(remote: true); release check uses get_github_release with an explicit api_token and asserts the response was a real 200 (not a swallowed 401/404/network error). Runs early so a bad NEW_VERSION short-circuits before the XCFramework build.
:rocket: Publish Swift release — gated on validate-release + the XCFramework build + lint/test steps. The lane:
1. Re-invokes validate as defense-in-depth — covers a future pipeline edit that drops the validate-release dependency. Cheap no-op when the earlier Buildkite step already passed.
2. Rewrites Package.swift to .release(version: "vX.Y.Z", checksum: ...) (reusing the rewrite_resources_mode! helper from ci(ios): publish + prune per-PR XCFramework snapshot branches #495).
3. Uploads the XCFramework to s3://a8c-apps-public-artifacts/gutenbergkit/vX.Y.Z/.
4. Checks out a local release/vX.Y.Z branch, commits the rewrite, tags vX.Y.Z, and pushes only the tag via push_git_tags. git push <tag> carries the commit along with the tag ref, so the tag's commit becomes reachable on origin via the tag alone — no branch ref ever lives on remote.
5. Calls set_github_release (release-toolkit action) against the just-pushed tag — auto-generated notes, marks as prerelease when the version contains -, uploads the XCFramework + checksum as assets. Authenticates with an explicit GITHUB_TOKEN so we don't depend on the agent's ambient gh auth.

The tag is pushed before the GH Release is created. Once the tag is on origin, SPM consumers can already resolve vX.Y.Z against the prebuilt XCFramework on CDN — the GH Release is metadata + an asset mirror on top of that. If set_github_release fails, the tag is unaffected and an operator can recreate the Release manually against the existing tag.

The tag's commit is parented on the release commit but unreachable from trunk's history — same shape as the pr-build/<n> and (deferred) trunk-build snapshot branches, just published under a tag ref instead of a branch ref.

The release lane is the CI orchestrator — don't run it locally: it pushes the tag, uploads to the public S3 bucket, and creates a real GitHub Release. For local diagnosis, invoke validate, update_swift_package, publish_to_s3, or publish_release_to_github individually.

Tag-triggered builds (Android still relies on these)

Pushing the tag triggers a separate Buildkite build (the pipeline has "Build tags" enabled). For Android, that build is still load-bearing — prepareToPublishToS3 resolves the version to vX.Y.Z from --tag-name and produces the canonical vX.Y.Z Maven artifact (the trunk branch-build only produces trunk-<sha>). The plugin hard-fails if the version is already published, so the trunk vs. tag builds aren't competing.

For iOS, the rocket step already uploads to gutenbergkit/vX.Y.Z/, so the tag-build's :s3: would just re-upload the same bytes. This PR adds && build.tag == null to the :s3: gate to skip it on tag builds. A cleaner future refactor would move Android publish into the rocket step too, then "Build tags" can be turned off entirely — out of scope here.

Changes

Fastfile

fastlane/Fastfile: Four new lanes — release (orchestrator: validate → rewrite → S3 → tag/Release), validate, update_swift_package, publish_release_to_github. The orchestrator re-invokes validate at the top so a future pipeline edit dropping the validate-release dep can't silently bypass validation. GitHub API calls (get_github_release, set_github_release) take an explicit api_token resolved from ENV['GITHUB_TOKEN'] — no reliance on gh CLI auth (the use-bot-for-git script only sets GIT_SSH_COMMAND). validate checks lane_context[GITHUB_API_STATUS_CODE] after the release probe so a swallowed 401/404 doesn't silently green-light the publish. Reuses the existing rewrite_resources_mode!, required_version!, xcframework_checksum, xcframework_file_path helpers added in ci(ios): publish + prune per-PR XCFramework snapshot branches #495.

Pipeline

.buildkite/pipeline.yml: New :white_check_mark: Validate Swift release step (gated on NEW_VERSION) and :rocket: Publish Swift release $NEW_VERSION step (gated on NEW_VERSION + trunk + non-PR), with the rocket step depending on validate plus the XCFramework build, swift package tests, lint, JS tests, and the iOS/web E2E suites. Existing :s3: Publish XCFramework to S3 step now also gated on NEW_VERSION == null && build.tag == null so the rocket step owns the vX.Y.Z/ namespace and the tag-triggered re-build doesn't re-upload the same iOS artifact. Version arg simplified from ${BUILDKITE_TAG:-$BUILDKITE_COMMIT} to $BUILDKITE_COMMIT since the step now never runs on a tag build.
.buildkite/release.sh (new): Sources use-bot-for-git, downloads the xcframework + checksum artifacts from build-xcframework, runs bundle exec fastlane release version:$NEW_VERSION. GITHUB_TOKEN for the API calls comes from the agent environment.

Release script

bin/release.sh: Dropped create_tag, create_github_release, is_prerelease (unused), and the gh dependency check. Push is now git push origin trunk (no --tags). New print_publish_instructions prints the Buildkite trigger steps and the just-pushed SHA after the trunk push. --dry-run now prints the same instructions with a [DRY RUN] prefix so the operator gets a full preview of a real run.

Behavior change: prereleases now get a GitHub Release

Previously, bin/release.sh skipped gh release create for prereleases (anything with a - suffix) — the tag was pushed but no GH Release existed. The new :rocket: flow does create a GH Release for prereleases, marked as prerelease. This is intentional: every tag now has a corresponding Release page with the XCFramework + checksum attached, and consumers who previously pinned prerelease tags via Git revision can keep doing so.

Docs

docs/releases.md: Rewrote into a Step 1 / Step 2 flow with a recovering-from-partial-publish section.
docs/wordpress-app-integration.md: Updated two stale "make release creates the tag/GH release" lines.

Test plan

Most of this can only be exercised end-to-end by cutting an actual release, so most of this would have to be tested post-merge.

Local validation (no CI run required)

Exercised locally against the PR branch:

Shell syntax: bash -n on release.sh, bin/release.sh, publish-pr-xcframework.sh.
Fastfile Ruby syntax: ruby -c fastlane/Fastfile.
pipeline.yml YAML parses; every depends_on reference resolves to a declared key:.
Version regex /\Av\d+\.\d+\.\d+(-.+)?\z/ — 15 cases (valid vX.Y.Z, vX.Y.Z-prerelease; rejects bare 0.15.0, v0.15, v0.15.0.1, trailing whitespace, trailing -).
rewrite_resources_mode! against a copy of Package.swift — correct rewrite, idempotent re-rewrite, errors on zero / multiple matches.
Read-only validate-lane probes: git ls-remote --tags origin <tag> and gh release view <tag> against v0.15.0 (exists) and v999.999.999 (doesn't) — both distinguish correctly.
bin/release.sh patch --dry-run in a throwaway worktree on trunk — new flow runs end-to-end: pre-flight → version bump → build → commit → git push origin trunk (no --tags) → "Version bump completed successfully!" with the new [DRY RUN]-prefixed Buildkite trigger instructions. Old Creating git tag / Creating GitHub release steps confirmed gone.
:rocket: step if: gating walked through 6 scenarios in Ruby — trunk + NEW_VERSION triggers; PR + NEW_VERSION blocked; stale branch + NEW_VERSION blocked.

Pipeline-only checks (pre-merge, require a CI run)

A regular trunk push (no NEW_VERSION) hits the existing :s3: step and uploads under gutenbergkit/<commit-sha>/, same as today.
A regular trunk push does not trigger the new :rocket: step.
A PR push hits Publish PR XCFramework, not the new :rocket: step.

Release dry-run (against a throwaway version)

Cleanup after dry-run

Delete the test tag, GH Release, and S3 artifacts.

XCFramework Build

This PR's XCFramework is available for testing. Add the following to your Package.swift:

.package(url: "https://github.com/wordpress-mobile/GutenbergKit", branch: "pr-build/502")

_{Built from ff062d7}

Mirrors the wordpress-rs tag-release flow. `bin/release.sh` stops at bumping versions on trunk; a follow-up Buildkite build kicked off with `NEW_VERSION=v<x.y.z>` then rewrites `Package.swift` to `.release(version:, checksum:)`, tags, and creates the GitHub Release. The tag's commit lives off trunk (parented on the release commit but only reachable via the tag ref), so SPM consumers pinning the tag resolve the prebuilt XCFramework from CDN rather than rebuilding from the local source bundle. This is the precondition for ignoring the committed iOS JS bundle at `ios/Sources/GutenbergKitResources/Gutenberg/` — once a tagged release exists in `.release(...)` mode and WordPress-iOS bumps to it, those files can be dropped from trunk.

Review-feedback follow-up to the publish flow added in this PR. - `validate` lane now passes an explicit `api_token` to `get_github_release` and asserts `GITHUB_API_STATUS_CODE == 200` after the probe. The action returns `nil` for both "no such release" AND for any API failure (401, 404, network), so without the status check an auth-misconfigured probe silently green-lit a publish. - `publish_release_to_github` swaps the `gh release create` shellout for `set_github_release(api_token: …)` (release-toolkit action). No more reliance on the agent's ambient `gh` auth — `use-bot-for-git` only sets `GIT_SSH_COMMAND`, not `GH_TOKEN`. Asset upload, prerelease flag, and auto-generated notes all flow through the action's params. - `release` orchestrator re-invokes `validate(version:, github_token:)` at the top so a misconfigured pipeline can't silently skip it. New `github_token!` helper resolves token from `options` or `ENV`. - Refactored `publish_release_to_github` itself: dropped the staging-branch + draft + flip dance in favour of the simpler `push_git_tags` flow that wordpress-rs uses. `git push <tag>` carries the commit along with the tag ref, so no branch ref ever lives on origin. Tag is the last thing pushed before the GH Release call, so partial failure leaves either nothing (clean re-run) or just the GH Release missing (recoverable manually against the existing tag). - `:s3: Publish XCFramework to S3` step also gated on `build.tag == null` so the auto-triggered tag build doesn't re-upload the same iOS artifact the `:rocket:` step already pushed. Android publish on tag builds is intentionally not gated — it's still load-bearing (produces the canonical `vX.Y.Z` Maven artifact via `--tag-name`). - `bin/release.sh --dry-run` now prints the Buildkite-trigger preview it was previously suppressing, with a `[DRY RUN]` prefix on the leading status line. - Fastfile comment on the `release` lane warns against local invocation (it pushes a tag and creates a real GH Release).

mokagio · 2026-05-15T05:59:06Z

      command: .buildkite/publish-pr-xcframework.sh
      plugins: *plugins

+    - label: ':rocket: Publish Swift release ${NEW_VERSION:-(no version)}'


Technically, this should never resolve without NEW_VERSION, but since there's no compiler, maybe a louder fallback value might help, just in case?

Suggested change

- label: ':rocket: Publish Swift release ${NEW_VERSION:-(no version)}'

- label: ':rocket: Publish Swift release ${NEW_VERSION:-(Error: No version found!)}'

mokagio · 2026-05-15T06:21:11Z

+      # the `build.tag == null` clause skips it. Android publish on tag
+      # builds is still load-bearing (produces the `vX.Y.Z` Maven artifact)
+      # and intentionally not gated here.
+      if: build.pull_request.id == null && build.env("NEW_VERSION") == null && build.tag == null


Nitpick, the other steps have the env var check first and the PR id last

Suggested change

if: build.pull_request.id == null && build.env("NEW_VERSION") == null && build.tag == null

if: build.env("NEW_VERSION") == null && build.tag == null && build.pull_request.id == null

mokagio · 2026-05-15T06:21:21Z

+#!/bin/bash
+set -euo pipefail


Nit

Suggested change

#!/bin/bash

set -euo pipefail

#!/bin/bash

set -euo pipefail

mokagio · 2026-05-15T06:21:58Z

+set -euo pipefail
+
+if [[ -z "${NEW_VERSION:-}" ]]; then
+    echo "ERROR: NEW_VERSION is not set or empty." >&2


Suggested change

echo "ERROR: NEW_VERSION is not set or empty." >&2

echo "ERROR: NEW_VERSION is not set or is empty." >&2

Maybe just me, but I read the original as "is neither set nor empty"

mokagio · 2026-05-15T06:25:48Z

-| Scenario                          | Recommended Method |
-| --------------------------------- | ------------------ |
-| Active feature development        | Local Development  |
-| PR review / testing               | Git Revision       |
-| Merging to WordPress app trunk    | Pre-release        |
-| WordPress app release             | Formal Release     |
+| Scenario                       | Recommended Method |
+| ------------------------------ | ------------------ |
+| Active feature development     | Local Development  |
+| PR review / testing            | Git Revision       |
+| Merging to WordPress app trunk | Pre-release        |
+| WordPress app release          | Formal Release     |


mokagio · 2026-05-15T06:27:29Z

+# tag to origin, uploads to the public S3 bucket, and creates a real GitHub
+# Release. For local diagnosis, invoke `validate`, `update_swift_package`,
+# `publish_to_s3`, or `publish_release_to_github` individually.
+lane :release do |options|


Given the **Don't run this locally** requirement, should we add something like

UI.user_error! "This lane should only run in CI" unless ENV.fetch(["CI"], nil).nil?

mokagio · 2026-05-15T06:28:03Z

+  UI.user_error!("Version #{version.inspect} is not a valid tag name (expected `vMAJOR.MINOR.PATCH` or `vMAJOR.MINOR.PATCH-PRERELEASE`).") \
+    unless version =~ /\Av\d+\.\d+\.\d+(-.+)?\z/
+
+  UI.user_error!("Tag #{version} already exists on the remote.") \
+    if git_tag_exists(tag: version, remote: true, remote_name: 'origin')


Interesting formatting choice over

if ... ... end

mokagio · 2026-05-15T06:31:02Z

+lane :validate do |options|
+  version = required_version!(options)
+  token = github_token!(options)


Out of scope because require_version! predates this code, but I'd say this options parsing approach is redundant when we can pass name arguments to the block

lane :validate do |version:, token:| ...

We'll still need validation logic for the input, such as version.empty? == false but at least we wouldn't have the opaque options container.

mokagio

Looking good.

I say let's merge and ship a pre-release to see how it behaves IRL in CI?

github-actions Bot added the [Type] Build Tooling Issues or PRs related to build tooling label May 11, 2026

jkmassel force-pushed the jkmassel/drop-committed-js-build branch 4 times, most recently from 60af26f to 00d77af Compare May 13, 2026 22:51

jkmassel requested a review from mokagio May 14, 2026 19:03

jkmassel marked this pull request as ready for review May 14, 2026 19:03

jkmassel added 2 commits May 14, 2026 13:03

jkmassel force-pushed the jkmassel/drop-committed-js-build branch from 2d598d7 to ff062d7 Compare May 14, 2026 19:03

mokagio reviewed May 15, 2026

View reviewed changes

mokagio approved these changes May 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ci(ios): publish tagged releases as binary targets via Buildkite#502

ci(ios): publish tagged releases as binary targets via Buildkite#502
jkmassel wants to merge 2 commits into
trunkfrom
jkmassel/drop-committed-js-build

jkmassel commented May 11, 2026 •

edited

Loading

Uh oh!

wpmobilebot commented May 11, 2026 •

edited

Loading

Uh oh!

mokagio May 15, 2026

Uh oh!

mokagio May 15, 2026

Uh oh!

mokagio May 15, 2026

Uh oh!

mokagio May 15, 2026

Uh oh!

mokagio May 15, 2026

Uh oh!

mokagio May 15, 2026

Uh oh!

mokagio May 15, 2026

Uh oh!

mokagio May 15, 2026

Uh oh!

mokagio left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	- label: ':rocket: Publish Swift release ${NEW_VERSION:-(no version)}'
	- label: ':rocket: Publish Swift release ${NEW_VERSION:-(Error: No version found!)}'

	if: build.pull_request.id == null && build.env("NEW_VERSION") == null && build.tag == null
	if: build.env("NEW_VERSION") == null && build.tag == null && build.pull_request.id == null

	echo "ERROR: NEW_VERSION is not set or empty." >&2
	echo "ERROR: NEW_VERSION is not set or is empty." >&2

Conversation

jkmassel commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

How a release works after this

Tag-triggered builds (Android still relies on these)

Changes

Fastfile

Pipeline

Release script

Behavior change: prereleases now get a GitHub Release

Docs

Test plan

Local validation (no CI run required)

Pipeline-only checks (pre-merge, require a CI run)

Release dry-run (against a throwaway version)

Cleanup after dry-run

Related

Uh oh!

wpmobilebot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

XCFramework Build

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mokagio left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jkmassel commented May 11, 2026 •

edited

Loading

wpmobilebot commented May 11, 2026 •

edited

Loading