Getting Started

Go from zero to release notes in under two minutes.

Installation

Install Cullit globally or use it with npx — no install needed:

# Run without installing
npx cullit generate --from HEAD~10 --provider none

# Or install globally
npm install -g cullit

# Or with pnpm
pnpm add -g cullit

Your First Run

Navigate to any Git repository and run:

# Generate notes from the last 10 commits, no AI key required
cullit generate --from HEAD~10 --provider none

# Generate notes between two tags with AI
cullit generate --from v1.0.0 --to v1.1.0

# Auto-detect: uses the two most recent tags
cullit generate

Cullit collects commits, enriches with ticket context (if configured), runs them through AI, and outputs categorized release notes.

How Cullit Uses AI

Cullit’s AI layer is grounded in shipping data. The model sees commit history first, then richer release context from Jira, Linear, GitHub, or GitLab when configured. That means the output is based on what changed, why it changed, and who the release is for.

Open Source & Support

Cullit is fully open source and free to use. There are no paid tiers, no checkout flow, and no feature-gated integrations.

• Use Everything — AI providers, enrichers, publishers, and dashboard workflows are all available.
• Support Development — sponsor at GitHub Sponsors if Cullit helps your team.
• Contribute — issues, PRs, docs updates, and testing feedback keep the project healthy.

Use provider keys in your environment when you want AI generation (for example ANTHROPIC_API_KEY or OPENAI_API_KEY). Use --provider none for template-only generation with no provider key.

There is no paid activation key required for Cullit features.

Configuration

Create a .cullit.yml in your project root. You can generate one interactively:

cullit init

Full config reference:

# .cullit.yml

ai:
  provider: anthropic        # anthropic | openai | gemini | ollama | none
  model: claude-sonnet-4-20250514  # optional: override default model
  audience: developer       # developer | end-user | executive
  tone: professional        # professional | casual | terse | edgy | hype | snarky
  categories:              # customize change categories
    - features
    - fixes
    - breaking
    - improvements
    - chores

source:
  type: local               # local | jira | linear | gitlab | bitbucket | multi-repo
  enrichment:              # enrich git commits with ticket data
    - jira
    - linear

publish:
  - type: stdout
  - type: file
    path: RELEASE_NOTES.md
  - type: slack
    webhook_url: $SLACK_WEBHOOK_URL
  - type: discord
    webhook_url: $DISCORD_WEBHOOK_URL

jira:
  domain: yourcompany.atlassian.net
  # Set JIRA_EMAIL and JIRA_API_TOKEN in your environment

linear:
  # Set LINEAR_API_KEY in your environment

AI Providers

Cullit supports five providers in open-source mode. Use --provider none for template-only generation or configure provider API keys for AI generation.

Environment Variables

Cullit reads these from your shell or a .env file in the project root:

CLI Reference

cullit generate

Generate release notes from git commits, Jira issues, or Linear tickets.

# Between two tags
cullit generate --from v2.3.0 --to v2.4.0

# Last N commits, JSON output
cullit generate --from HEAD~15 --format json

# Executive summary with Gemini
cullit generate --from v1.0.0 --audience executive --provider gemini

# From Jira sprint
cullit generate --source jira --from "project = PROJ AND sprint = 'Sprint 42'"

# From Linear team
cullit generate --source linear --from "team:ENG"

# No AI key, template engine
cullit generate --from HEAD~5 --provider none

# Local Ollama
cullit generate --from v1.0.0 --provider ollama --model llama3.2:3b

cullit status

Release readiness check. Analyzes unreleased commits and recommends whether it's time to release, what semver bump to use, and why.

cullit status

# Output:
  Current version:   v1.2.0
  Suggested next:    v1.3.0 (minor)
  Last release:      12 day(s) ago
  Unreleased commits: 8
  Contributors:      3

  Commit breakdown:
    ✨ Features:  ████████████████████ 4
    🐛 Fixes:     ██████████ 2
    🧹 Chores:    █████ 1
    📝 Other:     █████ 1

  Should you release? 🟢 Yes — time to release

  Why:
    → 4 new feature(s) — minor bump recommended
    → 8 commit(s) since v1.2.0 — consider releasing

