> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kolaria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelogs

> Generate changelogs from GitHub and Linear activity, review them in the editor, and publish them to your site

Kolaria generates changelogs from your GitHub pull requests, commits, and releases, and optionally from Linear issues. Each changelog is created as a draft post that you review, refine with the content agent, and publish when ready.

Changelogs live in the Studio content pipeline. In the dashboard, switch the sidebar to **Studio** and open **Content**.

## How It Works

<Steps>
  <Step title="Connect a source">
    Install the Kolaria GitHub app on the repositories you want to cover. You can also connect Linear so issues show up as source material. See [GitHub](/integrations/github) and [Linear](/integrations/linear).
  </Step>

  <Step title="Create on demand or automate">
    Click **New post** on the Content page to generate a changelog right now, or set up a schedule or an event trigger so Kolaria generates one for you. See [Scheduled Automation](/automation/scheduled) and [Event-Based Automation](/automation/event-based).
  </Step>

  <Step title="Kolaria reads your activity">
    The changelog agent pulls the activity inside the lookback window, filters out work that is only relevant internally, and groups the rest by impact and category.
  </Step>

  <Step title="Review and publish">
    The changelog appears as a draft in a collection. Open it, edit it directly or ask the content agent for changes, then click **Publish**.
  </Step>
</Steps>

## Creating a Changelog Manually

<Steps>
  <Step title="Open the create dialog">
    Go to **Content** and click **New post**.
  </Step>

  <Step title="Formats">
    Pick **Changelog entry**. You can select several formats at once (for example a changelog plus a LinkedIn post) and Kolaria generates all of them from the same activity. Choose a lookback window and toggle which data points to include: **Pull Requests**, **Commits**, and **Releases**.
  </Step>

  <Step title="Activity">
    Pick the repositories and Linear integrations to draw from. Kolaria previews the releases, pull requests, commits, and issues in the window and lets you deselect anything you do not want mentioned. You can search by title, author, or label.
  </Step>

  <Step title="Identity">
    Choose which brand identity should write the post. The posts are generated into a new collection, and each post opens in the editor when it is ready.
  </Step>
</Steps>

## Changelog Structure

Every generated changelog follows the same shape.

### Summary

A single paragraph directly under the title. The agent targets 120 to 180 words and goes shorter when there is less to cover.

### Highlights

Up to five changes, chosen by importance in this order: security, breaking changes, major features, reliability fixes, performance. If there are fewer than five genuinely high-impact changes, the list is shorter. It is never padded.

<Note>
  Low-signal work such as small refactors, dependency bumps, wording tweaks, and test-only changes is excluded from Highlights, and is left out of the changelog entirely unless it has a clear effect on your audience.
</Note>

### More Updates

Every remaining change appears exactly once as a bullet under one of these categories:

* **Security**
* **Features & Enhancements**
* **Bug Fixes**
* **Performance Improvements**
* **Infrastructure**
* **Internal Changes**
* **Testing**
* **Documentation**

When a change fits several categories, it is filed under the first match in this order: Security, Bug Fixes, Features & Enhancements, Performance Improvements, Infrastructure, Internal Changes, Testing, Documentation.

## Lookback Windows

The lookback window controls how far back Kolaria looks for activity when it generates a changelog on demand or on a schedule.

| Window | Description | Best For |
| - | - | - |
| `current_day` | Today's changes only | Real-time daily updates |
| `yesterday` | Previous day's activity | Morning recaps |
| `last_7_days` | Past week (default) | Weekly team updates |
| `last_14_days` | Past two weeks | Bi-weekly releases |
| `last_30_days` | Past month | Monthly summaries |

<Info>
  Event triggers do not use a lookback window. For a GitHub release event, Kolaria compares the new release with the previous one and uses that range.
</Info>

## Tone

The changelog is written in the tone profile of the brand identity you pick: **Conversational**, **Professional**, **Casual**, or **Formal**. Set it under **Studio > Brand Identity**, together with your target audience and custom instructions. See [Brand Voice](/concepts/brand-voice).

## Automation Settings

Schedules and event triggers that produce changelogs accept these options. The same fields are available in the dashboard and in the public API (`POST /v1/schedules` and `POST /v1/event-triggers`).

**Scheduled generation**

```json theme={null}
{
  "name": "Weekly changelog",
  "sourceType": "cron",
  "sourceConfig": {
    "cron": { "frequency": "weekly", "hour": 9, "minute": 0, "dayOfWeek": 1 }
  },
  "targets": { "repositoryIds": ["repo_123"] },
  "outputType": "changelog",
  "outputConfig": { "brandVoiceId": "bv_123" },
  "lookbackWindow": "last_7_days",
  "enabled": true,
  "autoPublish": false
}
```

