Workflows

Generate GitHub Actions workflow files under .github/workflows/ from the "workflows" array in nova.config.json.

The generator validates each entry against its template, builds the workflow from your config, resolves variable names, and writes the YAML to disk.

Why Use This Command?

• Bootstraps a full set of CI/CD workflows without writing YAML by hand.
• Publishes one project to multiple destinations (npm, GitHub Packages, Docker, hosting) from a single build, instead of each destination running its own pipeline from scratch.
• Serializes dependent publishes (e.g., a preset waits for its core dependency to reach the registry) via after on deploy destinations.
• Keeps workflow definitions consistent across Nova-managed repositories.

Requirements

• Node.js runtime — Use any Node.js LTS release.
• Project root — Run the command from the directory containing the top-level package.json.
• Corepack package manager — A project with a publish workflow must declare an exact root packageManager value for npm, pnpm, or Yarn. Ranges, partial versions, missing values, and unsupported clients are rejected before any workflow file changes.
• Configured workflows — The "workflows" array must exist in nova.config.json. Use nova utility initialize to configure it interactively.

Usage

Options

Package Manager Selection

The project root's packageManager field selects how generated publish workflows install dependencies and run project-owned tools. Nova passes the client through the entire workflow instead of translating every project to npm.

Each install job first runs corepack enable <client>. Corepack then reads the full descriptor from the checked-out root package.json, so the workflow uses the pinned version instead of installing a floating latest release. Turbo projects use the same client to execute turbo.

This selection governs project tooling; it does not rename deploy destinations. The npm and github-packages targets still use the npm publishing protocol and commands even when pnpm or Yarn manages the repository.

Config-Driven Workflow Entries

Each entry in the "workflows" array maps to one output file. An entry contains:

Deploy Fields

Each entry in the deploy array pins one publish destination to a workspace.

Config Examples

Publish a single package to npm:

{
  "template": "publish",
  "name": "project",
  "triggers": ["release"],
  "build": ["./packages/core"],
  "deploy": [
    {
      "to": "npm",
      "path": "./packages/core"
    }
  ]
}

Serialize dependent publishes with after:

{
  "template": "publish",
  "name": "project",
  "triggers": ["release"],
  "build": [
    "./packages/core",
    "./packages/preset"
  ],
  "deploy": [
    {
      "to": "npm",
      "path": "./packages/core"
    },
    {
      "to": "npm",
      "path": "./packages/preset",
      "after": ["./packages/core"]
    }
  ]
}

The preset destination waits for core to finish publishing before it starts, so consumers that pull [email protected] can always resolve its declared dependency on [email protected].

Publish to multiple destinations from one build:

{
  "template": "publish",
  "name": "project",
  "triggers": ["release"],
  "build": [
    "./packages/sdk",
    "./apps/docs"
  ],
  "deploy": [
    {
      "to": "npm",
      "path": "./packages/sdk"
    },
    {
      "to": "github-packages",
      "path": "./packages/sdk"
    },
    {
      "to": "cloudflare-pages-docusaurus",
      "path": "./apps/docs"
    }
  ]
}

Each destination becomes its own publish job. Jobs run in parallel off a shared build job, except where after declares an explicit ordering.

Available Templates

The generator bundles three templates, each with its own trigger set.

check-sponsor-gated-issues Variables

This template declares the following variables. GITHUB_TOKEN is supplied automatically, so the only secret you create manually is PERSONAL_ACCESS_TOKEN.

The remaining values are var-format, not literal - they resolve to ${{ vars.NAME }} references and are configured as GitHub repository variables.

Available Target Types

The publish template supports the following to values for each entry in deploy. Each type declares its own secrets and variables.

Available Triggers

Each template accepts a specific set of triggers, and a trigger outside that set is rejected.

The publish and lock-inactive-issues templates also include workflow_dispatch (manual trigger with dry-run option) automatically.

Configuring Publish Triggers

The publish template accepts three release-style triggers, each with its own config form.

• release — Publishes when a GitHub Release is published. Configure it with the bare string "release".
• tag-push — Publishes when a version tag is pushed, emitting on: push: tags: ["v*"]. Configure it with the bare string "tag-push" (tags default to v*), or an object { "name": "tag-push", "tags": ["v*"] } to override the tag globs.
• push — Branch continuous deployment that publishes for real on a push to a listed branch. Configure it only in object form with a required branches filter, for example { "name": "push", "branches": ["main"], "paths": ["packages/**"] }.

