Skip to main content

Nova Config Reference

The nova.config.json file lives at the monorepo root and drives every Nova command. This page documents each section and its fields.

For your first working file, follow the first successful check. Use this reference when you need every supported field, or run nova utility initialize to edit the same schema interactively.

project

Describes the project identity, display info, and build metadata.

FieldTypeDescription
name.slugstringURL-safe project identifier. Letters, numbers, hyphens, and underscores only. The 214-character npm limit is enforced by the nova utility initialize wizard; the parser only requires a non-empty trimmed string.
name.titlestringHuman-readable project name for display.
description.shortstringOne-line summary used in package.json and meta tags.
description.longstringExtended description for README and documentation pages.
keywordsstring[]Search keywords (max 50 characters each).
legalNamestringLegal entity name used in LICENSE and copyright notices.
pronounsstringControls first-person wording in generated files. One of "business" (we/our) or "personal" (I/my).
platformsstring[]Supported platforms for bug report dropdowns. One or more of "nodejs", "swift", "android", "java", "kotlin", "csharp", "php", "python", "macos", "linux", "windows". Unknown values are dropped.
startingYearnumberYear the project began (integer >= 1970). Used in LICENSE copyright ranges.
licensestringLicense identifier. One of "AGPL-3.0", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "BSL-1.0", "CC0-1.0", "EPL-2.0", "GPL-2.0", "GPL-3.0", "LGPL-2.1", "MIT", "MPL-2.0", "Proprietary", or "Unlicense".
json
{
  "project": {
    "name": {
      "slug": "example",
      "title": "Example"
    },
    "description": {
      "short": "A sample Nova project.",
      "long": "Extended description for documentation and README files."
    },
    "keywords": ["example", "nova"],
    "legalName": "Example Author LLC",
    "pronouns": "business",
    "platforms": ["nodejs", "macos", "linux", "windows"],
    "startingYear": 2025,
    "license": "MIT"
  }
}

entities

An array of people and organizations associated with the project.

