Release

Prerequisites

Secrets

GH_TOKEN — required Used for repository access and GitHub API interactions.
NPM_TOKEN — required Used to publish packages to the npm registry.
PAT_FORCE_PUSH — required Used by the downstream sync workflow to force-update branches.

How to Call This Workflow

This workflow is consumed as a reusable workflow. Applications explicitly opt in by invoking it from their local CI configuration.

Minimal Usage (Single Repository)

jobs:
  release:
    uses: kurocado-studio/platform/.github/workflows/workflow.release.yml@main
    secrets:
      GH_TOKEN: ${{ secrets.GH_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
      PAT_FORCE_PUSH: ${{ secrets.PAT_FORCE_PUSH }}
    with:
      branch_name: ${{ github.ref_name }}

Monorepo Usage

jobs:
  release:
    uses: kurocado-studio/platform/.github/workflows/workflow.release.yml@main
    with:
      monorepo: true
      branch_name: ${{ github.ref_name }}
    secrets:
      GH_TOKEN: ${{ secrets.GH_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
      PAT_FORCE_PUSH: ${{ secrets.PAT_FORCE_PUSH }}

Execution Sequence

The diagram below illustrates how release is executed when the workflow is triggered.

Purpose

Automates the release process, including versioning, changelog generation, and release notes.

This workflow centralizes release automation across all Platform consumers.

It ensures consistent versioning and publishing behavior without requiring each repository to define or maintain its own release pipeline. By owning releases at the Platform level, drift is prevented and fixes propagate to all applications automatically.

If this workflow is removed or bypassed, release behavior becomes inconsistent across repositories.

When to Use / When Not to Use

Use this workflow when:

you use semantic-release for automated versioning and publishing
releases should be gated to known branches (main, alpha, beta, develop, pre)
monorepo and single-repo projects should behave consistently
release should run as a single canonical CI job

Do not use this workflow when:

a repo has a fundamentally different release process/tooling
you need custom branch gating rules not supported by the platform workflow
you cannot provide the required tokens (npm publish + branch sync)

Repository Expectations

A valid semantic-release configuration exists (and matches your repo type).
Build is available via pnpm build (single repo) or turbo run build (monorepo).
Commit messages follow Conventional Commits (so semantic-release can compute versions).

Inputs & Outputs

Inputs

branch_name (string, required) Branch name used to decide whether release runs.
monorepo (boolean, optional) Enables workspace-aware build and semantic-release execution.

Outputs

None

This workflow is intended to publish releases and act as a gating CI step.

Internal Dependencies

Platform Actions

.github/actions/install

Platform Workflows

workflow.sync.yml (called after release)

External Dependencies

actions/checkout
Node.js runtime
pnpm
semantic-release (and plugins configured by the consuming repo)

Structural Topology

The following diagram shows the static dependency structure of the release workflow.

Failure Modes

Common failure cases include:

Missing secrets Releases fail immediately without GH_TOKEN, NPM_TOKEN, or PAT_FORCE_PUSH.
Branch not allowed Release job is skipped unless branch_name is one of: main, alpha, beta, develop, pre.
Build failure pnpm build (or turbo run build) fails and blocks publishing.
Invalid semantic-release config Missing plugins, bad .releaserc, or missing repo permissions.
npm publish failure Token is invalid, package name/visibility conflicts, or registry errors.
Sync failure Downstream workflow.sync.yml fails, leaving branches out of sync.

Last modified: 18 December 2025