Publishing on a version tag keeps GITHUB_REF pointing at the tag, so npm --provenance signing stays valid. A release-triggered run can instead bind to the default branch and fail provenance, which is why tag-push is preferred for signed npm publishes.

The bare string "push" is a validation error, since a branchless push trigger would fire on every branch. The branches, paths, and tags filters must each be a non-empty array of strings when present.

Configuring Workflow-Run Triggers

The three workflow-run-* triggers start a new publish workflow after a named upstream workflow finishes. Choose the variant that matches the upstream result you accept:

Declare one of these triggers in object form. Its workflows array contains sibling <template>-<name> keys from the same workflows config:

{
  "template": "publish",
  "name": "preset",
  "triggers": [
    {
      "name": "workflow-run-success",
      "workflows": ["publish-core"]
    }
  ],
  "build": ["./packages/preset"],
  "deploy": [
    {
      "to": "npm",
      "path": "./packages/preset"
    }
  ]
}

Nova turns publish-core into the generated upstream workflow's display name. When that workflow finishes successfully, GitHub starts publish-preset as a separate run.

{
  "name": "workflow-run-success",
  "workflows": ["publish-core", "publish-cli"]
}

Each referenced key must resolve to a sibling workflow, and Nova rejects circular references. The downstream run starts fresh; Nova does not automatically carry build files or artifacts over from the upstream run.

GitHub also requires the downstream workflow file to exist on the repository's default branch and limits workflow_run chains to three levels. See GitHub's workflow_run documentation before designing a longer chain.

Environment Variables and Secrets

A publish workflow reads workspace environment values declared under environment.workspaces. Every value has a required reach, which tells Nova where the value is allowed to travel:

For managed, build, and runtime, the independent secret flag controls storage: secret: false uses a GitHub Variable, while secret: true uses a GitHub Secret. A local value never leaves the developer's machine, so it does not accept secret and does not need a namespace prefix.

A build value exists only while the build runs on the CI runner. A Variable that application code inlines (for example, import.meta.env.PUBLIC_SITE_KEY) can become part of the output; a Secret used for authentication can be consumed without being emitted. "Build" means "available to the build process," not automatically "shipped to users." Whether a value is exposed in client output depends on how the application uses it.

A runtime value is reconciled into a running server's environment and read by reference (env.X or process.env.X). A managed value is tracked locally and on GitHub but is intentionally delivered to neither destination.

Every GitHub name is the workspace's prefix joined to the key (e.g. CBN_ joined to PUBLIC_SITE_KEY becomes CBN_PUBLIC_SITE_KEY).

Build Delivery

Every workspace value with reach: "build" is written into the build .env before check / build. Nova reads it from its GitHub Variable (${{ vars.<name> }}) when secret: false, or its GitHub Secret (${{ secrets.<name> }}) when secret: true.

A secret: false Variable falls back to its defaultValue when the Variable is unset. Deploy credentials and workflow-config keys never reach the build.

The Setup report lists every GitHub Variable and Secret to create.

Runtime Environment Sync

On each deploy, Nova reconciles every workspace value with reach: "runtime" into the runtime store of every server-bearing target in the workspace's deploy[]. secret picks the channel: a secret: true value is stored encrypted, while a secret: false value is stored as a plaintext runtime variable.

• Upsert — Every declared runtime value is pushed to the destination under its prefixed name, and the running app reads it as env.NAME on Workers or process.env.NAME on Vercel.
• Delete — Any value already in the destination store but no longer declared in the config is removed, since Nova is the single source of truth for that target's runtime env.
• Log by name — Each add and removal is written to the deploy log by name only, never by value, so the reconcile stays auditable.

Per-Target Mechanism

The config is identical across both targets; only the deploy step differs.

Dev is unchanged — the values live in the local .env from nova generate must-haves dotenv, which you fill in with real values.

Variable Formats

Each template declares variables with one of three formats. The format determines how the value is substituted into the generated YAML:

Output Filename Convention

Generated files are written to .github/workflows/ with the naming pattern:

nova-{template}-{name}.yml

Examples:

• nova-lock-inactive-issues-project.yml
• nova-publish-project.yml
• nova-check-sponsor-gated-issues-project.yml

How It Works

Reading Config

The generator loads nova.config.json and reads the "workflows" array. If the array is missing or empty, the generator exits with no changes.

Validation

When at least one valid publish entry exists, the generator validates the root packageManager first. If that project-level setting is missing or invalid, the whole generation run stops before writing, backing up, or deleting workflow files.

