Changelog

CI

The ci section drives everything Conventional Commits (by default): the CI that lints commit messages, the local husky hook, the commitlint.config.mjs, the GitHub workflows, and the changelog pipeline that bumps versions and writes CHANGELOG.md. Its ci.changelog config holds the changelog-specific options.

dbx.config.ts

export default defineConfig({
    toolchain: {
        ci: {
            ci: true,
            release: true,
            changelog: {
                branches: { main: 'main', dev: 'dev' },
                commitlint: {
                    types: ['feat', 'fix', 'docs', 'chore'],
                    scopes: ['api', 'web', 'deps'],
                },
                versioning: { target: 'individual', workspaces: ['packages/*', 'apps/*'] },
            },
        },
    },
});

dbx sync writes the opted-in GitHub workflows (.github/workflows), the commitlint config, and the husky commit-msg hook (.husky/commit-msg). Activate the hook with a postinstall script (Yarn Berry never runs prepare):

package.json

{ "scripts": { "commitlint": "commitlint", "postinstall": "husky" } }

See Package scripts for the full recommended script set.

Group order and titles

groups customizes the Conventional-Commits sections. It works on both toolchain.changelog.groups (manual runs) and ci.changelog.groups (CI + manual when inherited). An array sets the order and optionally the titles:

ci: {
    changelog: {
        groups: [
            { type: 'feat', title: 'New Features' },
            { type: 'fix', title: 'Bug Fixes' },
            'perf',
        ],
    },
}

A record is a shorthand for the same thing, ordered by its keys. Use false to hide a group:

groups: {
    feat: 'New Features',
    fix: 'Bug Fixes',
    chore: false,
}

The default order is Breaking Changes, feat, fix, then the remaining types (perf, refactor, docs, ...). Types you do not mention are appended in the default order. order overrides the array/record position, and every title/order/hidden value accepts a callback. The whole groups value can also be a callback, so it can be computed from the types/items in the current run:

groups: context => [
    {
        type: 'feat',
        title: group => `New Features (${group.groupItems.length})`,
        order: 0,
    },
    { type: 'fix', hidden: group => group.groupItems.length === 0 },
    ...context.types.filter(type => !['feat', 'fix'].includes(type)),
];

Callbacks are TS/JS-config-only. dbx changelog --format-only also uses the configured order/titles when regrouping existing entries.

Breaking-change detection

Breaking commits are detected by Conventional Commits rules by default: a ! before the subject colon (feat!:, feat(scope)!:) or a BREAKING CHANGE: / BREAKING-CHANGE: footer line. Configure breaking on either toolchain.changelog or ci.changelog to override it:

breaking: 'conventional', // default
// breaking: 'any',       // legacy loose match anywhere in the subject/body
// breaking: false,       // disable breaking detection
// breaking: { pattern: '^feat!:' },
// breaking: { match: 'BREAKING CHANGE' },
// breaking: ({ subject, body }) => subject.includes('!'),

The same setting is used for version bumps, changelog grouping and --format-only regrouping.

Manual toolchain.changelog

The top-level changelog section configures manual runs for dbx changelog, the VS Code actions and the programmatic API. It accepts the pipeline options (commitlint, versioning, groups, VS Code settings), but not the CI-only workflow options or branches:

manual pipeline

toolchain: {
    changelog: {
        commitlint: { types: ['feat'], scopes: ['api'] },
        versioning: true,
        vscode: true,
    },
}

Move the generated workflows to the top-level ci section, and put the pipeline options under ci.changelog when CI should use them too. Branches and workflow overrides only exist on ci.changelog:

after

toolchain: {
    ci: {
        ci: true,
        release: true,
        changelog: {
            branches: { main: 'main' },
            commitlint: { types: ['feat'], scopes: ['api'] },
            versioning: true,
            vscode: true,
        },
    },
}

ci.changelog inherits toolchain.changelog when it is enabled without pipeline options (ci.changelog: true, a raw workflow string, or workflow-only overrides). Options set explicitly on ci.changelog win.

Where to start

• CI — the opt-in GitHub workflows (CI checks, changelog, release, issues, sync) and their common settings.
• Branches — main/dev branch globs.
• commitlint — config location, types/scopes and the no-commitlint fallback.
• Versioning — which package.json versions a run bumps.
• CLI — running the changelog locally.
• Writing commit messages — avoiding shell-mangled messages.
• Troubleshooting — the upstream commitlint parser-preset error.
• Releases — the aggregated release PR body.