`frequency` is `daily`, `weekly` (requires `dayOfWeek`, 0 to 6), or `monthly` (requires `dayOfMonth`, 1 to 31). `hour` is 0 to 23 and `minute` is 0 to 59.

**Event-based generation**

```json theme={null}
{
  "sourceType": "github_webhook",
  "sourceConfig": { "eventTypes": ["release"], "includePreReleases": true },
  "targets": { "repositoryIds": ["repo_123"] },
  "outputType": "changelog",
  "outputConfig": { "brandVoiceId": "bv_123" },
  "enabled": true,
  "autoPublish": false
}
```

`eventTypes` accepts `release` and `push`.

### Auto-publish

Changelogs and blog posts support **Auto-publish**. When it is on, generated posts are saved with the `published` status immediately instead of as drafts. Social posts and images are always saved as drafts.

## Publishing

Clicking **Publish** in the editor (or enabling auto-publish) sets the post status to `published`. It does not push the post anywhere by itself. Published posts are what your publishing destinations pick up:

* **Framer**: the Kolaria plugin imports your posts into a Framer site. See [Framer](/integrations/framer).
* **Your own site or CMS**: fetch posts from the API with `GET /v1/posts?status=published` and render them however you like. See [API Getting Started](/api/getting-started).
* **Manual**: copy the Markdown from the editor.

**Move to draft** takes a published post back to `draft`.

## Editing with the Content Agent

Every post has a content agent in the right-hand panel. Select text in the editor to give the agent context, then ask for changes such as:

* "Expand the summary to mention the pricing change"
* "Simplify the Highlights for a non-technical audience"
* "Move the caching change into Performance Improvements"

The agent edits the post in place and you can review the diff before it is saved.

## Best Practices

### Write Meaningful PR Titles and Descriptions

Kolaria uses your PR titles and descriptions as source material. Clear, descriptive PRs lead to better changelogs.

**Good PR Title**\
`Add email verification flow with expiration handling`

**Poor PR Title**\
`Fix bug`

### Match the Lookback Window to Your Release Cadence

* Ship daily? Use `yesterday` or `current_day`
* Weekly releases? Use `last_7_days`
* Monthly updates? Use `last_30_days`

### Review Before Publishing

Changelogs are drafts until you publish them. Use the review to:

* Verify technical accuracy
* Add context that GitHub activity does not capture
* Adjust the Highlights for your audience

## Example Changelog

```markdown theme={null}
# Product Updates - Week of March 2, 2026

This week brought significant improvements to developer experience and
reliability. We shipped enhanced error handling for cached components,
improved email verification flows, and optimized authentication state
management. The team also focused on security hardening with rotated
webhook secret handling and cross-browser UI consistency improvements.

## Highlights

### Cache component support with actionable error guidance
Runtime guardrails now catch unsupported auth calls in cached contexts
and provide clear migration guidance with the correct usage pattern.

### Email link verification for signup flows
Signup verification now supports secure email-link completion flows
with clear status handling for expiration and mismatch cases.

## More Updates

### Security
- **Rotated webhook signing secret handling** [#131](https://github.com/org/repo/pull/131) -
  Improves secret lifecycle controls. (Author: [@lee](https://github.com/lee/))

### Bug Fixes
- **Fixed null-state crash in trigger editor** [#140](https://github.com/org/repo/pull/140) -
  Prevents editor crashes for partially configured triggers. (Author: [@sam](https://github.com/sam/))

### Features & Enhancements
- **Added repository filter presets** [#142](https://github.com/org/repo/pull/142) -
  Speeds up common workflow setup. (Author: [@alex](https://github.com/alex/))
```

## Common Issues

### Changelog Is Too Short or Missing Expected Changes

**Cause**: The lookback window does not cover the relevant timeframe, the activity was deselected in the Activity step, or the PRs lack detail.

**Solution**:

1. Check the lookback window against when the work was merged
2. Make sure the PRs, commits, or releases were selected in the Activity step
3. Add descriptive titles and descriptions to your PRs

### Nothing Was Generated

**Cause**: Every plan includes a monthly quota of long-form posts (changelogs and blog posts count against it). When the quota is used up, Kolaria falls back to AI credits, and if none are available the generation is blocked.

**Solution**: Check **Settings > Billing & Usage > Usage**, and top up credits under **Settings > Credits** or upgrade the plan. See [Billing & Plans](/organization/billing).

### Changes from Private Repositories Not Appearing

**Cause**: The GitHub app is not installed on the repository, or the repository is disabled in the integration.

**Solution**:

1. Navigate to **Integrations > GitHub**
2. Add the repository, or enable it if it is already listed
3. Re-run the generation

<Tip>
  See [Brand Voice](/concepts/brand-voice) to control how changelogs are written and which changes get emphasised.
</Tip>