The generator also checks each configured entry:

1. No entry carries an old-shape field name — a renamed field is rejected with a hint naming its replacement (e.g., Workflow field "suffix" was renamed to "name". Skipping.).
2. The template name matches a known bundled template.
3. name is present and a non-empty string, and no two entries share the same template and name.
4. Each trigger is valid for the entry's template, and object-form filter lists are non-empty string arrays.
5. A push trigger uses the object form with a branches filter, and a workflow-run trigger carries workflows references that each resolve to a sibling workflow.
6. Each build scope is a registered workspace, and no workspace still carries the retired dotenv block — that model moved to the top-level environment block classified by reach and, where applicable, secret, so an old-shape config is rejected with a migration hint.
7. Each deploy to is a supported target type, and each deploy path is a registered workspace.
8. All literal variables without a default have a corresponding value in with.
9. Destination uniqueness holds across every workflow (see Cross-Workflow Uniqueness), and no two entries produce the same output filename.

Each entry-level failure emits a diagnostic and skips the affected workflow, while other valid workflows still build. The project-level package manager guard is the exception because every publish entry shares it.

File Generation

Each valid entry produces one YAML file under .github/workflows/. The generator builds the workflow blueprint from your config — merging the resolved triggers, jobs, deploy destinations, and selected Corepack client — resolves variable placeholders from the template metadata and the entry's with, then serializes the blueprint to YAML.

Deploy jobs that declare after dependencies emit needs: ["build", ...]. If the target file already exists, a .nova-backup copy is created unless --replace-file is set.

Orphan Cleanup

Orphan cleanup runs only when the config validated with zero diagnostics. A config with any error never deletes your existing workflow files, so a rejected workflow's file is left untouched.

When the config is clean, the generator scans .github/workflows/ for existing nova-*.yml files that are not in the current config. These orphaned files are backed up (renamed with a .nova-backup timestamp) or deleted when --replace-file is set.

Setup Instructions

After all files are generated, the generator prints a Setup report of the secrets and variables to configure on GitHub. This covers every non-automatic template secret and var, plus every reach: "build" workspace value each build scope reads — listed under its prefixed GitHub name as a Variable (secret: false) or a Secret (secret: true).

Entries are deduplicated and listed once per output file, so a value used by two destinations in the same workflow appears a single time.

Publishing GitHub Actions

The github-action destination distributes a JavaScript GitHub Action by maintaining an orphan releases branch whose commits contain only the runtime files needed by consumers. Each release is tagged with its semver (e.g., v2.1.0), and the floating major tag (v2) is force-moved to the latest release commit.

Older frozen major tags (e.g., v1) are never touched.

Expected Repo Shape

• action.yml at the repo root (top-level, not inside a workspace).
• packages/<action-name>/ — action source (role: app, policy: trackable).
• apps/docs/ — Docusaurus docs (role: docs).
• Build output in the workspace's build/ directory, following the standard Nova convention.

Release Tree Contents

What lands on the releases branch for each release:

Required (publish fails if missing):

• action.yml
• action/ — the built output (renamed from the workspace's build/ directory during publish).

Optional (copied if present at repo root, skipped silently if not):

• README.md
• LICENSE
• SECURITY.md
• NOTICE
• CHANGELOG.md

Example nova.config.json Entry

{
  "workflows": [{
    "template": "publish",
    "name": "release",
    "triggers": ["release"],
    "deploy": [
      {
        "to": "github-action",
        "path": "./packages/my-action",
        "with": {
          "ACTION_ENTRY_POINT": "index.js",
          "ACTION_OUTPUT_PATH": "./packages/my-action/build",
          "ACTION_YML_PATH": "./action.yml",
          "RELEASE_BRANCH_NAME": "releases"
        }
      }
    ]
  }]
}

All four with values are required. Defaults aren't auto-applied — nova utility initialize prompts for each one, showing the suggested value as an example.

You can set these on the deploy's with as shown, or on the workflow-level with to share them across the entry. A deploy-level with value takes precedence over the workflow-level one for that destination.

Release Mechanics

When a GitHub Release is published:

1. The base build job runs the workspace's build command through the root packageManager client (executing Turbo when a turbo.json is present, otherwise using the client's workspace command), producing output in the workspace's build/ directory.
2. The publish-github-action-* job spins up a separate git workspace at $RUNNER_TEMP/release, initialized with the release branch name.
3. If the release branch already exists remotely, the workspace fetches and resets to it. Otherwise it stays as a fresh orphan branch.
4. The release tree is staged: action.yml, the optional files above, and the built output copied into action/ (renaming build/ → action/).
5. The staged tree is committed as Release <tag> and force-pushed to the release branch.
6. The semver tag (e.g., v2.1.0) is force-retagged onto the new orphan commit. GitHub creates this tag on main's HEAD when you publish the release; this step moves it to point at the orphan commit so uses: owner/[email protected] resolves correctly.
7. The floating major tag (e.g., v2) is force-moved to the same commit.
8. A SLSA build-provenance attestation is emitted on the resolved entry script (ACTION_OUTPUT_PATH/ACTION_ENTRY_POINT) via actions/attest-build-provenance.

