A changelog video belongs on the same checklist as the tag, the notes and the binaries. Check out the release on disk, brief the one change users will notice, review the script, export what you need, then attach the wide cut to the GitHub release before you share anywhere else. Ship it with the tag, not as a follow-up.
Key takeaways
- Put the video on the release checklist so it ships with the tag.
- One change per video. A tour of every bullet loses people fast.
- Build from the checked-out tag on your machine, not from a release URL alone.
- Attach the 16:9 file to the release or changelog page. Save vertical cuts for social.
- Keep a human on the script. Auto-start on every tag is not worth the risk.
Contents
- Why does a changelog video belong on the release checklist?
- What steps should the checklist include?
- How do you build the video from the tagged code?
- Where does each export format go?
- What should stay manual?
- FAQ
Why does a changelog video belong on the release checklist?
The tag is the moment you already decided what changed. The notes are open and someone is about to publish. That is the cheapest time to show the change on screen.
A video written days later usually drifts: a different highlight, a moved UI on main, or a task that never gets scheduled. Attaching the file to the release makes the gap visible. If the asset is missing, the checklist is not done.
Text notes still matter. The clip answers what people ask after they skim the bullets: what does this look like when I click it?
What steps should the checklist include?
Keep it short enough for release day.
| Checklist step | Done when | Owner |
|---|---|---|
| Tag is on disk | Fetch and checkout of the release tag succeed | Release cutter |
| One-line brief written | One sentence names the user-visible change | Release owner or PM |
| Script reviewed | First line states what changed; internals cut | Same person |
| Preview watched once | No wrong screen or leftover sample copy | Same person |
| Wide file attached | Release or changelog page links the MP4 | Release owner |
Name an owner for each step. Unowned steps skip the first busy week.
How do you build the video from the tagged code?
Check out the tag first
A local build-from-code workflow needs the release folder on your machine, not main from this morning.
git fetch origin
git checkout v2.4.0
Point the workspace at that folder. If the tool cannot take a GitHub URL, that is expected: "from a release" means "from this tag on disk."
Brief one change
Write one sentence for the change a customer will notice, for example "Show the new bulk export on the Reports page." Paste only the matching notes. Ten bullets in one video become a slideshow nobody finishes.
More on short release clips: why release notes work better as videos. The DemoVexa walkthrough: how to turn a GitHub release into a changelog video.
Review, export, attach
Read the script as a customer. Cut migrations, flags and internal names. The first line should say what is new. Render the wide cut first, with SRT or VTT if needed. Add vertical versions only for feeds.
Prefer the terminal? The product demo video CLI covers install and start. Someone still approves the script.
Where does each export format go?
- 16:9 MP4: GitHub release assets, changelog page, docs, YouTube.
- 9:16 MP4: Shorts, Reels, stories. One moment from the same change.
- 1:1 MP4: Feed posts that crop awkward widescreen frames.
- SRT / VTT: Upload wherever the platform indexes captions.
Readers on a laptop want the wide cut, not a vertical file in the notes.
What should stay manual?
Script approval. A changelog video goes to customers. Auto-start on every tag sounds neat until a half-finished feature name ships in the voiceover.
Rendering can wait overnight. A human still opens the preview, fixes one line if needed, and publishes.
DemoVexa builds the script and screens from the local code folder, then exports those formats with captions. See the features page. There is no GitHub Action that starts a video on publish today, and I would still want a person on the script even if there were.
FAQ
Can I point the tool at a GitHub release URL?
Only if it supports that. DemoVexa does not. Clone, check out the tag, and point a workspace at that folder.
How long should the changelog video be?
Long enough to show one change and why it matters. Most fit in about 30 to 60 seconds.
Do I need to record my own voice?
No. Use an AI voice on your own key, record yourself, or ship captions only.
Should every release get a video?
Only when there is a user-visible change worth showing. Skip dependency bumps and internal refactors.
Where should I link the video in the release body?
Near the top, next to the headline change.
Can the same project cover social cuts later?
Yes. Export 9:16 or 1:1 from the approved project later, instead of rebuilding from another commit.
Baltej Singh is the founder of DemoVexa, a desktop app and CLI that turns a local codebase into narrated product demo videos. He writes from Delaware, USA.
Top comments (10)
One practical addition: record against seeded demo data on the checked-out tag, so the clip doesn't show someone's real workspace and can be regenerated identically if the script changes. Burned-in captions also help, since most people watch release videos muted. And if you want the clip to play inline, drag the MP4 into the release notes body rather than only attaching it as a release asset, because assets just show up as a download link.
Good additions, all three. Seeded data on the checked-out tag is the one I'd push hardest, because it also keeps the clip matched to the code in that release instead of whatever is on main by the time someone records. Captions make sense for release videos in particular, since most people skim them in a feed with the sound off. And the inline MP4 tip is a good catch, an attached asset is easy to miss when it only shows up as a download link. Do you script the seed data per release, or keep one fixed demo workspace and only touch it when the UI changes?
I keep one fixed demo workspace and only touch it when the UI moves. The seed script runs against that workspace on the release tag, so the clip stays tied to what shipped without inventing a new dataset every time. When a feature needs fresh sample content, I add it to the seed rather than recording off a dirty local DB. The important bit is still "checked-out tag + seed", not whether the fixture is one file or many.
That split makes sense. The workspace stays stable and the seed is the only thing that grows with features, so anyone on the team can rebuild the same clip later without needing your local database. One thing I'd wonder about is older releases: if you regenerate a clip for an old tag, does today's seed still run against it, or do you pin the seed version to the tag as well?
Yes — I pin the seed to the tag, same as the app. The seed lives in the same repo, so checking out v1.2 gives me the v1.2 seed and the v1.2 UI, and today's seed only comes in when we cut a new release. If a later seed change would break an old workspace, regenerating that old clip is "check out the tag, run the seed that shipped with it," not "run main's seed against an old checkout." The release video is a CI artifact of that tag, so we don't have to remember the ritual six months later.
That's the cleanest version of it. Once the clip is a CI artifact of the tag, nobody has to remember how it was made, because the tag already carries the app, the seed and the recipe. It also answers the old release question completely: an old clip is just an old checkout plus the seed that shipped with it. Does the CI job block the release if the clip fails to render, or does it only warn and let the release go out?
Yes — I treat a failed render as a failed release if the clip is part of what that tag is supposed to ship. A tag that goes out without the video is annoying to rebuild later, and a warning everyone clicks past usually means the next person finds out on the release page. I keep the render step required in the release workflow, store the log and any partial output, and only allow a documented manual override for obvious infra flakes, so a renderer outage doesn't block a security patch. The retry still runs against the same tag, not against main.
That's a sensible line to draw. Required by default, with a documented override for infra flakes, keeps the video part of the release without letting a renderer outage hold up a security patch. Keeping the log and partial output is a good touch too, so whoever picks it up can see where it broke instead of rerunning blind. It's close to how I think about it with DemoVexa: if the demo is generated from the repo, it should rebuild from the tag like any other build output. What are you rendering with in that job, something headless like Remotion or a scripted screen capture?
It's a scripted screen capture of the seeded demo workspace, not Remotion. I want the pixels to come from the actual app at that tag, so a designed motion piece wouldn't catch a UI regression the changelog is supposed to show. Remotion would be the right tool if the video were an animation rather than a walkthrough of the shipped UI. The capture script pins the window size, theme and locale so a runner with a different default resolution doesn't change the frame, and it only starts recording after the seed has finished and the UI is idle, otherwise you get a spinner in the release video. ffmpeg writes the MP4 in the same job, and the artifact is uploaded with the tag.
Pinning window size, theme and locale is the part most people skip, and then they wonder why the CI frame looks different from their laptop. Waiting for the seed to finish and the UI to go idle is a good rule too, since a spinner in a release video is a very specific kind of embarrassing. Real pixels from the tag make sense when the point is catching regressions. How do you decide the UI is idle: a fixed quiet window on the network, or a ready signal the app sets itself?