Documentation menuSources
Sources
Changesets, CHANGELOG.md formats, conventional commits, GitHub and GitLab Releases, Linear, Jira and Notion.
Derivative picks the source automatically: if CHANGELOG.md exists it reads that file, otherwise it reads GitHub Releases when repo is set, and git in all other cases. GitLab Releases are read when project is set and nothing else matches. Set --source changelog, --source github, --source gitlab, --source git, --source linear, --source jira or --source notion to choose explicitly. The tracker sources are never picked automatically.
Changesets
The default and the @changesets/changelog-github formats are both understood. Headings map to entry types:
| Heading | Type in the widget |
|---|---|
| Major Changes | Breaking |
| Minor Changes | New |
| Patch Changes | Fixed |
Commit hashes and "Thanks @user!" prefixes are removed, the pull request link is kept. "Updated dependencies" entries are left out. Changesets writes no dates, so Derivative looks up the matching git tag (v1.2.0, 1.2.0 or @scope/pkg@1.2.0) and uses its date.
In a monorepo, pass each package changelog. Every release then carries its package name:
npx derivative build --changelog packages/app/CHANGELOG.md --changelog packages/sdk/CHANGELOG.md
Keep a Changelog and conventional-changelog
## [1.2.0] - 2026-10-01 and ## [1.2.0](compare-url) (2026-10-01) headings both work. Sections map like this:
| Section | Type |
|---|---|
| Added, Features | New |
| Changed, Improvements, Performance Improvements | Improved |
| Fixed, Bug Fixes | Fixed |
| Security | Security |
| Deprecated | Deprecated |
| Removed | Removed |
| Breaking Changes | Breaking |
## [Unreleased] is skipped unless you pass --unreleased.
Conventional commits
With --source git, every tag that contains a version starts a release, and the commits up to the previous tag are its entries:
| Commit | Type |
|---|---|
feat: | New |
fix: | Fixed |
perf: | Improved |
security: | Security |
deprecate: | Deprecated |
feat!: or a BREAKING CHANGE: footer | Breaking |
chore, ci, docs, test, refactor, build and style commits are left out because readers of a "What's new" panel don't care about them. Add [skip changelog] to any commit message to leave it out as well. Change the mapping with types in the config.
In a monorepo with tags like @acme/app@1.2.0, limit releases to one package with --tag-pattern "^@acme/app@". Link entries to commits with --commit-url "https://github.com/acme/app/commit/{hash}".
GitHub Releases
If you write release notes on GitHub instead of a CHANGELOG.md, read them from the API:
npx derivative build --source github --repo acme/app
Drafts are skipped, pre-releases too unless you pass --prereleases. The version comes from the tag, the release name becomes the title when it says more than the tag. Notes generated by GitHub ("What's Changed") are cleaned up: the "New Contributors" section and the "Full Changelog" line are removed, "by @user in URL" becomes a link, and conventional prefixes like feat: or fix: set the entry type. Hand-written notes with ### Added or ### Fixed sections map like a changelog.
Public repositories work without a token. For private repositories, or to avoid the rate limit in CI, set GITHUB_TOKEN; in GitHub Actions the built-in ${{ secrets.GITHUB_TOKEN }} is enough.
GitLab Releases
The same works for GitLab, including self-managed instances:
npx derivative build --source gitlab --project acme/team/app
npx derivative build --source gitlab --project 1234 --gitlab-url https://git.example.com
--project is the project path (group/name, subgroups allowed) or its numeric id. Release notes are read like GitHub's: the tag gives the version, the name becomes the title when it says more than the tag, ### Features or ### Fixed sections and conventional prefixes set the entry types. Upcoming releases are skipped unless you pass --prereleases. Public projects work without a token; for private projects set GITLAB_TOKEN (a token with read_api). In GitLab CI, create a project access token and expose it as that variable.
Monorepos
When one feed covers several packages, every release carries its package name. Limit the feed at build time, or let each widget pick its own packages from a shared feed:
npx derivative build --package "@acme/web" --package "@acme/ui-*"
npx derivative build --exclude-package "@acme/internal-*"
--package keeps only matching packages, --exclude-package drops matching ones afterwards. A name matches exactly, or as a prefix when it ends in *. In the config they are packages and excludePackages. The widget has the same filter as an attribute, see the widget guide: <derivative-widget src="/changelog.json" package="@acme/web"> shows, counts and marks as read only that package.
Linear, Jira and Notion (beta)
If product and support write down what shipped in a tracker, Derivative can read it. These sources only read, use a token that you create and keep in the environment, and never write back. They are beta: tested against fixtures of the documented API responses, not yet against live accounts. Try them with a read-only token and look at the result before you publish. These readers fetch the first 100 issues of a cycle, 20 Jira versions and 300 Notion pages, with no retry; Derivative Pro reads everything, retries on rate limits and writes the result as drafts for review.
All three decide the entry type from labels or the issue type (case-insensitive): feature, new feature, story → New; improvement, enhancement, task → Improved; bug, fix, defect → Fixed; security; breaking; deprecation; removal. Everything else becomes Improved. Add or change mappings with types and the fallback with fallback. Tickets labelled internal, no-changelog or skip-changelog stay out (change the list with excludeLabels). A label audience:pro sets the entry's audience, which the widget's audience attribute uses.
Linear
Every completed cycle of a team becomes a release (newest 50). Issues completed in it are its entries; the cycle name is the title.
{ "source": "linear", "linear": { "team": "ENG" } }
Create a personal API key with read access and set LINEAR_API_KEY.
Jira
Every released version of a Jira Cloud project becomes a release (newest 20). Issues with that fixVersion are its entries, linked to the ticket. A version name like 2.4.0 is the version; any other name becomes the title. The version description becomes the summary.
{ "source": "jira", "jira": { "url": "https://acme.atlassian.net", "project": "ACME" } }
Set JIRA_EMAIL and JIRA_API_TOKEN (an API token of that account). "includeUnreleased": true also reads versions that are not released yet.
Notion
Pages of a database become entries, grouped by their Version property. Name is the text, Type the entry type, Date the release date, Audience (multi-select) the audiences.
{
"source": "notion",
"notion": {
"database": "0123456789abcdef0123456789abcdef",
"properties": { "published": "Published" }
}
}
With properties.published, only pages with that checkbox ticked are included. Rename the columns through properties (title, version, type, date, audience). Create an internal integration, share the database with it and set NOTION_TOKEN.