Xova Actions

English | 简体中文

Composable GitHub Actions for public npm publication and documentation delivery, plus release-it presets and a short release Skill. Projects own their tools, checks, release contents, environments and deployment policy. Organization defaults and workflow templates stay in xova-dev/.github.

The stable interface has not been released. Every @v1 example is a placeholder. Use PENDING_ACTIONS_SHA for local consumer drafts that need uncommitted interfaces, then pin the delivered toolkit's full SHA after its remote CI passes. Code/docs CI does not establish npm OIDC, publication or deployment acceptance.

Start with project workflows: one declarative configuration for code checks, documentation checks, publication and recovery. Product matrices and event policy remain in consumers; setup and common checks stay here. Custom jobs compose operation actions directly.

Required settings follow the selected task; unrelated commands may be omitted while unknown fields and invalid values still fail. Each check job reads configuration once and uses independent source guards around the work.

Ordinary consumer CI runs code and docs in parallel in one workflow. Optional download caches for npm, pnpm and uv are declared once in project JSON; documentation can select a smaller cache set. Locked installation and checks still run on cache hits. See cache settings and CI wiring.

Successful npm jobs save a publication result and recovery summary. CI tests both reusable check paths with real code assertions, workflow outputs and downloaded documentation artifacts, without publishing or deploying.

Choose an entry

Entry	Responsibility
actions/	Composable steps; caller owns checkout, tools, dependencies and job policy.
.github/workflows/	Ubuntu recipes with Node/npm defaults and optional consumer mise setup.
lib/	Internal implementations; not a public CLI API.
release-it preset	Shared preparation defaults and the official Conventional Changelog plugin.
publication preset	release-it's built-in npm publisher with candidate and tarball checks.
xova-release	Agent guidance preserving project checks and authorization.

Read the architecture and interface contract, then the adoption guide.

Independent consumers

• npm-package: npm-only project using the publication recipe; no mise or pnpm.
• subpackage: one subdirectory package with a widget@ tag prefix and caller-owned setup.
• docs-only: no package.json or npm release; deploys documentation from main.
• multi-site: blueprint for two npm-workspace sites, separate artifacts, environments and Cloudflare targets. Supply workspaces, locked Wrangler and configurations.

The first three directories contain runnable minimal sources. Tests execute checks/builds, the real release-it CLI and shipped composite shell steps, substituting publication and hosted artifact/Pages APIs. Fixtures install consumer sources with --omit=dev and explicitly link the toolkit's locked release-it installation; CI also installs both npm examples' full locked dependencies and runs their CLI. The multi-site test exercises two artifact/restore paths; it does not run real Wrangler. Before publication, replace the illustrative package names and repository metadata as described in the adoption guide. The docs-only fixture includes hidden .well-known content for the Pages handoff.

Matrix and RSP demonstrate project policy: required CI, explicit mise/pnpm, publication before deployment, and latest-stable eligibility checked inside the serialized deployment job. Deployment adapters themselves require neither npm nor a GitHub Release.

Release preparation

Consumers can inherit the release-it configuration and use its native CLI and hooks without copying a preparation script. The preset disables commit, tag, push, npm publication and GitHub/GitLab Releases. Preparation uses release-it 21.1.1 and @release-it/conventional-changelog 12.0.2, requiring Node ^22.22.2, ^24.15.0 or >=26.0.0.

After configuring the consumer, use its installed CLI directly:

pnpm exec release-it 0.4.0 --ci --dry-run
pnpm exec release-it 0.4.0 --ci

Preparation updates version/changelog in a clean worktree without committing, tagging, pushing, publishing or creating a GitHub Release. Review the result and add necessary release notes, migrations and other changes. Consumer hooks run normally; the official plugin may stage a newly created changelog. See releasing and recovery.

Publication requires a locked release-it 21.1.1 development dependency in the consumer and runs its native CLI with an isolated publication preset. The built-in npm plugin publishes the verified tarball; Git delivery and version bumps are disabled. Packing uses npm by default, or explicit package-manager=pnpm. Optional package-verify-command receives the absolute TARBALL path. The source and tarball digest are rechecked before publishing those same bytes. Bundled semver rejects invalid/noncanonical versions and dist-tags that are version ranges before project checks. Native packers and tar are retained after the @publint/pack evaluation; no consumer release wrapper is required. The source tag retains build metadata, while the version output identifies the npm registry version without it. Publication rejects an effective npm dry-run setting instead of treating a preview as success.

Development

mise install
mise exec -- pnpm install --frozen-lockfile
mise exec -- pnpm check

Maintainer mise tools do not configure consumers. mise.toml pins actionlint 1.7.12 and action-validator 0.9.0. CI installs both through the existing mise setup and runs pnpm lint directly, without Docker. Local mise install downloads missing tools.

pnpm check regenerates the distribution files, then runs tests and lint, stopping on the first failure. Review any generated changes together with the source changes.

semver 7.8.5 is distributed in dist/semver.mjs with dist/semver.LICENSE; keep both files in Git so consumers do not need to install toolkit dependencies. Project settings and task rules are defined in config/project.mjs with Valibot. pnpm build generates config/project.schema.json through the official converter and bundles the validator in dist/project-config.mjs with its visible dist/valibot.LICENSE. Edit the source definition, not generated files. .gitattributes marks only dist/*.mjs as generated for GitHub diffs; licenses remain visible. After upgrading semver or changing the bundle entry, run pnpm check or mise exec -- pnpm build to regenerate only. CI uses pnpm build:check to compare generated bytes without rewriting files, then runs tests and lint separately. CI never automatically commits or pushes generated files. esbuild 0.28.2 is a maintainer-only build tool; its install script is explicitly disabled in pnpm-workspace.yaml and its packaged platform binary is used instead.

The lint entry checks workflows/examples with actionlint and recursively validates action.yml/action.yaml under actions/ with action-validator's metadata schema. Schema checks do not execute shell commands or fully check composite expressions; contract and behavior tests exercise the selected runtime paths. The actionlint exclusion covers only its missing support for GitHub.com's same-commit $/actions/... syntax; tests validate those references and input contracts. See GitHub workflow syntax.