The advisor also runs automatically after cullit generate and nudges you when thresholds are met (suppressed in --quiet mode).

Release advisor signals

The advisor emits one of three signals based on commit volume, time since last release, and change type mix:

  Should you release? 🟢 Yes – time to release
  # 1+ feature, fix or breaking change; ≥3 unreleased commits; ≥3 days since last release.

  Should you release? 🟡 Maybe – a few changes ready
  # Changes exist but thresholds not fully met (e.g. only chores/docs, or < 3 commits).

  Should you release? 🔴 Not yet – nothing worth releasing
  # Zero unreleased commits, or only automated bumps / dependency updates.

cullit init

Interactive config setup. Creates a .cullit.yml with your preferences:

cullit init

# Prompts for: provider, source, audience, tone, enrichment
# Creates .cullit.yml in the current directory

cullit tags

Lists recent git tags in the repository — useful for finding the right --from ref:

cullit tags

Recent tags:
  → v2.4.0
    v2.3.0
    v2.2.1
    v2.2.0

Integrations

GitHub Action

Add Cullit to your CI/CD pipeline with zero configuration:

# .github/workflows/release-notes.yml
name: Release Notes
on:
  push:
    tags: ['v*']

jobs:
  release-notes:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # for GitHub Release
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0  # full history for tag comparison

      - uses: mttaylor/cullit@v2
        with:
          provider: anthropic
          audience: end-user
          publish-github-release: 'true'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Action inputs:

GitHub App

The Cullit GitHub App auto-generates release notes when you push a tag or publish a release — no CI config needed. Install it from the GitHub Marketplace and it just works.

How it works:

1. You push a tag or publish a GitHub Release
2. The App receives a webhook, clones your repo, and runs the Cullit pipeline
3. Release notes are created or updated on your GitHub Release
4. If configured, notes are also auto-posted to Slack, Discord, Teams, and/or the hosted changelog

Self-hosting:

# docker-compose.yml
services:
  app:
    build:
      context: .
      dockerfile: packages/app/Dockerfile
    ports: ["3001:3001"]
    environment:
      GITHUB_APP_ID: ${GITHUB_APP_ID}
      GITHUB_APP_PRIVATE_KEY: ${GITHUB_APP_PRIVATE_KEY}
      GITHUB_WEBHOOK_SECRET: ${GITHUB_WEBHOOK_SECRET}

Environment variables:

Multi-Repo Aggregation

Aggregate release notes across multiple repositories into a single changelog — ideal for monorepo-adjacent setups, platform teams, or microservices.

# .cullit.yml
source:
  type: multi-repo

repos:
  - url: https://github.com/acme/api.git
    name: API
  - url: https://github.com/acme/web.git
    name: Web
  - path: ../shared-lib
    name: Shared

CLI usage:

cullit generate --source multi-repo --from v1.0.0 --to v1.1.0

GitHub Action:

- uses: mttaylor/cullit@v2
  with:
    source: multi-repo
    from: v1.0.0
    config: .cullit.yml

Each repo can specify its own from/to refs. Commits are tagged with [repo-name] prefix for traceability. Both local paths and remote URLs are supported (remote repos are shallow-cloned).

Jira Integration

Cullit can use Jira as a primary source (replace git) or as enrichment (add ticket context to git commits).

As primary source:

# Query completed issues by project
cullit generate --source jira --from PROJ

# By sprint
cullit generate --source jira --from "project = PROJ AND sprint = 'Sprint 42'"

# By fix version
cullit generate --source jira --from PROJ --to v2.0

As enrichment (adds Jira details to git commits):

# .cullit.yml
source:
  type: local
  enrichment: [jira]

jira:
  domain: yourcompany.atlassian.net

