BuildSpace Release Workflows Skill

Use this skill to set up or debug BuildSpace-powered release automation in repositories that use reusable GitHub Actions workflows.

What BuildSpace Provides

BuildSpace has two layers:

• Workflows: full release pipelines under .github/workflows/*.
• Blocks: reusable composite actions under .github/blocks/* for custom pipelines.

Default recommendation: use a prebuilt workflow unless the user explicitly needs custom behavior.

Workflow Selection

Pick exactly one primary workflow based on project type:

Project type	Workflow file	Trigger
Rust binary/library	rust-service-release.yaml	PR label release
TypeScript/JavaScript single package	typescript-service-release.yaml	PR label release
TypeScript monorepo (multiple packages)	typescript-monorepo-release.yaml	PR label release
Go binary	go-service-release.yaml	PR label release
Swift macOS .pkg (with compiled binary)	swift-release.yml	PR label release
macOS .pkg without binary (payload/scripts only)	pkg-release.yml	PR label release
macOS .pkg PR build (payload/scripts only)	pkg-release-pr.yml	Every PR commit
Swift macOS .pkg PR build previews	swift-pkg-pr.yml	Every PR commit
macOS dylib release (Xcode workspace)	dylib-release.yml	PR label release
macOS dylib release (Makefile)	makefile-dylib-release.yml	PR label release
Generic release (version + GitHub Release only)	release.yaml	PR label release
README freshness check on PRs	check-readme.yaml	Every PR
Skills documentation freshness check on PRs	check-skills.yaml	Every PR

Required Inputs, Secrets, and Permissions

Always verify these before writing YAML:

1. Inputs: service/package names, paths, build command, package lists, Homebrew tap info, Jamf config.
2. Secrets:
   • Always required for AI features: OPENAI_API_KEY
   • npm publishing: NPM_TOKEN
   • crates publishing: CARGO_REGISTRY_TOKEN
   • Swift compile-time env vars: SECRET_ENV_VARS
   • Jamf upload: JAMF_CLIENT_ID + JAMF_CLIENT_SECRET
   • Protected-branch pushes or Homebrew tap updates: APP_ID + APP_PRIVATE_KEY
   • Skills documentation check (private repos): SKILLS_REPO_TOKEN
   • Note: DEVELOPER_ID_INSTALLER_NAME is deprecated and ignored — packages are always unsigned.
3. Permissions:
   • Release/version bump jobs need contents: write
   • Label checks need pull-requests: read
   • PR commenting needs pull-requests: write

Release Trigger Rules (Important)

BuildSpace is label-gated by default.

• Standard release label: release
• Optional prerelease label: prerelease
• No label usually means no release job.

Behavior nuance to keep accurate:

• typescript-monorepo-release supports prerelease path directly.
• typescript-service-release, rust-service-release, and go-service-release gate release jobs on release (or forced input), and treat prerelease as flavor once release is active.
• swift-release, pkg-release, dylib-release, and makefile-dylib-release check only release.
• release.yaml (generic) checks release label and supports a release boolean input to force.

Implementation Procedure

When asked to set up BuildSpace in a repo:

1. Detect repo type (Rust, TS single, TS monorepo, Go, Swift, macOS pkg, dylib).
2. Confirm publish targets (GitHub only, npm, crates, Jamf, Homebrew tap).
3. Create a caller workflow in the user repo (.github/workflows/release.yaml or ci.yaml) with uses: photon-hq/buildspace/...@v1.
4. Wire with: inputs and secrets: exactly for that workflow.
5. Add recommended permissions block.
6. Add dry-run: true for first validation run unless the user requests immediate publish.
7. Explain how to trigger (release label + merge path, or forced release: true).
8. For monorepos, validate packages JSON and dependency order behavior.
9. For Homebrew tap updates, wire tap-repo and tap-formula inputs plus APP_ID/APP_PRIVATE_KEY secrets.
10. For Jamf uploads, wire jamf-url and Jamf secrets.

Workflow Reference

rust-service-release.yaml

Complete release pipeline for Rust services: label check, AI version + release notes, cross-build (Linux x64, macOS ARM64, Windows x64), sync workspace crate versions, publish crates to crates.io, create GitHub Release with binaries, optionally update Homebrew tap.

Inputs:

Input	Type	Required	Default	Description
service-name	string	Yes	—	Display name for the service
binary-name	string	Yes	—	Name of the binary from Cargo.toml
binary-path	string	No	""	Path to crate directory (e.g., crates/client)
crates	string	No	[]	JSON array of crate paths to publish in dependency order
build-env	string	No	""	Compile-time env vars (e.g., BASE_URL=https://...)
labels-to-check	string	No	["release", "prerelease"]	PR labels that trigger releases
prerelease	boolean	No	false	Force prerelease (adds -rc.N suffix)
release	boolean	No	false	Force release (bypasses label check)
dry-run	boolean	No	false	Test without actually publishing
tap-repo	string	No	""	Homebrew tap repository (e.g., photon-hq/homebrew-photon). Empty to skip.
tap-formula	string	No	""	Formula name in tap (e.g., jamf-package-updater). Required if tap-repo is set.

Secrets:

Secret	Required	Description
OPENAI_API_KEY	Yes	For AI-powered versioning and release notes
CARGO_REGISTRY_TOKEN	No	crates.io API token (required for publishing)
APP_ID	No	GitHub App ID (for protected branches and Homebrew tap updates)
APP_PRIVATE_KEY	No	GitHub App private key

typescript-service-release.yaml

Complete release pipeline for a single TypeScript/JavaScript package: label check, AI version + release notes, bump package.json, create GitHub Release, publish to npm.

Inputs:

Input	Type	Required	Default	Description
service-name	string	Yes	—	Display name for the service
bun-version	string	No	latest	Bun version to use
npm-tag	string	No	latest	npm dist-tag (e.g., latest, beta, next)
no-npm-publish	boolean	No	false	Skip npm publishing (GitHub Release only)
working-directory	string	No	.	Directory containing package.json
build-command	string	No	bun run build	Build command to run
labels-to-check	string	No	["release", "prerelease"]	PR labels that trigger releases
prerelease	boolean	No	false	Force prerelease
release	boolean	No	false	Force release (bypasses label check)
dry-run	boolean	No	false	Test without actually publishing

Secrets:

Secret	Required	Description
OPENAI_API_KEY	Yes	For AI-powered versioning and release notes
NPM_TOKEN	No	npm auth token (required for publishing)

typescript-monorepo-release.yaml

Complete release pipeline for TypeScript monorepos with independently-versioned packages. Detects changed packages, topologically sorts by dependency order, single AI call for all versions/notes, bumps each package.json, creates GitHub Release with release/YYYY-MM-DD.N tag, publishes to npm in order.

Inputs:

Input	Type	Required	Default	Description
service-name	string	Yes	—	Display name for the monorepo
packages	string	Yes	—	JSON array: [{"name":"pkg","path":"packages/pkg"}]
bun-version	string	No	latest	Bun version to use
npm-tag	string	No	latest	npm dist-tag
build-command	string	No	bun run build	Per-package build command (ignored if root-build-command is set)
root-build-command	string	No	""	Build once at repo root (e.g., turbo build)
include-dependents	boolean	No	false	Also release downstream dependents
labels-to-check	string	No	["release", "prerelease"]	PR labels that trigger releases
prerelease	boolean	No	false	Force prerelease
release	boolean	No	false	Force release
dry-run	boolean	No	false	Test without actually publishing

Secrets:

Secret	Required	Description
OPENAI_API_KEY	Yes	For AI-powered versioning and release notes
NPM_TOKEN	Yes	npm authentication token
APP_ID	No	GitHub App ID (for pushing to protected branches)
APP_PRIVATE_KEY	No	GitHub App private key

go-service-release.yaml

Complete release pipeline for Go binaries: label check, AI version + release notes, cross-compile for macOS (ARM64) and Linux (AMD64), create GitHub Release with binaries, optionally update Homebrew tap.

Inputs:

Input	Type	Required	Default	Description
service-name	string	Yes	—	Display name for the service
binary-name	string	Yes	—	Output binary name
go-version	string	No	stable	Go version to use
build-flags	string	No	""	Additional go build flags
ldflags	string	No	-s -w	Linker flags
labels-to-check	string	No	["release", "prerelease"]	PR labels that trigger releases
prerelease	boolean	No	false	Force prerelease
release	boolean	No	false	Force release
tap-repo	string	No	""	Homebrew tap repository. Empty to skip.
tap-formula	string	No	""	Formula name in tap. Required if tap-repo is set.

Secrets:

Secret	Required	Description
OPENAI_API_KEY	Yes	For AI-powered versioning and release notes
APP_ID	No	GitHub App ID (for Homebrew tap updates)
APP_PRIVATE_KEY	No	GitHub App private key

swift-release.yml

Complete release pipeline for macOS .pkg distribution with a compiled Swift binary: label check, AI version + release notes, Swift build, .pkg creation (unsigned), GitHub Release, optional Jamf upload.

Inputs:

Input	Type	Required	Default	Description
package-name	string	Yes	—	Name of the Swift binary / package
identifier	string	Yes	—	Package identifier (e.g., com.example.mytool)
scripts-path	string	No	""	Path to scripts directory with preinstall/postinstall scripts
payload-path	string	No	""	Path to additional payload directory (mirrors install root)
jamf-url	string	No	""	Jamf Pro instance URL (leave empty to skip)
jamf-package-priority	string	No	""	Package priority in Jamf Pro
jamf-package-name	string	No	""	Package name to match in Jamf Pro

Secrets:

Secret	Required	Description
OPENAI_API_KEY	Yes	For AI-powered versioning and release notes
SECRET_ENV_VARS	No	Compile-time env vars written to .env
JAMF_CLIENT_ID	No	Jamf Pro API client ID
JAMF_CLIENT_SECRET	No	Jamf Pro API client secret

pkg-release.yml

Release pipeline for macOS .pkg that does not contain a compiled binary. Packages payload files and scripts into a .pkg, creates GitHub Release, optionally uploads to Jamf. Use instead of swift-release when packages only deliver configuration files, LaunchDaemons, scripts, or other non-binary payload.

Inputs:

Input	Type	Required	Default	Description
package-name	string	Yes	—	Name of the package
identifier	string	Yes	—	Package identifier (e.g., com.example.my-config)
scripts-path	string	No	""	Path to scripts directory with preinstall/postinstall scripts
payload-path	string	No	""	Path to payload directory (mirrors install root)
jamf-url	string	No	""	Jamf Pro instance URL (leave empty to skip)
jamf-package-priority	string	No	""	Package priority in Jamf Pro
jamf-package-name	string	No	""	Package name to match in Jamf Pro

Secrets:

Secret	Required	Description
OPENAI_API_KEY	Yes	For AI-powered versioning and release notes
JAMF_CLIENT_ID	No	Jamf Pro API client ID
JAMF_CLIENT_SECRET	No	Jamf Pro API client secret

pkg-release-pr.yml

Builds a macOS .pkg (without a compiled binary) on every PR commit and reports status in the PR as a living comment. Same experience as swift-pkg-pr but for payload/scripts-only packages. Stale in-progress builds are automatically cancelled on new commits.

Inputs:

Input	Type	Required	Default	Description
package-name	string	Yes	—	Name of the package
identifier	string	Yes	—	Package identifier (e.g., com.example.my-config)
scripts-path	string	No	""	Path to scripts directory with preinstall/postinstall scripts
payload-path	string	No	""	Path to payload directory (mirrors install root)

swift-pkg-pr.yml

Builds a macOS .pkg (with Swift binary) on every PR commit, posts/updates a single PR comment with build status, uploads artifact (7-day retention). Stale in-progress builds are automatically cancelled on new commits.

Inputs:

Input	Type	Required	Default	Description
package-name	string	Yes	—	Name of the Swift binary / package
identifier	string	Yes	—	Package identifier (e.g., com.example.mytool)
scripts-path	string	No	""	Path to scripts directory with preinstall/postinstall scripts

Secrets:

Secret	Required	Description
SECRET_ENV_VARS	No	Compile-time env vars written to .env

dylib-release.yml

Release pipeline for macOS dynamic libraries built from an Xcode workspace with CocoaPods. Label check, AI version + release notes, install CocoaPods, build dylib (arm64e), create GitHub Release with .dylib artifact.

Inputs:

Input	Type	Required	Default	Description
workspace	string	Yes	—	Path to .xcworkspace
scheme	string	Yes	—	Xcode scheme to build
dylib-name	string	Yes	—	Name of the output dylib (e.g., BlueBubblesHelper)
project-directory	string	Yes	—	Directory containing the Podfile

Secrets:

Secret	Required	Description
OPENAI_API_KEY	Yes	For AI-powered versioning and release notes

makefile-dylib-release.yml

Release pipeline for macOS dynamic libraries built from a Makefile. Label check, AI version + release notes, make release, create GitHub Release with .dylib artifact.

Inputs:

Input	Type	Required	Default	Description
dylib-name	string	Yes	—	Name of the output dylib (e.g., imessage-helper)

Secrets:

Secret	Required	Description
OPENAI_API_KEY	Yes	For AI-powered versioning and release notes

release.yaml

Generic release pipeline for projects that only need AI-powered versioning and a GitHub Release (no build step, no package publishing). Useful for configuration repos, documentation repos, or any project that just needs tagged releases.

Inputs:

Input	Type	Required	Default	Description
service-name	string	Yes	—	Display name for the service
labels-to-check	string	No	["release"]	JSON array of PR labels to check
release	boolean	No	false	Force release (overrides label)

Secrets:

Secret	Required	Description
OPENAI_API_KEY	Yes	For AI-powered versioning and release notes

check-readme.yaml

Runs on every PR to check if README.md is up to date with the changes. Uses AI to analyze changed files against the README. Posts/removes PR comments automatically.

Inputs:

Input	Type	Required	Default	Description
blocking	boolean	No	false	If true, fail the workflow when README is outdated. If false, only post a warning comment.

Secrets:

Secret	Required	Description
OPENAI_API_KEY	Yes	For AI-powered README analysis

check-skills.yaml

Runs on every PR to check if skills documentation (in a separate skills repo) is up to date with the changes. Uses AI to analyze changed files against skill SKILL.md files. Posts/removes PR comments automatically.

Inputs:

Input	Type	Required	Default	Description
fail_on_missing_skills	boolean	No	false	If true, fail workflow when skills are outdated. If false, only post a warning comment.
skills-repo	string	No	photon-hq/skills	Skills repository to check against (owner/repo format)

Secrets:

Secret	Required	Description
OPENAI_API_KEY	Yes	For AI-powered skills analysis
SKILLS_REPO_TOKEN	No	GitHub token for skills repo (defaults to GITHUB_TOKEN; use PAT for private repos)

Monorepo-Specific Guidance

For typescript-monorepo-release:

• packages input must be a JSON array: [{"name":"pkg","path":"packages/pkg"}]
• Changed package detection is diffed from last release tag.
• Packages are topologically sorted using local dependency edges.
• Optional include-dependents: true pulls downstream packages into release.
• root-build-command takes precedence over per-package build-command.
• Pre-release npm tag is automatically beta when prerelease is active.
• Uses release/YYYY-MM-DD.N date-based tags since there's no single version.

Rust/Go Notes

• Rust workflow can:
  • cross-build artifacts for Linux x64, macOS ARM64, Windows x64
  • sync workspace versions across all crates
  • publish crates in provided order
  • optionally update Homebrew tap (tap-repo + tap-formula, requires APP_ID + APP_PRIVATE_KEY)
• Go workflow:
  • cross-builds for macOS ARM64 and Linux AMD64
  • can also update Homebrew tap (tap-repo + tap-formula, requires APP_ID + APP_PRIVATE_KEY)

Swift / macOS .pkg Notes

• swift-release builds the Swift binary, creates an unsigned .pkg, creates GitHub Release, and optionally uploads to Jamf.
• pkg-release is for .pkg packages that contain no compiled binary — only payload files and/or scripts.
• swift-pkg-pr and pkg-release-pr are the PR preview counterparts (build on every commit, comment on PR).
• Packages are always unsigned (DEVELOPER_ID_INSTALLER_NAME is deprecated and ignored).
• Compile-time env vars are passed via SECRET_ENV_VARS secret (written to .env).
• Jamf upload is optional — set jamf-url input and provide JAMF_CLIENT_ID + JAMF_CLIENT_SECRET secrets.

Dylib Notes

• dylib-release.yml is for projects using an Xcode workspace with CocoaPods. Builds arm64e dylib.
• makefile-dylib-release.yml is for projects using a Makefile. Runs make release and embeds version.
• Both create a GitHub Release with the .dylib as an artifact.

README Check Guidance

Use check-readme.yaml for PR docs drift detection:

• blocking: false (default): warning comment only.
• blocking: true: fails job when README appears stale.
• Requires OPENAI_API_KEY and PR write permission for comments.

Skills Check Guidance

Use check-skills.yaml for skills documentation drift detection:

• fail_on_missing_skills: false (default): warning comment only.
• fail_on_missing_skills: true: fails job when skills appear outdated.
• Requires OPENAI_API_KEY and PR write permission for comments.
• For private skills repos, provide SKILLS_REPO_TOKEN (PAT with repo access).

Blocks Reference

All blocks live under .github/blocks/. Workflows compose these internally — use them directly only for custom pipelines.

Version & Release Info

Block	Path	Purpose
determine-publish-version	.github/blocks/determine-publish-version/action.yaml	AI-powered next semantic version (standalone, no release notes)
generate-release-info	.github/blocks/generate-release-info/action.yaml	AI-powered version + release notes in one step
create-github-release	.github/blocks/create-github-release/action.yaml	Create GitHub Release with optional artifact attachments

Label & PR Interaction

Block	Path	Purpose
check-pr-label	.github/blocks/check-pr-label/action.yaml	Check PR labels to decide if release should trigger
comment-on-pr	.github/blocks/comment-on-pr/action.yaml	Post or update a single PR comment (idempotent via comment-key)
check-readme	.github/blocks/check-readme/action.yaml	AI-powered README freshness check
check-skills	.github/blocks/check-skills/action.yaml	AI-powered skills documentation freshness check

Build Blocks

Block	Path	Purpose
rust-build	.github/blocks/rust-build/action.yaml	Build Rust binary for a target triple
go-build	.github/blocks/go-build/action.yaml	Build Go binary for a target OS/arch
typescript-build	.github/blocks/typescript-build/action.yaml	Build TypeScript project using Bun
swift-build	.github/blocks/swift-build/action.yml	Build Swift binary (SPM, supports .env injection)
swift-pkg	.github/blocks/swift-pkg/action.yml	Create macOS .pkg from binary and/or payload/scripts
build-dylib	.github/blocks/build-dylib/action.yml	Build macOS dylib from Xcode workspace (arm64e)
build-makefile-dylib	.github/blocks/build-makefile-dylib/action.yml	Build macOS dylib from Makefile
install-cocoapods	.github/blocks/install-cocoapods/action.yml	Cache and install CocoaPods dependencies

Publish Blocks

Block	Path	Purpose
publish-npm	.github/blocks/publish-npm/action.yaml	Publish single package to npm
publish-npm-packages	.github/blocks/publish-npm-packages/action.yaml	Publish multiple monorepo packages to npm in dependency order
publish-crates	.github/blocks/publish-crates/action.yaml	Publish workspace crates to crates.io in order
bump-npm-version	.github/blocks/bump-npm-version/action.yaml	Bump version in package.json and push
bump-monorepo-versions	.github/blocks/bump-monorepo-versions/action.yaml	AI version bump for all changed monorepo packages
sync-crates-version	.github/blocks/sync-crates-version/action.yaml	Set a single version across all Rust workspace crates
update-tap	.github/blocks/update-tap/action.yaml	Update Homebrew tap formula (auto-calculates SHA256 for npm/Go/prebuilt)
detect-changed-packages	.github/blocks/detect-changed-packages/action.yaml	Detect changed monorepo packages and return in topological order

Troubleshooting Checklist

If release did not run:

• Confirm PR had expected label before merge.
• Confirm workflow permissions include required scopes.
• Confirm secrets exist at repository level.
• Confirm caller workflow points to correct reusable workflow path.
• For monorepos, confirm packages JSON is valid and paths exist.
• For publish failures, test with dry-run: true and verify auth token scopes.
• For Homebrew tap updates, confirm APP_ID + APP_PRIVATE_KEY secrets are set and the GitHub App has push access to the tap repo.
• For Jamf uploads, confirm JAMF_CLIENT_ID + JAMF_CLIENT_SECRET are set and jamf-url is a valid Jamf Pro URL.
• For dylib builds, confirm Xcode workspace/scheme or Makefile exists and produces expected output.

Output Format for Agent Responses

When generating BuildSpace setup instructions, respond with:

1. Chosen workflow and why.
2. Copy-ready YAML for caller workflow.
3. Secrets to add (list exactly which ones and where to get them).
4. How to trigger and verify.
5. First-run safe mode (dry-run) recommendation.

Keep recommendations concrete and default to the smallest working setup.