config-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/dmno-dev/bumpy/main/packages/bumpy/config-schema.json",
  "title": "Bumpy Configuration",
  "description": "Configuration for @varlock/bumpy — monorepo versioning and changelog tool",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "description": "Path or URL to the JSON schema"
    },
    "baseBranch": {
      "type": "string",
      "description": "Branch used for release comparisons",
      "default": "main"
    },
    "access": {
      "type": "string",
      "enum": ["public", "restricted"],
      "description": "Default npm publish access level",
      "default": "public"
    },
    "versionCommitMessage": {
      "type": "string",
      "description": "Customize the commit message used when versioning. A plain string is used as-is. A path starting with \"./\" or \"../\" is loaded as a module that exports a function receiving the release plan and returning a message string."
    },
    "changelog": {
      "description": "Changelog formatter — \"default\", \"github\", or path to a custom formatter. Can also be a tuple of [formatter, options]. Set to false to disable changelog generation.",
      "default": "default",
      "oneOf": [
        { "type": "boolean", "const": false },
        { "type": "string" },
        {
          "type": "array",
          "items": [{ "type": "string" }, { "type": "object" }],
          "minItems": 2,
          "maxItems": 2
        }
      ]
    },
    "changedFilePatterns": {
      "type": "array",
      "description": "Glob patterns to filter which changed files count toward marking a package as changed. Can be overridden per-package.",
      "items": { "type": "string" },
      "default": ["**"]
    },
    "ignoredPackageJsonFields": {
      "type": "array",
      "description": "Top-level package.json fields whose change alone does not mark a package as changed. When package.json is the only changed file, it's diffed against the base branch and changes confined to these fields are ignored. Default: ['devDependencies']. A changed devDependencies entry matching the package's releaseTriggeringDevDeps still counts.",
      "items": { "type": "string" },
      "default": ["devDependencies"]
    },
    "fixed": {
      "type": "array",
      "description": "Package groups that always bump together to the same version. Each element is an array of package name globs.",
      "items": {
        "type": "array",
        "items": { "type": "string" }
      },
      "default": []
    },
    "linked": {
      "type": "array",
      "description": "Package groups that share the highest bump level. Each element is an array of package name globs.",
      "items": {
        "type": "array",
        "items": { "type": "string" }
      },
      "default": []
    },
    "ignore": {
      "type": "array",
      "description": "Package name globs to exclude from versioning",
      "items": { "type": "string" },
      "default": []
    },
    "include": {
      "type": "array",
      "description": "Package name globs to explicitly include (overrides ignore and privatePackages)",
      "items": { "type": "string" },
      "default": []
    },
    "updateInternalDependencies": {
      "type": "string",
      "enum": ["patch", "minor", "out-of-range"],
      "description": "When to update internal dependency version ranges",
      "default": "out-of-range"
    },
    "dependencyBumpRules": {
      "type": "object",
      "description": "Controls how bumps propagate through dependency types",
      "properties": {
        "dependencies": { "$ref": "#/$defs/dependencyBumpRule" },
        "devDependencies": { "$ref": "#/$defs/dependencyBumpRule" },
        "peerDependencies": { "$ref": "#/$defs/dependencyBumpRule" },
        "optionalDependencies": { "$ref": "#/$defs/dependencyBumpRule" }
      },
      "additionalProperties": false
    },
    "privatePackages": {
      "type": "object",
      "description": "Whether to version and/or create git tags for private packages",
      "properties": {
        "version": {
          "type": "boolean",
          "description": "Whether to version private packages",
          "default": false
        },
        "tag": {
          "type": "boolean",
          "description": "Whether to create git tags for private packages",
          "default": false
        }
      },
      "additionalProperties": false
    },
    "allowCustomCommands": {
      "description": "Allow per-package custom commands (buildCommand, publishCommand, checkPublished) defined in package.json \"bumpy\" fields. true = allow all, string[] = allow matching package name globs, false = only root-config commands allowed.",
      "default": false,
      "oneOf": [
        { "type": "boolean" },
        {
          "type": "array",
          "items": { "type": "string" }
        }
      ]
    },
    "packages": {
      "type": "object",
      "description": "Per-package config overrides, keyed by package name or glob pattern",
      "additionalProperties": { "$ref": "#/$defs/packageConfig" }
    },
    "publish": {
      "type": "object",
      "description": "Publishing pipeline configuration",
      "properties": {
        "packManager": {
          "type": "string",
          "enum": ["auto", "npm", "pnpm", "bun", "yarn"],
          "description": "Package manager to use for packing. \"auto\" detects from lockfile.",
          "default": "auto"
        },
        "publishManager": {
          "type": "string",
          "enum": ["npm", "pnpm", "bun", "yarn"],
          "description": "Command to use for publishing. npm supports OIDC/provenance.",
          "default": "npm"
        },
        "publishArgs": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Extra args appended to the publish command (e.g., \"--tag next\")",
          "default": []
        },
        "protocolResolution": {
          "type": "string",
          "enum": ["pack", "in-place", "none"],
          "description": "How to handle workspace:/catalog: protocol resolution. \"pack\" = use PM's pack to build a clean tarball, \"in-place\" = rewrite package.json before publish, \"none\" = don't resolve.",
          "default": "pack"
        },
        "provenance": {
          "type": "boolean",
          "description": "Attach provenance attestation when publishing via npm. Requires a supported CI environment with OIDC (GitHub Actions, GitLab CI, etc.). Only works with publishManager \"npm\".",
          "default": false
        },
        "npmStaged": {
          "type": "boolean",
          "description": "Use npm staged publishing (`npm stage publish`). Stages the publish on npmjs.com, requiring manual 2FA approval before going live. Only works with publishManager \"npm\" and requires npm >= 11.15.0.",
          "default": false
        }
      },
      "additionalProperties": false
    },
    "gitUser": {
      "type": "object",
      "description": "Git identity used for CI commits",
      "properties": {
        "name": {
          "type": "string",
          "description": "Git user name",
          "default": "bumpy-bot"
        },
        "email": {
          "type": "string",
          "description": "Git user email",
          "default": "276066384+bumpy-bot@users.noreply.github.com"
        }
      },
      "additionalProperties": false
    },
    "versionPr": {
      "type": "object",
      "description": "Customize the version PR created by bumpy ci release",
      "properties": {
        "title": {
          "type": "string",
          "description": "PR title",
          "default": "🐸 Versioned release"
        },
        "branch": {
          "type": "string",
          "description": "Branch name for the version PR",
          "default": "bumpy/version-packages"
        },
        "preamble": {
          "type": "string",
          "description": "HTML/markdown content prepended to the PR body"
        }
      },
      "additionalProperties": false
    },
    "channels": {
      "type": "object",
      "description": "Prerelease channels, keyed by channel name. Each maps a long-lived branch to a prerelease line (version suffix + npm dist-tag). Prerelease versions are derived at publish time and never committed.",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "branch": {
            "type": "string",
            "description": "Branch that triggers this channel (required)"
          },
          "preid": {
            "type": "string",
            "description": "Version suffix (preid), e.g. \"rc\" produces 1.2.0-rc.0. Defaults to the channel name."
          },
          "tag": {
            "type": "string",
            "description": "npm dist-tag for publishes. Defaults to the channel name."
          },
          "versionPr": {
            "type": "object",
            "description": "Release PR overrides for this channel",
            "properties": {
              "title": {
                "type": "string",
                "description": "Release PR title. Defaults to \"<base title> (<channel name>)\"."
              },
              "branch": {
                "type": "string",
                "description": "Release PR branch. Defaults to \"<base branch>-<channel name>\"."
              },
              "automerge": {
                "type": "boolean",
                "description": "Enable auto-merge on the release PR",
                "default": false
              }
            },
            "additionalProperties": false
          }
        },
        "required": ["branch"],
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false,
  "$defs": {
    "bumpType": {
      "type": "string",
      "enum": ["major", "minor", "patch"]
    },
    "cascadeConfig": {
      "oneOf": [
        {
          "type": "array",
          "description": "List of package names/glob patterns (defaults: trigger \"patch\", bumpAs \"match\")",
          "items": { "type": "string" }
        },
        {
          "type": "object",
          "description": "Package name/glob patterns mapped to cascade rules",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "trigger": {
                "$ref": "#/$defs/bumpType",
                "description": "Minimum bump level that triggers the cascade (default: \"patch\")"
              },
              "bumpAs": {
                "description": "What level to bump the target (default: \"match\")",
                "oneOf": [{ "$ref": "#/$defs/bumpType" }, { "type": "string", "const": "match" }]
              }
            },
            "additionalProperties": false
          }
        }
      ]
    },
    "dependencyBumpRule": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "trigger": {
              "$ref": "#/$defs/bumpType",
              "description": "Minimum bump level that triggers propagation"
            },
            "bumpAs": {
              "description": "What level to bump the dependent (\"match\" mirrors the triggering level)",
              "oneOf": [{ "$ref": "#/$defs/bumpType" }, { "type": "string", "const": "match" }]
            }
          },
          "required": ["trigger", "bumpAs"],
          "additionalProperties": false
        },
        {
          "type": "boolean",
          "const": false,
          "description": "Set to false to disable propagation for this dependency type"
        }
      ]
    },
    "packageConfig": {
      "type": "object",
      "description": "Per-package configuration",
      "properties": {
        "managed": {
          "type": "boolean",
          "description": "Explicitly opt this package in or out of version management"
        },
        "directBump": {
          "type": "boolean",
          "description": "When false, this package can never be bumped directly by a bump file — it only receives propagated bumps (fixed/linked group, cascade, dependency). Use for derived artifacts like platform binary packages kept in a fixed group with their core package."
        },
        "access": {
          "type": "string",
          "enum": ["public", "restricted"],
          "description": "Override the global access level"
        },
        "publishCommand": {
          "description": "Custom command(s) to publish this package (replaces npm publish)",
          "oneOf": [
            { "type": "string" },
            {
              "type": "array",
              "items": { "type": "string" }
            }
          ]
        },
        "buildCommand": {
          "type": "string",
          "description": "Command to run before publishing"
        },
        "registry": {
          "type": "string",
          "description": "Custom npm registry URL"
        },
        "skipNpmPublish": {
          "type": "boolean",
          "description": "Don't publish to npm (still creates git tags)"
        },
        "checkPublished": {
          "type": "string",
          "description": "Custom command that outputs the currently published version"
        },
        "changedFilePatterns": {
          "type": "array",
          "description": "Glob patterns to filter which changed files count toward marking this package as changed (overrides root setting)",
          "items": { "type": "string" }
        },
        "dependencyBumpRules": {
          "type": "object",
          "description": "Per-package override for dependency propagation rules",
          "properties": {
            "dependencies": { "$ref": "#/$defs/dependencyBumpRule" },
            "devDependencies": { "$ref": "#/$defs/dependencyBumpRule" },
            "peerDependencies": { "$ref": "#/$defs/dependencyBumpRule" },
            "optionalDependencies": { "$ref": "#/$defs/dependencyBumpRule" }
          },
          "additionalProperties": false
        },
        "cascadeTo": {
          "description": "Explicit cascade targets — when this package is bumped, cascade to matching packages.",
          "$ref": "#/$defs/cascadeConfig"
        },
        "cascadeFrom": {
          "description": "Explicit cascade sources — when a matching package is bumped, cascade the bump to this package.",
          "$ref": "#/$defs/cascadeConfig"
        },
        "releaseTriggeringDevDeps": {
          "type": "array",
          "description": "Names (or globs) of devDependencies that are release-relevant: a change to one requires a release of this package, and (for internal workspace deps) its own releases cascade here. devDependencies are ignored for versioning by default — this opts specific entries back in. The usual reason is a dep bundled into the published output (inlined by tsup/tsdown/esbuild/rollup/…). Shorthand for a cascadeFrom rule of { trigger: 'patch', bumpAs: 'patch' }; an explicit cascadeFrom for the same source takes precedence.",
          "items": { "type": "string" }
        }
      },
      "additionalProperties": false
    }
  }
}