Set JIRA_EMAIL and JIRA_API_TOKEN in your environment.

Linear Integration

Works the same way — as a primary source or enrichment.

As primary source:

# By team
cullit generate --source linear --from "team:ENG"

# By project
cullit generate --source linear --from "project:Mobile App"

# By label
cullit generate --source linear --from "label:release-v2"

# Current cycle
cullit generate --source linear --from "cycle:current"

As enrichment:

# .cullit.yml
source:
  type: local
  enrichment: [linear]

Set LINEAR_API_KEY in your environment.

Publishing

Cullit publishes to multiple targets simultaneously. Configure in .cullit.yml.

stdout & File

publish:
  - type: stdout           # print to terminal
  - type: file
    path: RELEASE_NOTES.md # write to file

Slack

Create an incoming webhook in your Slack workspace, then:

publish:
  - type: slack
    webhook_url: $SLACK_WEBHOOK_URL

Cullit formats notes with emoji categories and Slack mrkdwn syntax.

Discord

Create a webhook in your Discord channel settings, then:

publish:
  - type: discord
    webhook_url: $DISCORD_WEBHOOK_URL

Posts as a rich embed with the Cullit accent color.

GitHub Release

Automatically creates or updates a GitHub Release. Works in GitHub Actions (uses GITHUB_TOKEN automatically):

publish:
  - type: github-release

GitLab Release Pro

Create or update a GitLab Release via the GitLab API. Supports self-hosted GitLab instances. Requires GITLAB_TOKEN with api scope:

publish:
  - type: gitlab-release

