Skip to content

Commit bdd365a

Browse files
RomneyDaRomneyDa
authored
docs: clarify macOS release workflow refs (#97116)
* docs: clarify macOS release workflow refs * docs: clarify macOS release repo roles * docs: document macOS release approval gate * docs: align maintainer macOS release repo refs
1 parent a82902c commit bdd365a

2 files changed

Lines changed: 111 additions & 68 deletions

File tree

‎.agents/skills/release-openclaw-mac/SKILL.md‎

Lines changed: 51 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: "Run or recover OpenClaw macOS release signing, notarization, appca
55

66
# OpenClaw Mac Release
77

8-
Use with `$release-openclaw-maintainer`, `$release-openclaw-ci`, `$one-password`, and `$release-private` if it exists when stable macOS assets, private mac preflight, notarization, appcast promotion, or mac release recovery is involved.
8+
Use with `$release-openclaw-maintainer`, `$release-openclaw-ci`, `$one-password`, and `$release-private` if it exists when stable macOS assets, release-ops mac preflight, notarization, appcast promotion, or mac release recovery is involved.
99

1010
## Credentials
1111

@@ -23,7 +23,7 @@ Use with `$release-openclaw-maintainer`, `$release-openclaw-ci`, `$one-password`
2323

2424
## GitHub Secrets
2525

26-
Target private repo environment: `openclaw/releases-private`, env `mac-release`.
26+
Target release-ops repo environment: `openclaw/releases`, env `mac-release`.
2727

2828
Set only after local notary auth validation:
2929

@@ -35,12 +35,24 @@ Do not update these from mixed sources. All three ASC fields must come from the
3535

3636
## Workflow Shape
3737

38+
- `openclaw/openclaw` is the public product repo. Its GitHub Releases page is
39+
where macOS assets are ultimately attached.
40+
- `openclaw/openclaw` `macos-release.yml` is public handoff validation only.
41+
It never signs, notarizes, or uploads macOS assets, regardless of
42+
`preflight_only`.
43+
- `openclaw/releases` is the restricted release-ops repo. Its macOS workflows
44+
sign, notarize, validate, and promote assets onto the
45+
`openclaw/openclaw` GitHub release.
3846
- Public release branch may carry mac-only packaging fixes after the stable tag/npm are already live.
39-
- Use `source_ref=release/YYYY.M.PATCH` for private mac preflight/validation when building that branch variation.
47+
- Use `source_ref=release/YYYY.M.PATCH` for release-ops mac preflight/validation when building that branch variation.
4048
- Keep `tag=vYYYY.M.PATCH` pointing at the original stable release commit.
4149
- Real mac publish must reuse:
42-
- a successful private mac preflight run for the same tag/source SHA
43-
- a successful private mac validation run for the same tag/source SHA
50+
- a successful release-ops mac preflight run for the same tag/source SHA
51+
- a successful release-ops mac validation run for the same tag/source SHA
52+
- Release-ops preflight and real publish enter the protected `mac-release`
53+
environment in the `build_sign_and_package` job. Operators may be able to
54+
trigger the workflow while Vincent or another environment reviewer approves
55+
the paused deployment before signing/notarization/promotion proceeds.
4456
- If preflight source SHA differs from tag SHA, validation must also use the same `source_ref`; promotion rejects mismatched proof.
4557

4658
## Notarization
@@ -52,10 +64,25 @@ Do not update these from mixed sources. All three ASC fields must come from the
5264

5365
## Dispatch
5466

55-
Private preflight:
67+
Public handoff validation:
5668

5769
```bash
58-
gh workflow run openclaw-macos-publish.yml --repo openclaw/releases-private --ref main \
70+
gh workflow run macos-release.yml --repo openclaw/openclaw \
71+
--ref release/YYYY.M.PATCH \
72+
-f tag=vYYYY.M.PATCH \
73+
-f preflight_only=true \
74+
-f public_release_branch=release/YYYY.M.PATCH
75+
```
76+
77+
- Use the public release branch as the workflow ref so the Actions list displays
78+
`release/YYYY.M.PATCH`, matching prior stable macOS handoff runs.
79+
- Do not use `--ref main` or `--ref vYYYY.M.PATCH` for this public handoff
80+
validation. The workflow checks out the tag from the `tag` input internally.
81+
82+
Release-ops preflight:
83+
84+
```bash
85+
gh workflow run openclaw-macos-publish.yml --repo openclaw/releases --ref main \
5986
-f tag=vYYYY.M.PATCH \
6087
-f source_ref=release/YYYY.M.PATCH \
6188
-f preflight_only=true \
@@ -64,18 +91,24 @@ gh workflow run openclaw-macos-publish.yml --repo openclaw/releases-private --re
6491
-f public_release_branch=release/YYYY.M.PATCH
6592
```
6693

67-
Private validation for a branch-variation preflight:
94+
Wait for the run to reach the `mac-release` environment approval if GitHub
95+
pauses it, then get approval from Vincent or another configured environment
96+
reviewer. Record the successful preflight run id.
97+
98+
Release-ops validation for a branch-variation preflight:
6899

69100
```bash
70-
gh workflow run openclaw-macos-validate.yml --repo openclaw/releases-private --ref main \
101+
gh workflow run openclaw-macos-validate.yml --repo openclaw/releases --ref main \
71102
-f tag=vYYYY.M.PATCH \
72103
-f source_ref=release/YYYY.M.PATCH
73104
```
74105

106+
Record the successful validation run id.
107+
75108
Real publish:
76109

77110
```bash
78-
gh workflow run openclaw-macos-publish.yml --repo openclaw/releases-private --ref main \
111+
gh workflow run openclaw-macos-publish.yml --repo openclaw/releases --ref main \
79112
-f tag=vYYYY.M.PATCH \
80113
-f preflight_only=false \
81114
-f smoke_test_only=false \
@@ -85,6 +118,14 @@ gh workflow run openclaw-macos-publish.yml --repo openclaw/releases-private --re
85118
-f public_release_branch=release/YYYY.M.PATCH
86119
```
87120

121+
Wait for the `mac-release` environment approval again if GitHub pauses the real
122+
publish run before it promotes assets.
123+
124+
- Release-ops `openclaw/releases` publish/validate workflows run from their own
125+
trusted `main` workflow ref. Real publish has a guard that rejects any other
126+
workflow ref. That displayed `main` ref is expected; the public OpenClaw
127+
source is selected by `tag` and optional `source_ref`.
128+
88129
## Verify
89130

90131
- `gh release view vYYYY.M.PATCH --repo openclaw/openclaw` shows zip, dmg, dSYM zip, not draft, not prerelease.

‎.agents/skills/release-openclaw-maintainer/SKILL.md‎

Lines changed: 60 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -203,8 +203,9 @@ Stable publication is not complete until `main` carries the actual shipped relea
203203
validation-only release machinery. If mac packaging needs release-branch-only
204204
fixes after the stable npm package or GitHub tag is already published, do not
205205
create a `vYYYY.M.PATCH-N` correction tag just to change the workflow source.
206-
Dispatch the private mac workflows for the original `tag=vYYYY.M.PATCH` with
207-
`source_ref=release/YYYY.M.PATCH` and `public_release_branch=release/YYYY.M.PATCH`;
206+
Dispatch the release-ops mac workflows for the original `tag=vYYYY.M.PATCH`
207+
with `source_ref=release/YYYY.M.PATCH` and
208+
`public_release_branch=release/YYYY.M.PATCH`;
208209
provenance checks must prove the source SHA descends from the tag and
209210
validation/preflight use the same source. Reserve `vYYYY.M.PATCH-N` correction
210211
tags for emergency hotfixes that must publish a new npm package/release
@@ -579,8 +580,8 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
579580
- Actual npm install/update phases are capped at 5 minutes. If `npm install -g`, installer package install, or `openclaw update` takes longer than 300s in release e2e, stop treating the run as healthy progress and debug the installer/updater or harness.
580581
- Serialize host build/package mutations ahead of VM lanes. Finish `pnpm build`, `pnpm ui:build`, `pnpm release:check`, install smoke, and any Docker/package-prep lanes before starting Parallels `npm pack` lanes; otherwise `dist` can disappear during VM pack prep and produce false failures.
581582
- Include mac release readiness in preflight by running the public validation
582-
workflow in `openclaw/openclaw` and the real mac preflight in
583-
`openclaw/releases-private` for every release.
583+
workflow in `openclaw/openclaw` and the release-ops mac preflight in
584+
`openclaw/releases` for every release.
584585
- Treat the `appcast.xml` update on `main` as part of mac release readiness, not an optional follow-up.
585586
- The workflows remain tag-based. The agent is responsible for making sure
586587
preflight runs complete successfully before any publish run starts.
@@ -608,16 +609,16 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
608609
## Use the right auth flow
609610

610611
- OpenClaw publish uses GitHub trusted publishing.
611-
- Stable npm promotion from `beta` to `latest` uses the private
612-
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
613-
workflow because `npm dist-tag` management needs `NPM_TOKEN`, while the
614-
public npm release workflow stays OIDC-only.
615-
- Prefer fixing the private workflow token path over any local 1Password
616-
fallback. The desired setup is a granular npm token stored as the private
612+
- Stable npm promotion from `beta` to `latest` uses the restricted release-ops
613+
`openclaw/releases/.github/workflows/openclaw-npm-dist-tags.yml` workflow
614+
because `npm dist-tag` management needs `NPM_TOKEN`, while the public npm
615+
release workflow stays OIDC-only.
616+
- Prefer fixing the release-ops workflow token path over any local 1Password
617+
fallback. The desired setup is a granular npm token stored as the release-ops
617618
repo's `NPM_TOKEN` secret, scoped to the `openclaw` package with read/write
618619
and 2FA bypass for automation.
619-
- If the private dist-tag workflow cannot promote because `NPM_TOKEN` is absent
620-
or stale, use the local tmux + 1Password fallback:
620+
- If the release-ops dist-tag workflow cannot promote because `NPM_TOKEN` is
621+
absent or stale, use the local tmux + 1Password fallback:
621622
- Start or reuse a tmux session so interactive `npm login` and OTP prompts
622623
are observable and recoverable.
623624
- Hard rule: never run `op` directly in the main agent shell during release
@@ -635,21 +636,21 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
635636
- Verify with a cache-bypassed registry read, for example:
636637
`npm view openclaw dist-tags --json --prefer-online --cache /tmp/openclaw-npm-cache-verify-$$`
637638
and `npm view openclaw@latest version dist.tarball --json --prefer-online`.
638-
- Direct stable publishes can also use that private dist-tag workflow to point
639-
`beta` at the already-published `latest` version when the operator wants both
640-
tags aligned immediately.
639+
- Direct stable publishes can also use that release-ops dist-tag workflow to
640+
point `beta` at the already-published `latest` version when the operator wants
641+
both tags aligned immediately.
641642
- The publish run must be started manually with `workflow_dispatch`.
642-
- The npm workflow and the private mac publish workflow accept
643+
- The npm workflow and the release-ops mac publish workflow accept
643644
`preflight_only=true` to run validation/build/package steps without uploading
644645
public release assets.
645646
- Real npm publish requires a prior successful npm preflight run id and the
646647
successful Full Release Validation run id for the same tag/SHA so the publish
647648
job promotes the prepared tarball instead of rebuilding it and attaches the
648649
correct release evidence.
649-
- Real private mac publish requires a prior successful private mac preflight
650-
run id so the publish job promotes the prepared artifacts instead of
650+
- Real release-ops mac publish requires a prior successful release-ops mac
651+
preflight run id so the publish job promotes the prepared artifacts instead of
651652
rebuilding or renotarizing them again.
652-
- The private mac workflow also accepts `smoke_test_only=true` for branch-safe
653+
- The release-ops mac workflow also accepts `smoke_test_only=true` for branch-safe
653654
workflow smoke tests that use ad-hoc signing, skip notarization, skip shared
654655
appcast generation, and do not prove release readiness.
655656
- `preflight_only=true` on the npm workflow is also the right way to validate an
@@ -670,27 +671,27 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
670671
use only `main` or `release/YYYY.M.PATCH`.
671672
- `.github/workflows/macos-release.yml` in `openclaw/openclaw` is now a
672673
public validation-only handoff. It validates the tag/release state and points
673-
operators to the private repo. It still rebuilds the JS outputs needed for
674+
operators to the release-ops repo. It still rebuilds the JS outputs needed for
674675
release validation, but it does not sign, notarize, or publish macOS
675676
artifacts.
676-
- `openclaw/releases-private/.github/workflows/openclaw-macos-validate.yml`
677-
is the required private mac validation lane for `swift test`; keep it green
677+
- `openclaw/releases/.github/workflows/openclaw-macos-validate.yml` is the
678+
required release-ops mac validation lane for `swift test`; keep it green
678679
before any real stable mac publish run starts.
679680
- Real mac preflight and real mac publish both use
680-
`openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml`.
681-
- The private mac validation lane runs on GitHub's standard macOS runner.
682-
- The private mac preflight path runs on GitHub's xlarge macOS runner and uses
681+
`openclaw/releases/.github/workflows/openclaw-macos-publish.yml`.
682+
- The release-ops mac validation lane runs on GitHub's standard macOS runner.
683+
- The release-ops mac preflight path runs on GitHub's xlarge macOS runner and uses
683684
a SwiftPM cache because the build/sign/notarize/package path is CPU-heavy.
684-
- Private mac preflight uploads notarized build artifacts as workflow artifacts
685-
instead of uploading public GitHub release assets.
686-
- Private smoke-test runs upload ad-hoc, non-notarized build artifacts as
685+
- Release-ops mac preflight uploads notarized build artifacts as workflow
686+
artifacts instead of uploading public GitHub release assets.
687+
- Release-ops smoke-test runs upload ad-hoc, non-notarized build artifacts as
687688
workflow artifacts and intentionally skip stable `appcast.xml` generation.
688689
- For stable releases, npm preflight, Full Release Validation, public mac
689-
validation, private mac validation, and private mac preflight must all pass
690-
before any real publish run starts. For beta releases, npm preflight and Full
691-
Release Validation must pass before npm publish unless the operator explicitly
692-
waives the full gate; mac beta validation is still only required when
693-
requested.
690+
validation, release-ops mac validation, and release-ops mac preflight must all
691+
pass before any real publish run starts. For beta releases, npm preflight and
692+
Full Release Validation must pass before npm publish unless the operator
693+
explicitly waives the full gate; mac beta validation is still only required
694+
when requested.
694695
- Real publish runs may be dispatched from `main` or from a
695696
`release/YYYY.M.PATCH` branch. For release-branch runs, the tag must be contained
696697
in that release branch, and the real publish must reuse a successful preflight
@@ -699,21 +700,21 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
699700
rather than workflow-level SHA pinning.
700701
- The `npm-release` environment must be approved by `@openclaw/openclaw-release-managers` before publish continues.
701702
- Mac publish uses
702-
`openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml` for
703-
private mac preflight artifact preparation and real publish artifact
703+
`openclaw/releases/.github/workflows/openclaw-macos-publish.yml` for
704+
release-ops mac preflight artifact preparation and real publish artifact
704705
promotion.
705-
- Real private mac publish uploads the packaged `.zip`, `.dmg`, and
706+
- Real release-ops mac publish uploads the packaged `.zip`, `.dmg`, and
706707
`.dSYM.zip` assets to the existing GitHub release in `openclaw/openclaw`
707708
automatically when `OPENCLAW_PUBLIC_REPO_RELEASE_TOKEN` is present in the
708-
private repo `mac-release` environment.
709+
release-ops repo `mac-release` environment.
709710
- For stable releases, the agent must also download the signed
710-
`macos-appcast-<tag>` artifact from the successful private mac workflow and
711-
then update `appcast.xml` on `main`.
711+
`macos-appcast-<tag>` artifact from the successful release-ops mac workflow
712+
and then update `appcast.xml` on `main`.
712713
- For beta mac releases, do not update the shared production `appcast.xml`
713714
unless a separate beta Sparkle feed exists.
714-
- The private repo targets a dedicated `mac-release` environment. If the GitHub
715-
plan does not yet support required reviewers there, do not assume the
716-
environment alone is the approval boundary; rely on private repo access and
715+
- The release-ops repo targets a dedicated `mac-release` environment. If the
716+
GitHub plan does not yet support required reviewers there, do not assume the
717+
environment alone is the approval boundary; rely on restricted repo access and
717718
CODEOWNERS until those settings can be enabled.
718719
- Do not use `NPM_TOKEN` or the plugin OTP flow for the OpenClaw package
719720
publish path; package publishing uses trusted publishing.
@@ -800,12 +801,12 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
800801
18. For stable releases, start `.github/workflows/macos-release.yml` in
801802
`openclaw/openclaw` and wait for the public validation-only run to pass.
802803
19. For stable releases, start
803-
`openclaw/releases-private/.github/workflows/openclaw-macos-validate.yml`
804-
with the same tag and wait for the private mac validation lane to pass.
804+
`openclaw/releases/.github/workflows/openclaw-macos-validate.yml` with the
805+
same tag and wait for the release-ops mac validation lane to pass.
805806
20. For stable releases, start
806-
`openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml`
807-
with `preflight_only=true` and wait for it to pass. Save that run id because
808-
the real publish requires it to reuse the notarized mac artifacts.
807+
`openclaw/releases/.github/workflows/openclaw-macos-publish.yml` with
808+
`preflight_only=true` and wait for it to pass. Save that run id because the
809+
real publish requires it to reuse the notarized mac artifacts.
809810
21. If any preflight or validation run fails, fix the issue on a new commit,
810811
delete the tag and any accidental draft/incomplete GitHub release, recreate
811812
the tag from the fixed commit, and rerun all relevant preflights from
@@ -861,22 +862,23 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
861862
promotion roster when the matching beta already carried the full confidence
862863
pass: published npm postpublish verify, Docker install/update smoke,
863864
macOS-only Parallels install/update smoke, and required QA signal.
864-
Then start the private
865-
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
866-
workflow to promote that stable version from `beta` to `latest`, then
867-
verify `latest` now points at that version.
865+
Then start the restricted release-ops
866+
`openclaw/releases/.github/workflows/openclaw-npm-dist-tags.yml` workflow
867+
to promote that stable version from `beta` to `latest`, then verify
868+
`latest` now points at that version.
868869
29. If the stable release was published directly to `latest` and `beta` should
869-
follow it, start that same private dist-tag workflow to point `beta` at the
870-
stable version, then verify both `latest` and `beta` point at that version.
870+
follow it, start that same release-ops dist-tag workflow to point `beta` at
871+
the stable version, then verify both `latest` and `beta` point at that
872+
version.
871873
30. For stable releases, start
872-
`openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml`
873-
for the real publish with the successful private mac `preflight_run_id` and
874-
wait for success.
875-
31. Verify the successful real private mac run uploaded the `.zip`, `.dmg`,
874+
`openclaw/releases/.github/workflows/openclaw-macos-publish.yml` for the
875+
real publish with the successful release-ops mac `preflight_run_id` and wait
876+
for success.
877+
31. Verify the successful real release-ops mac run uploaded the `.zip`, `.dmg`,
876878
and `.dSYM.zip` artifacts to the existing GitHub release in
877879
`openclaw/openclaw`.
878880
32. For stable releases, download `macos-appcast-<tag>` from the successful
879-
private mac run, update `appcast.xml` on `main`, verify the feed, then
881+
release-ops mac run, update `appcast.xml` on `main`, verify the feed, then
880882
complete the **Close stable releases on main** gate.
881883
33. For beta releases, publish the mac assets only when intentionally requested;
882884
expect no shared production

0 commit comments

Comments
 (0)