Managing the changelog from GitHub

You can keep a changelog's entries in a GitHub repository, one Markdown file per entry. Merging to the connected branch publishes, deleting a file unpublishes, and, if you choose, changes made in the EvoHub console go back to the repository as pull requests. It works the same way as GitHub sync for Docs.

#The repository layout

EvoHub reads one folder of one branch, changelog/ unless you choose another (or the repository root). Every Markdown file in it is one entry:

changelog/
├── 2026-10-10-faster-search.md
├── 2026-10-02-dark-mode.md
├── 2026/                       subfolders are fine
│   └── 2026-01-15-sso.md
├── images/
│   └── search.png              linked from entries by relative path
├── _drafts/
│   └── ideas.md                skipped: the name starts with _
└── README.md                   skipped

• Every .md or .markdown file in the folder or its subfolders is an entry.
• Skipped: README.md, index.md, and any file or folder whose name starts with _ or .. Use a _drafts/ folder for notes that are not entries yet.
• A file's address (slug) is its slug in the front matter, else its file name without the extension and without a leading date: 2026-10-10-faster-search.md is /faster-search. Slugs are unique within a changelog.

#Front matter

A YAML block between two --- lines at the top of the file, then the body in Markdown:

---
title: Faster search
date: 2026-10-10
categories: [Improved]
tags: [search, performance]
version: 2.4.0
cover: ./images/search.png
author: Ada Lovelace
summary: Search answers in half the time.
pinned: false
draft: false
notify: false
slug: faster-search
---

Search now answers in half the time. ![Results](./images/search.png)

Unknown keys are ignored and listed as warnings. Quote values that contain a colon: title: "Search: twice as fast".

#Images

Link images relative to the file (./images/search.png, ../shared/logo.svg) or from the repository root (/assets/logo.png). A sync uploads them to the changelog's files — PNG, JPEG, WebP, GIF or SVG, up to 5 MB each, the same checks as an upload in the editor — and the entry points at the uploaded copy. Images already on the web (https://…) are left as they are.

#One branch per changelog

Each changelog follows one branch. Keep the same changelog/ folder on each branch and give each environment its own changelog:

Work on a branch from dev, merge to dev to see the entry on the development changelog, then merge dev into main to publish it in production — the same flow as code.

#Connect a repository

You need permission to manage changelogs (changelog:site:write), you must be signed in as a person, and you need to be able to install a GitHub app on the repository.

The GitHub tab then shows the repository, branch and folder, the result of the last sync (how many entries were created, updated, published, scheduled, sent to review or unpublished) and the last push, and any errors or warnings for individual files, with the line they are on. Sync now reads every file again.

#What a sync does

A sync runs after every push to the connected branch, usually within a minute.

• A new or changed file updates its entry's draft and publishes it. A future date schedules it instead, and draft: true keeps it off the changelog.
• A deleted file unpublishes its entry. The entry stays in EvoHub (delete it there if you want it gone) and is no longer tied to a file.
• A renamed or moved file keeps its entry, as long as its slug stays the same.
• A file with an error (no title, a date that is not a date, more than five categories) is skipped and listed with its line number; the rest of the changelog still syncs.
• If the folder is empty or missing, nothing is unpublished: the sync stops with an error instead.
• If a file's slug is already used by another entry, the entry gets the next free one (faster-search-2) and the sync lists a warning.
• In the console, GitHub is shown as whoever created or last changed an entry through a sync.

#With review turned on

If the changelog requires review (see Writing entries), a sync never publishes or schedules. New and changed entries go to In review, and a reviewer publishes them in EvoHub as usual. Merging to the branch is then "ready for review", not "live".

#Editing in EvoHub

You can still edit entries in the console. What happens next depends on Open a pull request with changes made in EvoHub:

• Off: console edits stay in EvoHub. The next time the file changes on GitHub, you are asked which version to keep (see Conflicts).
• On: publishing, unpublishing and deleting in EvoHub — and scheduled entries going live — write back to the repository. Commits go to a branch named evohub/changelog-<changelog address> and a pull request titled "Changelog edits from EvoHub" is opened; later changes join the same pull request while it is open. A new entry gets a file named <folder>/<date>-<slug>.md, an unpublished entry is written with draft: true, and a deleted entry's file is deleted. Your connected branch and the repository's default branch are never written to directly. When you merge the pull request, the next sync recognises the files as its own and changes nothing.

#Conflicts

If the same entry changed both in EvoHub and in its file on GitHub since they last matched — or its file was deleted after it was edited in EvoHub — nothing is overwritten. The entry is flagged in the editor and listed in the GitHub tab. For each one choose:

• Keep EvoHub's: the entry stays as it is in EvoHub. With pull requests on, the next push replaces the file.
• Keep GitHub's: the file replaces the entry's draft on the next sync (and publishes it, unless the changelog requires review). Your EvoHub edits to it are lost.

Resolving a conflict needs permission to publish entries.

#Disconnect

Disconnect in the GitHub tab removes the link between entries and files. The entries stay as they are. If the app is uninstalled or loses access to the repository on GitHub, the connection shows as disconnected and Reconnect picks up where it left off.

#Related

• Writing entries
• Reaching readers
• Changelog settings
• GitHub sync for Docs