The main branch is never rewritten — the release branch is a parallel, orphan history that mirrors only what consumers receive via uses: owner/repo@<ref>.

Implications of the orphan-branch design

A few non-obvious consequences worth knowing:

• main and the release branch share no history. Running git log main will never show release commits. Running git log <release-branch> shows only release commits, never source commits. To find which main commit produced a given release, use git log with the release's authoring date or look at the release's GitHub UI metadata.
• Checking out a tag yields the runtime tree, not the source. git checkout v2.1.0 puts you in a working tree containing only action.yml, action/index.js, and the optional community files. The original source that produced this release is at the parent main commit at the time of release publication.
• Force-retagging breaks reproducibility from a tag. Once v2.1.0 is moved from main's HEAD to the orphan commit, the original main commit that triggered the release is no longer reachable via that tag. Keep release notes that reference the original commit SHA if you need that traceability.
• Older frozen major tags stay put. A v1 tag from a prior major line is never touched by this workflow. Only the floating major matching the released v<N>.x.y (e.g., v2 for a v2.1.0 release) gets force-moved.

Multiple actions in one repo

If a repo ships more than one GitHub Action (rare), each github-action destination must declare a distinct RELEASE_BRANCH_NAME across the entire nova.config.json. Two github-action destinations sharing the same release branch will race on push — both jobs run in parallel and force-push to the same branch, so the second writer overwrites the first.

Nova validates destination uniqueness across the entire workflows[] array, not just within a single workflow: declaring two github-action destinations anywhere in your config — same workflow or separate workflows — with overlapping RELEASE_BRANCH_NAME values fails the generator with a clear error message and rejects both colliding workflows. To ship two actions from one repo, use distinct RELEASE_BRANCH_NAME values (e.g., releases-primary, releases-secondary) — typically each in its own workflow with its own name.

Example layout:

{
  "workflows": [
    {
      "template": "publish",
      "name": "primary",
      "triggers": ["release"],
      "deploy": [
        {
          "to": "github-action",
          "path": "./packages/primary-action",
          "with": {
            "ACTION_ENTRY_POINT": "index.js",
            "ACTION_OUTPUT_PATH": "./packages/primary-action/build",
            "ACTION_YML_PATH": "./action.yml",
            "RELEASE_BRANCH_NAME": "releases-primary"
          }
        }
      ]
    },
    {
      "template": "publish",
      "name": "secondary",
      "triggers": ["release"],
      "deploy": [
        {
          "to": "github-action",
          "path": "./packages/secondary-action",
          "with": {
            "ACTION_ENTRY_POINT": "index.js",
            "ACTION_OUTPUT_PATH": "./packages/secondary-action/build",
            "ACTION_YML_PATH": "./packages/secondary-action/action.yml",
            "RELEASE_BRANCH_NAME": "releases-secondary"
          }
        }
      ]
    }
  ]
}

Each action gets its own publish workflow with a distinct RELEASE_BRANCH_NAME, and the GitHub Releases for each action use a uniquely-prefixed tag (e.g., primary-v1.2.3, secondary-v1.0.0). Nova's force-retag step is prefix-aware: the floating major derivation matches an optional alphanumeric prefix before the v (so primary-v1.2.3 → primary-v1, v2.1.3 → v2).

Consumers reference each action via its prefixed tag: uses: owner/repo@primary-v1, uses: owner/repo@secondary-v1.

Similarly, only one github-pages-docusaurus destination may be declared across all workflows in your nova.config.json — GitHub Pages is repo-scoped, so two deployments would overwrite each other regardless of whether they live in the same workflow or separate ones. Nova validates this at workflow-generation time.

The same cross-workflow uniqueness check applies to these other publish targets: