buildspace-ci-cd

BuildSpace 发布工作流技能

使用此技能可在使用可复用 GitHub Actions 工作流的代码仓库中设置或调试由 BuildSpace 驱动的发布自动化。

BuildSpace 提供的功能

BuildSpace 分为两层：

• 工作流：位于 .github/workflows/* 下的完整发布流水线。
• 构建块：位于 .github/blocks/* 下的可复用复合操作，适用于自定义流水线。

默认建议：使用预构建工作流，除非用户明确需要自定义行为。

工作流选择

根据项目类型，恰好选择一个主要工作流：

项目类型	工作流文件	触发条件
Rust 二进制文件／库	rust-service-release.yaml	PR 标签 release
TypeScript／JavaScript 单一包	typescript-service-release.yaml	PR 标签 release
TypeScript monorepo（多个包）	typescript-monorepo-release.yaml	PR 标签 release
Go 二进制文件	go-service-release.yaml	PR 标签 release
Swift macOS .pkg（含已编译二进制文件）	swift-release.yml	PR 标签 release
不含二进制文件的 macOS .pkg（仅含有效载荷／脚本）	pkg-release.yml	PR 标签 release
macOS .pkg PR 构建（仅含有效载荷／脚本）	pkg-release-pr.yml	每次 PR 提交
Swift macOS .pkg PR 构建预览	swift-pkg-pr.yml	每次 PR 提交
macOS dylib 发布（Xcode workspace）	dylib-release.yml	PR 标签 release
macOS dylib 发布（Makefile）	makefile-dylib-release.yml	PR 标签 release
通用发布（仅版本号 + GitHub Release）	release.yaml	PR 标签 release
PR 上的 README 最新性检查	check-readme.yaml	每个 PR
PR 上的 Skills 文档最新性检查	check-skills.yaml	每个 PR

必需的输入、密钥和权限

编写 YAML 之前，务必核实以下内容：

1. 输入：服务／包名称、路径、构建命令、包列表、Homebrew tap 信息、Jamf 配置。
2. 密钥：
   • AI 功能始终需要：OPENAI_API_KEY
   • 发布 npm 包：NPM_TOKEN
   • 发布 crates：CARGO_REGISTRY_TOKEN
   • Swift 编译时环境变量：SECRET_ENV_VARS
   • Jamf 上传：JAMF_CLIENT_ID + JAMF_CLIENT_SECRET
   • 推送到受保护分支或更新 Homebrew tap：APP_ID + APP_PRIVATE_KEY
   • Skills 文档检查（私有代码仓库）：SKILLS_REPO_TOKEN
   • 注意：DEVELOPER_ID_INSTALLER_NAME 已弃用且会被忽略——软件包始终不签名。
3. 权限：
   • 发布／版本号递增作业需要 contents: write
   • 标签检查需要 pull-requests: read
   • PR 评论需要 pull-requests: write

发布触发规则（重要）

BuildSpace 默认通过标签控制触发。

• 标准发布标签：release
• 可选的预发布标签：prerelease
• 通常没有标签就不会运行发布作业。

需要准确理解的行为细节：

• typescript-monorepo-release 直接支持预发布流程。
• typescript-service-release、rust-service-release 和 go-service-release 会通过 release 标签（或强制输入）控制发布作业，并在发布流程启动后将预发布视为一种发布类型。
• swift-release、pkg-release、dylib-release 和 makefile-dylib-release 仅检查 release。
• release.yaml（通用）会检查 release 标签，并支持通过 release 布尔输入强制触发。

实施流程

在收到在代码仓库中设置 BuildSpace 的请求时：

1. 检测代码仓库类型（Rust、单体 TS、TS 单仓库、Go、Swift、macOS pkg、dylib）。
2. 确认发布目标（仅 GitHub、npm、crates、Jamf、Homebrew tap）。
3. 在用户的代码仓库中创建调用工作流（.github/workflows/release.yaml 或 ci.yaml），并使用 photon-hq/buildspace/...@v1。
4. 为该工作流准确配置 with: 输入和 secrets:。
5. 添加建议的权限区块。
6. 除非用户要求立即发布，否则首次验证运行时添加 dry-run: true。
7. 说明如何触发（添加 release 标签并合并路径，或强制设置 release: true）。
8. 对于单仓库，验证 packages JSON 和依赖顺序行为。
9. 对于 Homebrew tap 更新，配置 tap-repo 和 tap-formula 输入，以及 APP_ID/APP_PRIVATE_KEY 密钥。
10. 对于 Jamf 上传，配置 jamf-url 和 Jamf 密钥。

工作流参考

rust-service-release.yaml

Rust 服务的完整发布流水线：标签检查、AI 版本号与发布说明、跨平台构建（Linux x64、macOS ARM64、Windows x64）、同步工作区 crate 版本、向 crates.io 发布 crate、创建包含二进制文件的 GitHub Release，并可选择更新 Homebrew tap。

输入：

输入	类型	必填	默认值	描述
service-name	string	是	—	服务的显示名称
binary-name	string	是	—	Cargo.toml 中的二进制文件名称
binary-path	string	否	""	crate 目录的路径（例如 crates/client）
crates	string	否	[]	按依赖顺序发布的 crate 路径 JSON 数组
build-env	string	否	""	编译时环境变量（例如 BASE_URL=https://...）
labels-to-check	string	否	["release", "prerelease"]	触发发布的 PR 标签
prerelease	boolean	否	false	强制预发布（添加 -rc.N 后缀）
release	boolean	否	false	强制发布（绕过标签检查）
dry-run	boolean	否	false	测试但不实际发布
tap-repo	string	否	""	Homebrew tap 代码仓库（例如 photon-hq/homebrew-photon）。留空则跳过。
tap-formula	string	否	""	tap 中的 Formula 名称（例如 jamf-package-updater）。设置 tap-repo 时必填。

密钥：

密钥	必填	描述
OPENAI_API_KEY	是	用于 AI 驱动的版本号生成和发布说明
CARGO_REGISTRY_TOKEN	否	crates.io API 令牌（发布时必需）
APP_ID	否	GitHub App ID（用于受保护分支和 Homebrew tap 更新）
APP_PRIVATE_KEY	否	GitHub App 私钥

typescript-service-release.yaml

单个 TypeScript/JavaScript 包的完整发布流水线：标签检查、AI 版本号与发布说明、升级 package.json、创建 GitHub Release，并发布到 npm。

输入：

输入	类型	必填	默认值	描述
service-name	string	是	—	服务的显示名称
bun-version	string	否	latest	要使用的 Bun 版本
npm-tag	string	否	latest	npm dist-tag（例如 latest、beta、next）
no-npm-publish	boolean	否	false	跳过 npm 发布（仅创建 GitHub Release）
working-directory	string	否	.	包含 package.json 的目录
build-command	string	否	bun run build	要运行的构建命令
labels-to-check	string	否	["release", "prerelease"]	触发发布的 PR 标签
prerelease	boolean	否	false	强制预发布
release	boolean	否	false	强制发布（绕过标签检查）
dry-run	boolean	否	false	测试但不实际发布

密钥：

密钥	必填	描述
OPENAI_API_KEY	是	用于 AI 驱动的版本号生成和发布说明
NPM_TOKEN	否	npm 身份验证令牌（发布时必需）

typescript-monorepo-release.yaml

面向独立版本管理的 TypeScript 单体仓库的完整发布流水线。检测发生变更的包，按依赖顺序进行拓扑排序，通过一次 AI 调用生成所有版本号和发布说明，更新各个 package.json，创建带有 release/YYYY-MM-DD.N 标签的 GitHub Release，并按顺序发布到 npm。

输入：

输入	类型	必填	默认值	描述
service-name	string	是	—	单体仓库的显示名称
packages	string	是	—	JSON 数组：[{"name":"pkg","path":"packages/pkg"}]
bun-version	string	否	latest	要使用的 Bun 版本
npm-tag	string	否	latest	npm dist-tag
build-command	string	否	bun run build	每个包的构建命令（如果设置了 root-build-command，则忽略）
root-build-command	string	否	""	在仓库根目录构建一次（例如 turbo build）
include-dependents	boolean	否	false	同时发布下游依赖项
labels-to-check	string	否	["release", "prerelease"]	触发发布的 PR 标签
prerelease	boolean	否	false	强制预发布
release	boolean	否	false	强制发布
dry-run	boolean	否	false	进行测试，但不实际发布

密钥：

密钥	必填	描述
OPENAI_API_KEY	是	用于 AI 版本管理和生成发布说明
NPM_TOKEN	是	npm 身份验证令牌
APP_ID	否	GitHub App ID（用于推送到受保护的分支）
APP_PRIVATE_KEY	否	GitHub App 私钥

go-service-release.yaml

面向 Go 二进制文件的完整发布流水线：检查标签、通过 AI 生成版本号和发布说明、为 macOS（ARM64）和 Linux（AMD64）进行交叉编译、创建包含二进制文件的 GitHub Release，并可选择更新 Homebrew tap。

输入：

输入	类型	必填	默认值	描述
service-name	string	是	—	服务的显示名称
binary-name	string	是	—	输出二进制文件的名称
go-version	string	否	stable	要使用的 Go 版本
build-flags	string	否	""	额外的 go build 标志
ldflags	string	否	-s -w	链接器标志
labels-to-check	string	否	["release", "prerelease"]	触发发布的 PR 标签
prerelease	boolean	否	false	强制预发布
release	boolean	否	false	强制发布
tap-repo	string	否	""	Homebrew tap 仓库。留空则跳过。
tap-formula	string	否	""	tap 中的 formula 名称。设置 tap-repo 时必填。

密钥：

密钥	必填	描述
OPENAI_API_KEY	是	用于 AI 版本管理和生成发布说明
APP_ID	否	GitHub App ID（用于更新 Homebrew tap）
APP_PRIVATE_KEY	否	GitHub App 私钥

swift-release.yml

用于 macOS .pkg 分发的完整发布流水线，包含已编译的 Swift 二进制文件：标签检查、AI 版本号与发布说明、Swift 构建、创建 .pkg（未签名）、GitHub Release，以及可选的 Jamf 上传。

输入：

输入	类型	必填	默认值	描述
package-name	string	是	—	Swift 二进制文件／软件包的名称
identifier	string	是	—	软件包标识符（例如，com.example.mytool）
scripts-path	string	否	""	脚本目录的路径，目录中包含 preinstall/postinstall 脚本
payload-path	string	否	""	其他负载目录的路径（与安装根目录结构一致）
jamf-url	string	否	""	Jamf Pro 实例 URL（留空则跳过）
jamf-package-priority	string	否	""	Jamf Pro 中的软件包优先级
jamf-package-name	string	否	""	用于在 Jamf Pro 中匹配的软件包名称

密钥：

密钥	必填	描述
OPENAI_API_KEY	是	用于 AI 驱动的版本号和发布说明
SECRET_ENV_VARS	否	写入 .env 的编译时环境变量
JAMF_CLIENT_ID	否	Jamf Pro API 客户端 ID
JAMF_CLIENT_SECRET	否	Jamf Pro API 客户端密钥

pkg-release.yml

用于 macOS .pkg 的发布流水线，不包含已编译的二进制文件。将负载文件和脚本打包到 .pkg 中，创建 GitHub Release，并可选择上传到 Jamf。当软件包仅提供配置文件、LaunchDaemons、脚本或其他非二进制负载时，请使用此流水线代替 swift-release。

输入：

输入	类型	必填	默认值	描述
package-name	string	是	—	软件包名称
identifier	string	是	—	软件包标识符（例如，com.example.my-config）
scripts-path	string	否	""	脚本目录的路径，目录中包含 preinstall/postinstall 脚本
payload-path	string	否	""	负载目录的路径（与安装根目录结构一致）
jamf-url	string	否	""	Jamf Pro 实例 URL（留空则跳过）
jamf-package-priority	string	否	""	Jamf Pro 中的软件包优先级
jamf-package-name	string	否	""	用于在 Jamf Pro 中匹配的软件包名称

密钥：

密钥	必填	描述
OPENAI_API_KEY	是	用于 AI 驱动的版本号和发布说明
JAMF_CLIENT_ID	否	Jamf Pro API 客户端 ID
JAMF_CLIENT_SECRET	否	Jamf Pro API 客户端密钥

pkg-release-pr.yml

每次 PR 提交时构建 macOS .pkg（不含已编译的二进制文件），并在 PR 中通过持续更新的评论报告状态。体验与 swift-pkg-pr 相同，但适用于仅包含负载／脚本的软件包。新提交会自动取消已过时的进行中构建。

输入：

输入	类型	必填	默认值	描述
package-name	string	是	—	软件包名称
identifier	string	是	—	软件包标识符（例如，com.example.my-config）
scripts-path	string	否	""	脚本目录的路径，目录中包含 preinstall/postinstall 脚本
payload-path	string	否	""	负载目录的路径（与安装根目录结构一致）

swift-pkg-pr.yml

每次 PR 提交时构建 macOS .pkg（包含 Swift 二进制文件），发布／更新一条 PR 评论以显示构建状态，并上传构建产物（保留 7 天）。新提交会自动取消已过时的进行中构建。

输入：

输入	类型	必填	默认值	描述
package-name	string	是	—	Swift 二进制文件／软件包的名称
identifier	string	是	—	软件包标识符（例如，com.example.mytool）
scripts-path	string	否	""	脚本目录的路径，目录中包含 preinstall/postinstall 脚本

密钥：

密钥	必填	描述
SECRET_ENV_VARS	否	写入 .env 的编译时环境变量

dylib-release.yml

macOS 动态库发布流水线，基于使用 CocoaPods 的 Xcode 工作区构建。检查标签、使用 AI 生成版本号和发布说明、安装 CocoaPods、构建 dylib（arm64e），并创建包含 .dylib 构件的 GitHub Release。

输入：

输入	类型	必填	默认值	说明
workspace	string	是	—	.xcworkspace 的路径
scheme	string	是	—	要构建的 Xcode scheme
dylib-name	string	是	—	输出 dylib 的名称（例如，BlueBubblesHelper）
project-directory	string	是	—	包含 Podfile 的目录

密钥：

密钥	必填	说明
OPENAI_API_KEY	是	用于 AI 驱动的版本管理和发布说明

makefile-dylib-release.yml

macOS 动态库发布流水线，使用 Makefile 构建。检查标签、使用 AI 生成版本号和发布说明、运行 make release，并创建包含 .dylib 构件的 GitHub Release。

输入：

输入	类型	必填	默认值	说明
dylib-name	string	是	—	输出 dylib 的名称（例如，imessage-helper）

密钥：

密钥	必填	说明
OPENAI_API_KEY	是	用于 AI 驱动的版本管理和发布说明

release.yaml

通用发布流水线，适用于只需要 AI 驱动的版本管理和 GitHub Release 的项目（无需构建步骤，也无需发布软件包）。适用于配置仓库、文档仓库，或任何只需要带标签发布的项目。

输入：

输入	类型	必填	默认值	说明
service-name	string	是	—	服务的显示名称
labels-to-check	string	否	["release"]	要检查的 PR 标签的 JSON 数组
release	boolean	否	false	强制发布（覆盖标签设置）

密钥：

密钥	必填	说明
OPENAI_API_KEY	是	用于 AI 驱动的版本管理和发布说明

check-readme.yaml

在每个 PR 上运行，检查 README.md 是否与更改同步。使用 AI 对照 README 分析已更改的文件，并自动发布或移除 PR 评论。

输入：

输入	类型	必填	默认值	说明
blocking	boolean	否	false	如果为 true，则在 README 过时的情况下使工作流失败。如果为 false，则仅发布警告评论。

密钥：

密钥	必填	说明
OPENAI_API_KEY	是	用于 AI 驱动的 README 分析

check-skills.yaml

在每个 PR 上运行，检查技能文档（位于单独的技能仓库中）是否与更改同步。使用 AI 对照技能 SKILL.md 文件分析已更改的文件，并自动发布或移除 PR 评论。

输入：

输入	类型	必填	默认值	说明
fail_on_missing_skills	boolean	否	false	如果为 true，则在技能文档过时的情况下使工作流失败。如果为 false，则仅发布警告评论。
skills-repo	string	否	photon-hq/skills	用于比对的技能仓库（格式为 owner/repo）

密钥：

密钥	必填	说明
OPENAI_API_KEY	是	用于 AI 驱动的技能分析
SKILLS_REPO_TOKEN	否	用于技能仓库的 GitHub 令牌（默认使用 GITHUB_TOKEN；私有仓库请使用 PAT）

Monorepo 专属指南

对于 typescript-monorepo-release：

• packages 输入必须是 JSON 数组： [{"name":"pkg","path":"packages/pkg"}]
• 更改的软件包通过与上次发布标签的差异来检测。
• 根据本地依赖关系边对软件包进行拓扑排序。
• 设置 include-dependents: true 可将下游软件包纳入发布。
• root-build-command 优先于各软件包的 build-command。
• 预发布生效时，npm 标签会自动设为 beta。
• 由于没有单一版本号，因此使用基于日期的 release/YYYY-MM-DD.N 标签。

Rust/Go 说明

• Rust 工作流可以：
  • 为 Linux x64、macOS ARM64 和 Windows x64 交叉构建产物
  • 在所有 crate 之间同步工作区版本
  • 按指定顺序发布 crate
  • 可选更新 Homebrew tap（tap-repo + tap-formula，需要 APP_ID + APP_PRIVATE_KEY）
• Go 工作流：
  • 为 macOS ARM64 和 Linux AMD64 交叉构建
  • 也可以更新 Homebrew tap（tap-repo + tap-formula，需要 APP_ID + APP_PRIVATE_KEY）

Swift / macOS .pkg 说明

• swift-release 会构建 Swift 二进制文件、创建未签名的 .pkg、创建 GitHub Release，并可选上传到 Jamf。
• pkg-release 适用于不包含已编译二进制文件的 .pkg 包——仅包含有效载荷文件和/或脚本。
• swift-pkg-pr 和 pkg-release-pr 是对应的 PR 预览工作流（每次提交都会构建，并在 PR 中发表评论）。
• 包始终未签名（DEVELOPER_ID_INSTALLER_NAME 已弃用且会被忽略）。
• 编译时环境变量通过 SECRET_ENV_VARS 密钥传入（写入 .env）。
• Jamf 上传是可选的——设置 jamf-url 输入，并提供 JAMF_CLIENT_ID + JAMF_CLIENT_SECRET 密钥。

Dylib 说明

• dylib-release.yml 适用于使用 CocoaPods 的 Xcode 工作区项目。构建 arm64e dylib。
• makefile-dylib-release.yml 适用于使用 Makefile 的项目。运行 make release 并嵌入版本号。
• 两者都会创建 GitHub Release，并将 .dylib 作为构建产物。

README 检查指南

使用 check-readme.yaml 检测 PR 文档是否与实际情况不符：

• blocking: false（默认）：仅发布警告评论。
• blocking: true：当 README 看起来已过时，任务会失败。
• 需要 OPENAI_API_KEY 和 PR 评论写入权限。

Skills 检查指南

使用 check-skills.yaml 检测 skills 文档是否与实际情况不符：

• fail_on_missing_skills: false（默认）：仅发布警告评论。
• fail_on_missing_skills: true：当 skills 看起来已过时时，任务会失败。
• 需要 OPENAI_API_KEY 和 PR 评论写入权限。
• 对于私有 skills 仓库，需提供 SKILLS_REPO_TOKEN（具有仓库访问权限的 PAT）。

Blocks 参考

所有 blocks 均位于 .github/blocks/ 下。工作流会在内部组合这些 blocks——仅在自定义流水线中直接使用它们。

版本与发布信息

Block	Path	用途
determine-publish-version	.github/blocks/determine-publish-version/action.yaml	由 AI 生成下一个语义化版本（独立运行，不生成发布说明）
generate-release-info	.github/blocks/generate-release-info/action.yaml	通过一个步骤由 AI 生成版本号和发布说明
create-github-release	.github/blocks/create-github-release/action.yaml	创建 GitHub Release，可选附加构建产物

标签与 PR 交互

Block	Path	用途
check-pr-label	.github/blocks/check-pr-label/action.yaml	检查 PR 标签，以决定是否触发发布
comment-on-pr	.github/blocks/comment-on-pr/action.yaml	发布或更新单条 PR 评论（通过 comment-key 实现幂等）
check-readme	.github/blocks/check-readme/action.yaml	由 AI 检查 README 是否保持最新
check-skills	.github/blocks/check-skills/action.yaml	由 AI 检查 skills 文档是否保持最新

构建模块

模块	路径	用途
rust-build	.github/blocks/rust-build/action.yaml	为目标三元组构建 Rust 二进制文件
go-build	.github/blocks/go-build/action.yaml	为目标 OS/架构构建 Go 二进制文件
typescript-build	.github/blocks/typescript-build/action.yaml	使用 Bun 构建 TypeScript 项目
swift-build	.github/blocks/swift-build/action.yml	构建 Swift 二进制文件（SPM，支持注入 .env）
swift-pkg	.github/blocks/swift-pkg/action.yml	根据二进制文件和/或载荷/脚本创建 macOS .pkg
build-dylib	.github/blocks/build-dylib/action.yml	根据 Xcode 工作区构建 macOS dylib（arm64e）
build-makefile-dylib	.github/blocks/build-makefile-dylib/action.yml	根据 Makefile 构建 macOS dylib
install-cocoapods	.github/blocks/install-cocoapods/action.yml	缓存并安装 CocoaPods 依赖项

发布模块

模块	路径	用途
publish-npm	.github/blocks/publish-npm/action.yaml	将单个包发布到 npm
publish-npm-packages	.github/blocks/publish-npm-packages/action.yaml	按依赖顺序将多个 monorepo 包发布到 npm
publish-crates	.github/blocks/publish-crates/action.yaml	按顺序将工作区 crates 发布到 crates.io
bump-npm-version	.github/blocks/bump-npm-version/action.yaml	更新 package.json 中的版本并推送
bump-monorepo-versions	.github/blocks/bump-monorepo-versions/action.yaml	使用 AI 更新所有发生变更的 monorepo 包的版本
sync-crates-version	.github/blocks/sync-crates-version/action.yaml	为所有 Rust 工作区 crates 设置统一版本
update-tap	.github/blocks/update-tap/action.yaml	更新 Homebrew tap 配方（自动计算 npm/Go/预构建包的 SHA256）
detect-changed-packages	.github/blocks/detect-changed-packages/action.yaml	检测发生变更的 monorepo 包，并按拓扑顺序返回

故障排除清单

如果发布流程未运行：

• 确认 PR 在合并前带有预期标签。
• 确认工作流权限包含所需范围。
• 确认仓库级别已设置所需密钥。
• 确认调用方工作流指向正确的可复用工作流路径。
• 对于 monorepo，确认 packages JSON 有效且路径存在。
• 对于发布失败，使用 dry-run: true 进行测试，并验证身份验证令牌的权限范围。
• 对于 Homebrew tap 更新，确认已设置 APP_ID 和 APP_PRIVATE_KEY 密钥，且 GitHub App 有权限向 tap 仓库推送。
• 对于 Jamf 上传，确认已设置 JAMF_CLIENT_ID 和 JAMF_CLIENT_SECRET，且 jamf-url 是有效的 Jamf Pro URL。
• 对于 dylib 构建，确认 Xcode 工作区/方案或 Makefile 存在，且能生成预期输出。

Agent 响应的输出格式

生成 BuildSpace 设置说明时，请按以下格式回复：

1. 选择的工作流及原因。
2. 可直接复制的 YAML，用于调用方工作流。
3. 需要添加的密钥（准确列出密钥及其获取方式）。
4. 如何触发和验证。
5. 首次运行安全模式（dry-run）建议。

建议务必具体，并默认采用最精简的可用设置。