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:

Inputs: service/package names, paths, build command, package lists, Homebrew tap info, Jamf config.
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.
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:

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

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

Keep recommendations concrete and default to the smallest working setup.

buildspace-ci-cd

BuildSpace Release Workflows Skill

What BuildSpace Provides

Workflow Selection

Required Inputs, Secrets, and Permissions

Release Trigger Rules (Important)

Implementation Procedure

Workflow Reference

rust-service-release.yaml

typescript-service-release.yaml

typescript-monorepo-release.yaml

go-service-release.yaml

swift-release.yml

pkg-release.yml

pkg-release-pr.yml

swift-pkg-pr.yml

dylib-release.yml

makefile-dylib-release.yml

release.yaml

check-readme.yaml

check-skills.yaml

Monorepo-Specific Guidance

Rust/Go Notes

Swift / macOS .pkg Notes

Dylib Notes

README Check Guidance

Skills Check Guidance

Blocks Reference

Version & Release Info

Label & PR Interaction

Build Blocks

Publish Blocks

Troubleshooting Checklist

Output Format for Agent Responses