FieldTypeDescription
namestringDisplay name.
emailstringContact email (must contain @ and a domain).
urlstringProfile or organization URL (http:// or https://).
rolesstring[]One or more of "author", "contributor", "supporter".
json
{
  "entities": [
    {
      "name": "Example Author",
      "email": "[email protected]",
      "url": "https://example.com/author",
      "roles": ["author"]
    },
    {
      "name": "Example Collaborator",
      "email": "[email protected]",
      "url": "https://example.com/collaborator",
      "roles": ["contributor", "supporter"]
    }
  ]
}

emails

Canonical contact addresses referenced by tools and metadata.

FieldTypeDescription
bugsstringEmail for bug reports and support.
json
{
  "emails": {
    "bugs": "[email protected]"
  }
}

github

Identifies the GitHub repository and declares repository-level settings. Most blocks are maintained by repeatable recipes; issueTemplate is input for an explicit generator.

FieldTypeOwner command
ownerstringTarget owner used by every GitHub recipe and generator. Letters, numbers, and hyphens are allowed.
repostringTarget repository used by every GitHub recipe and generator. Letters, numbers, dots, _, and - work.
topicsstring[]sync-identity. An empty array clears GitHub topics.
featuresobjectsync-features.
policiesobjectsync-policies.
securityobjectsync-security.
rulesetsobjectsync-rulesets.
actionsobjectsync-actions.
labelsobject[]sync-labels.
issueTemplateobjectnova generate github issue-template.

An omitted recipe field means “leave GitHub's current value alone.” It does not mean false, and Nova does not mix in GitHub defaults.

Features Fields

Booleans controlling which repository features are enabled. Each field is optional; omitted fields leave the corresponding GitHub setting untouched.

FieldTypeDescription
issuesbooleanEnables the Issues tab.
wikibooleanEnables the Wiki tab.
projectsbooleanEnables repository Projects.
discussionsbooleanEnables the Discussions tab.
sponsorshipsbooleanEnables the Sponsor button when GitHub considers it eligible.

Policies Fields

Repository policy settings. Each field is optional.

FieldTypeDescription
visibilitystringpublic, private, or internal.
defaultBranchstringDefault branch name. Nova skips the update if that branch does not exist yet.
mergeMethods.mergebooleanAllows merge commits.
mergeMethods.squashbooleanAllows squash merges.
mergeMethods.rebasebooleanAllows rebase merges.
mergeCommit.titlestringpull-request-title or merge-message.
mergeCommit.messagestringpull-request-body, pull-request-title, or blank; requires mergeCommit.title.
squashMerge.titlestringpull-request-title or commit-or-pull-request-title.
squashMerge.messagestringpull-request-body, commit-messages, or blank; requires squashMerge.title.
autoDeleteHeadBranchbooleanDeletes the head branch after a pull request is merged.
autoMergebooleanAllows pull-request auto-merge.
allowUpdateBranchbooleanAllows GitHub's update-branch action when a pull request is behind its base.
webCommitSignoffRequiredbooleanRequires signoff for commits created through GitHub's web interface.

Security Fields

FieldTypeDescription
vulnerabilityAlertsbooleanEnables Dependabot vulnerability alerts.
dependabotSecurityUpdatesbooleanEnables automatic security-update pull requests.
secretScanningbooleanEnables secret scanning.
pushProtectionbooleanBlocks pushes containing detected secrets.

pushProtection: true requires secretScanning: true in the same block. GitHub plan and organization policies still determine availability.

Ruleset Fields

These fields configure Nova's one named default-branch ruleset, Nova default branch.

FieldTypeDescription
defaultBranch.enforcementstringactive, disabled, or evaluate.
blockDeletionsbooleanBlocks default-branch deletion.
blockForcePushesbooleanBlocks force pushes.
requireLinearHistorybooleanRequires linear history.
requireSignedCommitsbooleanRequires signed commits.
requirePullRequestbooleanRequires pull requests.
allowedMergeMethodsstring[]One or more of merge, squash, and rebase when pull requests are required.
dismissStaleReviewsbooleanDismisses approvals after new commits.
requireCodeOwnerReviewbooleanRequires a code-owner review.
requireLastPushApprovalbooleanRequires someone other than the last pusher to approve.
requiredApprovalsnumberInteger from 0 through 10.
requireConversationResolutionbooleanRequires review threads to be resolved.
requiredStatusChecksstring[]Required status-check context names.
requireBranchesToBeUpToDatebooleanRequires a current branch and at least one required status check.

At least one protection rule must be enabled. Nova does not edit or delete unrelated rulesets.

Actions Fields

FieldTypeDescription
enabledbooleanEnables or disables Actions. Required with allowedActions or SHA pinning.
allowedActionsstringall, local-only, or selected.
shaPinningRequiredbooleanRequires full-SHA action references.
selectedActions.githubOwnedbooleanAllows GitHub-owned actions in selected mode.
selectedActions.verifiedbooleanAllows verified Marketplace creators in selected mode.
selectedActions.patternsstring[]Custom allowlist patterns. An empty array clears those patterns.
defaultWorkflowPermissionsstringDefault GITHUB_TOKEN permission: read or write.
canApprovePullRequestReviewsbooleanAllows Actions to create or approve pull-request reviews.
artifactRetentionDaysnumberInteger from 1 through 400; GitHub may enforce a lower plan maximum.

Label Fields

Each entry in labels has these fields. An explicit empty array is valid and performs no work. Labels missing from the array are not deleted.

FieldTypeDescription
namestringRequired non-empty label name.
colorstringRequired six-digit hexadecimal color without #.
descriptionstringOptional label description.

Issue Template Fields

FieldTypeDescription
bugReportFieldsstring[]Optional platform field filenames for generated bug reports, such as nodejs.yml. When omitted, the generator derives fields from project.platforms.
json
{
  "github": {
    "owner": "example-org",
    "repo": "example-project",
    "topics": ["nova", "monorepo", "typescript"],
    "features": {
      "issues": true,
      "wiki": false,
      "projects": false,
      "discussions": true,
      "sponsorships": true
    },
    "policies": {
      "visibility": "public",
      "defaultBranch": "main",
      "mergeMethods": {
        "merge": false,
        "squash": true,
        "rebase": false
      },
      "mergeCommit": {
        "title": "pull-request-title",
        "message": "pull-request-body"
      },
      "squashMerge": {
        "title": "commit-or-pull-request-title",
        "message": "commit-messages"
      },
      "autoDeleteHeadBranch": true,
      "autoMerge": true,
      "allowUpdateBranch": true,
      "webCommitSignoffRequired": false
    },
    "security": {
      "vulnerabilityAlerts": true,
      "dependabotSecurityUpdates": true,
      "secretScanning": true,
      "pushProtection": true
    },
    "rulesets": {
      "defaultBranch": {
        "enforcement": "active",
        "blockDeletions": true,
        "blockForcePushes": true,
        "requireLinearHistory": false,
        "requireSignedCommits": true,
        "requirePullRequest": true,
        "allowedMergeMethods": ["squash", "rebase"],
        "dismissStaleReviews": true,
        "requireCodeOwnerReview": false,
        "requireLastPushApproval": true,
        "requiredApprovals": 1,
        "requireConversationResolution": true,
        "requiredStatusChecks": ["check", "build"],
        "requireBranchesToBeUpToDate": true
      }
    },
    "actions": {
      "enabled": true,
      "allowedActions": "selected",
      "shaPinningRequired": true,
      "selectedActions": {
        "githubOwned": true,
        "verified": false,
        "patterns": ["actions/*", "acme/*"]
      },
      "defaultWorkflowPermissions": "read",
      "canApprovePullRequestReviews": false,
      "artifactRetentionDays": 30
    },
    "labels": [
      {
        "name": "bug",
        "color": "d73a4a",
        "description": "Something isn't working"
      },
      {
        "name": "good first issue",
        "color": "7057ff",
        "description": "Good for newcomers"
      }
    ],
    "issueTemplate": {
      "bugReportFields": ["nodejs.yml", "screenshots.yml"]
    }
  }
}

workflows

An array of GitHub Actions workflow entries consumed by nova generate github workflows. Each entry maps to one generated .yml file.

FieldTypeDescription
templatestringName of a bundled workflow template: "publish", "lock-inactive-issues", or "check-sponsor-gated-issues".
namestringRequired label appended to the output filename and workflow name. Must be unique within the same template.
triggersarrayTriggers for the template. Each is a bare string or an object such as { "name": "push", "branches": ["main"] }.
buildstring[]Optional. Workspace paths (keys from workspaces) that the check / build step should filter to.
deployobject[]Optional. Publish destinations for the publish template. Each destination has to, path, after, with.
withobjectOptional. Key-value pairs that remap secret / variable names or supply values for literal template variables.

Field names changed in the rebuilt generator: suffix is now name, scopes is now build, targets is now deploy, and settings is now with. The former top-level depends-on moved onto the workflow-run trigger object as a workflows array.

Trigger Object Fields

Use a bare string for triggers that need no filters, such as "release". Use an object when the trigger needs additional settings.

FieldTypeDescription
namestringRequired trigger name, such as "push", "tag-push", or "workflow-run-success".
branchesstring[]Branch filters for push. A push trigger requires at least one branch.
pathsstring[]Optional path filters for push.
tagsstring[]Optional tag filters for tag-push.
workflowsstring[]Upstream {template}-{name} keys for a workflow-run-* trigger. Any listed workflow can start the downstream run; GitHub does not wait for all of them.
json
{
  "name": "workflow-run-success",
  "workflows": ["publish-core"]
}

See Configuring Workflow-Run Triggers for chaining behavior and GitHub's limits.

Deploy Fields

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

FieldTypeDescription
tostringOne of: "npm", "github-action", "github-packages", "docker-hub", "ghcr", "cloudflare-pages-docusaurus", "cloudflare-workers", "github-pages-docusaurus", "vercel-nextjs".
pathstringPath to the workspace that owns the destination (e.g., "./packages/nova").
afterstring[]Optional. Paths of other same-type destinations that must finish publishing before this one starts.
withobjectOptional. Key-value pairs for this destination that remap names or supply literal values, overriding the workflow-level with.

Variable Formats

Each template declares variables with one of three formats. The format determines how values in with are used:

FormatWhat happens
secretProduces ${{ secrets.NAME }} in the YAML. A with value remaps the secret name.
varProduces ${{ vars.NAME }} in the YAML. A with value remaps the variable name.
literalReplaces the placeholder with the exact string from with. Must be provided or the entry is skipped.

Output Filenames

Generated files follow the pattern nova-{template}-{name}.yml under .github/workflows/.

json
{
  "workflows": [
    {
      "template": "lock-inactive-issues",
      "name": "project",
      "triggers": ["schedule-weekly"]
    },
    {
      "template": "publish",
      "name": "project",
      "triggers": ["release"],
      "build": [
        "./packages/core",
        "./packages/preset",
        "./apps/docs"
      ],
      "deploy": [
        {
          "to": "npm",
          "path": "./packages/core"
        },
        {
          "to": "npm",
          "path": "./packages/preset",
          "after": ["./packages/core"]
        },
        {
          "to": "cloudflare-pages-docusaurus",
          "path": "./apps/docs"
        }
      ]
    }
  ]
}

urls

Canonical links with validation and normalization.

FieldTypeDescription
homepagestringProject homepage URL.
repositorystringSource repository URL. Accepts git:, git+https:, git+ssh:, git+http:, http://, https://.
bugsstringIssue tracker URL.
licensestringLicense file URL.
logostringProject logo URL.
documentationstringDocumentation site URL.
npmstringnpm package page URL.
dockerstringDocker image registry page URL.
fundSourcesstring[]Funding URLs (entered comma-separated in the wizard, saved as a list).
privacyPolicystringPrivacy policy URL. Appears in generated GitHub issue templates.
termsOfUsestringTerms of use URL. Appears in generated GitHub issue templates.
json
{
  "urls": {
    "homepage": "https://example.com",
    "repository": "https://github.com/example/example-project",
    "bugs": "https://github.com/example/example-project/issues",
    "license": "https://github.com/example/example-project/blob/main/LICENSE",
    "logo": "https://example.com/assets/logo.svg",
    "documentation": "https://docs.example.com/project",
    "npm": "https://www.npmjs.com/package/example-project",
    "docker": "https://hub.docker.com/r/example/example-project",
    "fundSources": [
      "https://github.com/sponsors/example",
      "https://opencollective.com/example"
    ],
    "privacyPolicy": "https://example.com/privacy",
    "termsOfUse": "https://example.com/terms"
  }
}

workspaces

A map of relative paths to workspace definitions. Each key is a path from the monorepo root (e.g., "./", "./apps/docs", "./packages/nova").

FieldTypeDescription
namestringPackage name for package.json. Must follow the naming pattern for its role. See Workspace Rules for details.
rolestringWorkspace role: "project", "docs", "config", "app", "package", "tool", or "template". See Workspace Rules for details.
policystringWorkspace policy: "freezable", "trackable", or "distributable". See Workspace Rules for details.
json
{
  "workspaces": {
    "./": {
      "name": "example-project",
      "role": "project",
      "policy": "freezable"
    },
    "./packages/nova": {
      "name": "@company/example",
      "role": "package",
      "policy": "distributable"
    },
    "./apps/docs": {
      "name": "example-docs",
      "role": "docs",
      "policy": "freezable"
    }
  }
}

gitignore

Adds project-specific patterns to the generated root .gitignore without mixing them into Nova's built-in templates.

FieldTypeDescription
projectExcludesstring[]Optional patterns appended under the generated Project Excludes marker. An empty array keeps the section empty.
json
{
  "gitignore": {
    "projectExcludes": [
      ".wrangler/",
      "coverage/"
    ]
  }
}

agents

Selects the AI-tool entry files emitted by nova generate must-haves agent-conventions.

ValueFile emitted
"claude-code"CLAUDE.md
"codex"AGENTS.md

The shared VISION.md, PROJECT_RULES.md, and conventions/*.md files are generated whenever at least one agent is selected. An empty array is valid and intentionally disables generation.

json
{
  "agents": ["claude-code", "codex"]
}

recipes

Stores every recipe toggle in one top-level block. Repository, license, and README recipes are project-scoped; package-json recipes are nested under the workspace path they modify.

Recipe Entry Fields

FieldTypeDescription
enabledbooleanRequired. Runs the recipe when true and skips it when false.
settingsobjectOptional boolean settings supported by that recipe. Unknown or non-boolean settings are dropped.

Recipe Categories

CategorySupported recipes
githubsync-actions, sync-features, sync-identity, sync-labels, sync-policies, sync-rulesets, sync-security
licenseupdate-copyright
read-meupdate-badges, update-credits, update-documentation, update-header, update-introduction
package-jsoncleanup, normalize-artifacts, normalize-bundler, normalize-dependencies, normalize-modules, normalize-tooling, sync-environment, sync-identity, sync-ownership

Package JSON recipes accept these optional settings where applicable:

RecipeSettings
cleanupremoveUnknownKeys, reorderKeys
normalize-dependenciespinDependencyVersions, pinDevDependencyVersions
sync-environmenttrackNodeLtsVersions
sync-identitydescription, keywords, displayName for distributable workspaces
sync-ownershiphomepage, bugs, author, contributors, funding, repository for distributable workspaces
json
{
  "recipes": {
    "github": {
      "sync-identity": {
        "enabled": true
      }
    },
    "license": {
      "update-copyright": {
        "enabled": true
      }
    },
    "read-me": {
      "update-header": {
        "enabled": true
      }
    },
    "package-json": {
      "./": {
        "cleanup": {
          "enabled": true,
          "settings": {
            "removeUnknownKeys": true,
            "reorderKeys": true
          }
        }
      },
      "./packages/nova": {
        "sync-identity": {
          "enabled": true,
          "settings": {
            "description": true,
            "keywords": true,
            "displayName": true
          }
        }
      }
    }
  }
}

environment

Every environment value in the repository lives here, grouped by namespace and classified by its required reach. The nova generate must-haves dotenv command writes workspace values to local .env files, while publish workflows provision and deliver the non-local values.

FieldTypeDescription
projectobjectOptional. Project-wide managed keys, such as deploy credentials, under one shared prefix. See Project Fields.
workspacesobjectOptional. Per-workspace environment values, keyed by the workspace path (including the repo root ./). See Workspaces Fields.
workflowsobjectOptional. Workflow-config prefixes, keyed by workflow name. See Workflows Fields.

Every declared environment.project, environment.workspaces.<path> (including the repo root ./), and environment.workflows.<name> entry must declare a prefix — there is no exception for a group whose keys are all local. Nova joins that prefix to every key to form its GitHub name (for example, CBN_ joined to PUBLIC_SITE_KEY becomes CBN_PUBLIC_SITE_KEY).

Prefixes must be disjoint, must not reuse the reserved GITHUB_ namespace, and a key must not repeat its own prefix. The reserved dotenv keys NODE_ENV, LOG_LEVEL, and LOG_TIME are the only unprefixed, template-managed keys.

Project Fields

project holds project-wide keys under a single prefix. Each variable uses reach: "managed", is provisioned on GitHub, and is not written to a workspace .env or delivered to a build or server.

Project-scoped deploy credentials (such as a Cloudflare API token) also derive their GitHub name from this prefix.

FieldTypeDescription
prefixstringRequired. The uppercase namespace joined to every key.
variablesarrayOptional. Managed-only values, each with key, reach: "managed", and secret.

Workspaces Fields

environment.workspaces is keyed by a workspace path that matches a top-level workspaces entry (including the repo root ./). Each workspace declares a prefix; every value appears in its generated .env and .env.sample, while reach determines what happens beyond local development.

FieldTypeDescription
prefixstringRequired. The uppercase namespace joined to every key.
variablesarrayOptional. Workspace environment values. See Value Fields.

Value Fields

FieldTypeDescription
keystringEnvironment variable name. Nova joins the group's prefix when a non-local value needs a GitHub name; local .env files use the unprefixed key.
reachstringRequired. One of "local", "managed", "build", or "runtime". See Reach Values.
secretbooleanRequired for managed, build, and runtime; forbidden for local. true stores the GitHub value as a Secret, while false stores it as a Variable.
defaultValuestringOptional for non-secret local, build, and runtime values. Seeds .env.sample; for build, it is also the build fallback. Forbidden for managed values and every value with secret: true.

Reach Values

ReachLocal .envGitHubCI delivery
localNone. The key stays on the developer machine.
managed✓ (blank)None. Nova tracks the GitHub name but does not inject it into a build or server.
buildInjected into the build environment.
runtimeReconciled into every server-bearing deploy target for the workspace.

Project-scoped variables support only managed. Their Local .env column is not applicable because they do not belong to a workspace.

Workflows Fields

workflows is keyed by a workflow name and gives that workflow's config keys their own prefix.

FieldTypeDescription
prefixstringRequired. The uppercase namespace joined to every key.
json
{
  "environment": {
    "project": {
      "prefix": "ACCT_",
      "variables": [
        { "key": "NPM_TOKEN", "reach": "managed", "secret": true }
      ]
    },
    "workspaces": {
      "./": {
        "prefix": "ROOT_"
      },
      "./apps/web": {
        "prefix": "WEB_",
        "variables": [
          { "key": "LOCAL_API_MOCK", "reach": "local", "defaultValue": "http://127.0.0.1:8787" },
          { "key": "SENTRY_PROJECT", "reach": "managed", "secret": false },
          { "key": "PUBLIC_ANALYTICS_ID", "reach": "build", "secret": false, "defaultValue": "" },
          { "key": "STRIPE_SECRET_KEY", "reach": "runtime", "secret": true }
        ]
      }
    },
    "workflows": {
      "sponsor-check": {
        "prefix": "SGI_"
      }
    }
  }
}

settings

Project-wide behavior toggles that affect how Nova commands operate.

FieldTypeDescription
lockStepVersioningbooleanWhen true, nova utility changelog --release moves every non-freezable workspace — both trackable and distributable — to the same version, even if some had no recorded changes. Before writing, Nova requires every participating package.json to exist, contain a valid version for the selected strategy, and start at the same version. Workspaces without changes receive a "No changes." entry in their CHANGELOG.md.
versionStrategystringVersion strategy for the project: "semver" (default) or "calver". SemVer uses major.minor.patch with bump types. CalVer uses YYYY.MM.MICRO with automatic date-based versioning. Nova locks this setting to existing version headings found in the root or any non-freezable workspace changelog; missing changelogs and freezable workspaces do not lock it.
nova.config.json
json
{
  "settings": {
    "lockStepVersioning": true,
    "versionStrategy": "semver"
  }
}