Set GITLAB_URL for self-hosted instances (defaults to https://gitlab.com). The project is auto-detected from your git remote or can be set with GITLAB_PROJECT_ID.

Microsoft Teams

Post release notes to a Teams channel via incoming webhook:

publish:
  - type: teams
    webhook_url: $TEAMS_WEBHOOK_URL

Confluence

Publish release notes as a Confluence page. Requires CONFLUENCE_EMAIL and CONFLUENCE_API_TOKEN environment variables:

publish:
  - type: confluence

Notion

Add release notes to a Notion database. Requires NOTION_API_KEY environment variable:

publish:
  - type: notion

Hosted Changelog

Push release notes to Cullit's hosted changelog — a public, embeddable page that your users can visit or you can embed in your app with the widget.

publish:
  - type: changelog

Your changelog will be available at cullit.io/changelog?project=your-project. To embed a “What's New” widget in your app:

<script src="https://cullit.io/widget.js" data-project="your-project"></script>

For authenticated hosted API routes, set CULLIT_API_KEY when needed. Core local generation does not require this key. The GitHub App can also auto-publish to the hosted changelog — set CULLIT_APP_CHANGELOG_ENABLED=true.

Advanced Usage

Library Usage

Use Cullit programmatically in your Node.js / TypeScript projects:

npm install @cullit/core @cullit/config

import { runPipeline, createLogger } from '@cullit/core';
import { loadConfig } from '@cullit/config';

const config = loadConfig();
const logger = createLogger('verbose');

const result = await runPipeline('v1.0.0', 'HEAD', config, {
  format: 'markdown',
  dryRun: true,
  logger,
});

console.log(result.formatted);     // the release notes string
console.log(result.notes.changes); // structured change entries
console.log(result.duration);      // pipeline duration in ms

Packages:

Release Advisor

The release advisor analyzes your unreleased commits and recommends when to release:

import { analyzeReleaseReadiness } from '@cullit/core';

const advisory = analyzeReleaseReadiness();

console.log(advisory.shouldRelease);   // true | false
console.log(advisory.suggestedBump);   // 'patch' | 'minor' | 'major'
console.log(advisory.nextVersion);     // 'v1.3.0'
console.log(advisory.reasons);         // ['4 new features', '12 days since last release']
console.log(advisory.breakdown);       // { features: 4, fixes: 2, breaking: 0, ... }

Heuristics that trigger a release recommendation:

• 5+ unreleased commits accumulated
• 3+ new features
• Any breaking changes
• Security-related commits (keywords: security, CVE, vulnerability)
• 14+ days since last release

API Server

Cullit includes a lightweight REST API for programmatic access:

# Start the server
node packages/api/dist/index.js

# Generate release notes
curl -X POST http://localhost:3000/generate \
  -H "Content-Type: application/json" \
  -d '{"from": "v1.0.0", "provider": "none"}'

Endpoints:

Configuration:

Team & Org Behavior:

• Reducing seats: Reducing org seats revokes excess team API keys. Remaining keys stay active.
• Removing an org member: That member's team API key is revoked immediately.
• Database required: Orgs and team features require DATABASE_URL. Without it, the server runs in file-backed mode (suitable for local dev only).

Web Dashboard

Cullit includes a browser-based dashboard at dashboard.html for visually generating release notes without the CLI.

Features:

• Point-and-click configuration (provider, audience, tone, format)
• Real-time pipeline output preview
• Copy-to-clipboard export
• Connects to the API Server

Quick start:

# Start the API server
node packages/api/dist/index.js

# Open dashboard in your browser
open site/dashboard.html

Real-World Walkthrough

Here's exactly how you'd set up Cullit for a real project from scratch.

Scenario

You maintain a SaaS product called Acme Dashboard. Your team uses GitHub for code, Jira for project management, and Slack for comms. You want release notes auto-generated when you push a tag.

Step 1 — Install & Initialize

cd ~/projects/acme-dashboard
npm install -g cullit
cullit init

# Answer the prompts:
  AI provider: anthropic
  Source type: local
  Audience: end-user
  Tone: professional
  Enrich from: jira
  ✓ Created .cullit.yml

Step 2 — Configure Integrations

Edit the generated .cullit.yml:

ai:
  provider: anthropic
  audience: end-user     # customer-facing notes
  tone: professional

source:
  type: local
  enrichment: [jira]    # pull ticket context

publish:
  - type: stdout
  - type: file
    path: CHANGELOG.md
  - type: slack
    webhook_url: $SLACK_WEBHOOK_URL

jira:
  domain: acme.atlassian.net

Step 3 — Set Environment Variables

# .env (add to .gitignore!)
ANTHROPIC_API_KEY=sk-ant-...
JIRA_EMAIL=matt@acme.com
JIRA_API_TOKEN=ATATT3x...
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../...

Step 4 — Test Locally

# Preview notes from the last 5 commits (dry run)
cullit generate --from HEAD~5 --dry-run

# Check readiness
cullit status

# Full run between tags
cullit generate --from v2.3.0 --to v2.4.0

Step 5 — Automate with GitHub Actions

Create .github/workflows/release-notes.yml:

name: Release Notes
on:
  push:
    tags: ['v*']

permissions:
  contents: write

jobs:
  notes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - uses: mttaylor/cullit@v2
        with:
          provider: anthropic
          audience: end-user
          publish-github-release: 'true'
          publish-slack-webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
          jira-domain: acme.atlassian.net
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
          JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Step 6 — Ship a Release

# Check if it's time to release
cullit status

# Tag and push
git tag v2.4.0
git push origin v2.4.0

# GitHub Actions fires automatically:
#   → Collects commits v2.3.0..v2.4.0
#   → Enriches with Jira ticket data
#   → Generates AI-powered release notes
#   → Creates GitHub Release
#   → Posts to #releases in Slack

What You Get

A GitHub Release and Slack message that looks like this:

## Release v2.4.0 — March 13, 2026

This release introduces real-time collaboration, new export
formats, and several performance improvements.

✨ Features
- Real-time collaboration for shared dashboards (DASH-142)
- Export API now supports CSV and PDF formats (DASH-156)
- Webhook configuration UI with test-send (DASH-161)

🐛 Bug Fixes
- Fixed timezone rendering in scheduled reports (DASH-149)
- Resolved memory leak in WebSocket pool (DASH-155)

⚠️ Breaking Changes
- No breaking changes in this example release

Team Dashboard

The Cullit Dashboard (v1.8.0+) provides multi-provider login, persistent generation history, usage analytics, team/org management, release drafts, and project templates.

Authentication

The dashboard uses WorkOS AuthKit for authentication, supporting GitHub, GitLab, Google, email, and SSO/SAML. To enable it:

1. Create a WorkOS account at dashboard.workos.com
2. Add the redirect URI https://your-domain.com/auth/callback
3. Configure the API server environment variables:

WORKOS_CLIENT_ID=your_client_id
WORKOS_API_KEY=your_api_key
CULLIT_JWT_SECRET=your_32char_minimum_secret
CULLIT_BASE_URL=https://your-domain.com

Users sign in via the dashboard login button. Sessions are stored as HttpOnly JWT cookies (7-day expiry). Each user automatically receives a clt_* API key on first login.

Generation History

Every release note generation is recorded server-side. The history tab shows:

• Source range (from/to), provider, change count, and timestamp
• Paginated browsing with clickable entries to replay a generation
• Per-user history outside orgs and org-shared visibility inside teams

API: GET /v1/history?limit=20&offset=0 (requires authentication)

Usage Analytics

The analytics tab displays:

• Stats cards — total generations, total changes, average duration, this month’s count
• Daily chart — bar chart of generations over the last 30 days
• Provider breakdown — which AI providers are used most

API: GET /v1/analytics/usage?days=30 (requires authentication). Org-level stats are shared across team members.

Organizations

Create an organization to share analytics and manage seats:

• POST /v1/org — create an org (you become the owner)
• GET /v1/org — view your org and members
• POST /v1/org/invite — add a member directly by user id (owner/admin only)
• POST /v1/org/invites — create email invite (owner/admin only)
• GET /v1/org/invites — list pending invites
• DELETE /v1/org/invites/:id — revoke invite
• PATCH /v1/org/members/:userId — update member role (owner only)
• DELETE /v1/org/members — remove a member (owner/admin only)
• GET /v1/org/usage — org usage and seat snapshot

Organization workflows include branded changelog widgets, project templates, audit logs, team analytics, and collaboration tools in open-source mode.

Team API Key Management

Org owners and admins can manage team API keys from the dashboard:

• Label — name each key (e.g. "Frontend Dev", "CI Pipeline")
• Assign — associate a team member’s email and name with each key
• Send — email the key directly to the assigned team member
• Rotate — generate a new key value, instantly invalidating the old one
• Revoke — permanently disable a key

API endpoints for key management:

• GET /v1/org/keys — list all team API keys (admins see full keys, members see masked)
• PATCH /v1/org/keys/:id — update label or assignment
• POST /v1/org/keys/:id/send — email key to assigned recipient
• POST /v1/org/keys/:id/revoke — revoke a key
• POST /v1/org/keys/:id/rotate — rotate a key (returns new value)

Team members can use assigned keys for hosted API routes where authentication is enabled. Local CLI generation can run without this key.

Release Draft Workflow

Collaborative release drafting and approvals are available in the open-source dashboard workflow:

• POST /v1/drafts — create a draft from generated output
• GET /v1/drafts — list drafts with status filter and pagination
• GET /v1/drafts/:id — retrieve draft detail plus revisions
• PATCH /v1/drafts/:id — update draft content
• DELETE /v1/drafts/:id — delete non-published draft
• POST /v1/drafts/:id/submit, /approve, /publish — workflow transitions

Publishing a draft writes the approved result to hosted changelog entries.

Project Templates

Save project-level defaults for faster generation:

• GET /v1/projects/settings — list project defaults
• PUT /v1/projects/:project/settings — upsert defaults (source, provider, audience, tone, categories)

Cullit is MIT-licensed and open source. npm • Home