> ## Documentation Index
> Fetch the complete documentation index at: https://www.usenotra.com/docs/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

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

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

## How it works

<Steps>
  <Step title="Connect a source">
    Install the Notra GitHub app on the repositories you want to cover, and optionally connect Linear so issues show up as source material. See [GitHub](/docs/integrations/github) and [Linear](/docs/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 Notra generates one for you. See [Scheduled Automation](/docs/automation/scheduled) and [Event-Based Automation](/docs/automation/event-based).
  </Step>

  <Step title="Notra 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>

## Create 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 Notra 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, and Notra previews the releases, pull requests, commits and issues in the window. Deselect anything you do not want mentioned, and search by title, author or label to find items.
  </Step>

  <Step title="Identity">
    Choose which brand identity writes the post. Notra then generates the posts into a new collection and opens each one in the editor when it is ready.
  </Step>
</Steps>

## Changelog structure

Every generated changelog follows the same shape.

### Summary

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

### Highlights

Highlights lists up to five changes, chosen by importance in this order: security, breaking changes, major features, reliability fixes, performance. If there are fewer than five high-impact changes, the list is shorter, because the agent never pads it.

<Note>
  The agent excludes low-signal work such as small refactors, dependency bumps, wording tweaks and test-only changes from Highlights. It leaves that work 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, the agent files it 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 Notra 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, so for a GitHub release event, Notra compares the new release with the previous one and uses that range.
</Info>

## Tone

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

## Automation settings

Schedules and event triggers that produce changelogs accept these options, and 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={"system"}
{
  "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={"system"}
{
  "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**, and when it is on, Notra saves generated posts with the `published` status immediately instead of as drafts. Notra always saves social posts and images as drafts.

## Publishing

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

* **Framer**: the Notra plugin imports your posts into a Framer site. See [Framer](/docs/integrations/framer).
* **Manual**: copy the Markdown from the editor.

- **Your own site or CMS**: fetch posts from the API with `GET /v1/posts?status=published` and render them on your site. See [API Getting Started](/docs/api/getting-started).

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

## Edit 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 saves.

## Best practices

### Write clear PR titles and descriptions

Notra uses your PR titles and descriptions as source material, so descriptive PRs produce 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

* If you ship daily, use `yesterday` or `current_day`
* For weekly releases, use `last_7_days`
* For monthly updates, use `last_30_days`

### Review before publishing

Changelogs stay drafts until you publish them, so 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={"system"}
# 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

The lookback window may not cover the relevant timeframe, the activity may have been deselected in the Activity step or the PRs may lack detail. To fix it:

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

Every plan includes a monthly quota of long-form posts, and changelogs and blog posts count against it. When the quota is used up, Notra falls back to AI credits, and if none are available, Notra blocks the generation.

To fix it, check **Settings > Billing & Usage > Usage**, and top up credits under **Settings > Credits** or upgrade the plan. See [Billing & Plans](/docs/organization/billing).

### Changes from private repositories not appearing

The GitHub app is not installed on the repository, or the repository is disabled in the integration. To fix it:

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](/docs/concepts/brand-voice) to control how changelogs are written and which changes get emphasis.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.