A GitHub release can start a job that hands its notes to a coding agent, lets the agent edit a video project and renders the result with one coa render command. The step that makes this safe to run unattended is a gate. The agent must write a verdict.json, and a script renders nothing unless the verdict says render, lists no open questions, matches the release and points to real clips and real lines from the notes.
The limit comes first. The gate checks references, not meaning, and the agent can show only what a recording already covers. Someone still supplies approved clips and reviews the MP4 before it goes anywhere.
The example is a fictional CLI called deploykit, release 3.8, with a workflow you can adapt. Most of the post covers the part pipelines usually skip, which is deciding when the job should refuse to render.
The pipeline at a glance
One picture covers the whole flow, and the branch after the gate matters most.
Two steps need judgment, the agent edit and the final review. Everything between them is mechanical.
Why the video has to be files first
A pipeline can only gate what it can read.
CoAnimator stores a video as project files that a coding agent such as Claude Code or Codex edits, while the studio reloads its stage so a person can watch or step in. coa render turns a project folder into an MP4 without opening the app. It exits 0 on success and 1 on failure, and it checks dimensions, frame count, duration and audio before replacing an output file. The coa CLI reference covers install and flags.
Encoded files can differ across engines, hardware and platforms. Review project files in pull requests and do not compare MP4 bytes.
That settles the renderer. The agent's inputs come next.
What goes into the run folder
Every run starts from a fresh folder, so a retry never edits the result of an earlier release.
run/
notes.md release notes from GitHub
brief.md standing rules, plus version and release URL
clips/ approved recordings of the released build
project/ copy of the reviewed baseline project
verdict.json written by the agent
out/ MP4 and contact sheet
- Notes: The GitHub release body, which should describe one release. A guard step rejects empty notes, an Unreleased heading and more than one version heading, so a pasted changelog fails early.
-
Clips: The only source of product visuals. A clip counts as approved when it is committed to the repository's
clips/folder through review. Terminal output and UI states must match the released build, so nothing here is generated. They are large binaries, so keep them in Git LFS or fetch them in an earlier step. The workflow below assumes they are already in the checkout. - Baseline: The first episode, built by hand once, so typography, pacing and sound are already settled.
The guard is a few lines of shell:
#!/usr/bin/env sh
# usage: check-notes.sh <notes.md>
set -eu
notes=$1
[ -s "$notes" ] || { echo "Release notes are empty" >&2; exit 1; }
if grep -qiE '^#{1,6}[[:space:]]+.*unreleased' "$notes"; then
echo "Notes contain an Unreleased heading" >&2; exit 1
fi
count=$(grep -cE '^#{1,6}[[:space:]]+\[?v?[0-9]+\.[0-9]+' "$notes" || true)
if [ "$count" -gt 1 ]; then
echo "Notes contain $count version headings, expected one release" >&2; exit 1
fi
It is a heading heuristic and assumes curated notes. The agent edits the project copy and never the baseline, and what it writes back needs a fixed shape.
The verdict file
A chat reply cannot gate a job, but a file with a fixed shape can.
{
"status": "render",
"release": "3.8",
"picked": [
{ "source_line": "Add --dry-run to push", "clip": "clips/push-dry-run.mp4" },
{ "source_line": "logs --follow reconnects after a dropped connection", "clip": "clips/logs-follow.mp4" },
{ "source_line": "Name the searched paths when deploykit.toml is missing", "clip": "clips/missing-config.mp4" }
],
"held_back": [
{ "note": "Bump TLS library", "why": "No visible behavior, stays in the written notes" },
{ "note": "Refactor config loader", "why": "Internal change" }
],
"open_questions": []
}
-
render: The agent claims every pick has a clip and no question is open. -
needs_clips: A pick has no approved recording, and the missing filenames go inopen_questions. -
skip: Nothing in the release is worth showing, andheld_backrecords why.
The held_back list keeps every omission explainable in review. Each pick carries a copied line from the notes and a clip path, which gives a script something to verify.
What the gate checks
The agent writes the verdict, and a separate script decides whether to believe it.
#!/usr/bin/env sh
# usage: check-verdict.sh <run-dir> <release-tag>
set -eu
dir=$1
tag=$2
verdict="$dir/verdict.json"
# 1. Shape: status, open questions, one to three picks, each with a source line and a clip path
jq -e '
.status == "render"
and (.open_questions | length == 0)
and (.picked | type == "array" and length >= 1 and length <= 3)
and all(.picked[]; (.source_line | type == "string" and length > 0)
and (.clip | type == "string" and length > 0))
' "$verdict" > /dev/null || { echo "Verdict failed the status, question or pick checks" >&2; exit 1; }
# 2. The verdict must be about the release that triggered the run
[ "$(jq -r '.release' "$verdict")" = "${tag#v}" ] || { echo "Verdict release does not match tag $tag" >&2; exit 1; }
# 3. Every pick points to an existing approved clip and quotes a real line from the notes
jq -r '.picked[] | [.clip, .source_line] | @tsv' "$verdict" |
while IFS="$(printf '\t')" read -r clip line; do
case "$clip" in
clips/*..*|../*) echo "Rejected clip path: $clip" >&2; exit 1 ;;
clips/*) ;;
*) echo "Clip is outside clips/: $clip" >&2; exit 1 ;;
esac
[ -f "$dir/$clip" ] || { echo "Missing clip: $clip" >&2; exit 1; }
grep -qF -- "$line" "$dir/notes.md" || { echo "Line not found in notes.md: $line" >&2; exit 1; }
done
A missing or malformed file fails the script, and so does any pick that points outside clips/. The script checks references, not meaning. It cannot tell whether a clip really shows the change it is attached to, so that check stays with the reviewer. It also depends on the agent following the brief.
The standing brief
The brief stays the same every release, and the job appends the version and release URL.
- Work only inside
project/and never touch the baseline. - Use only files from
clips/, with no new media and no invented screens, output or figures. - Pick at most three changes. For each, copy the exact line from
notes.mdintosource_lineand name a clip. - Keep command names, flags and interface labels exactly as recorded.
- Keep rollout limits beside the feature they apply to.
- Never present an Unreleased item as shipped.
- Write
verdict.jsonand stop, because rendering belongs to the job.
Release notes are free text that contributors can edit, and the agent reads them, so I treat them as untrusted input. The agent is narrowed in three ways:
-
Tools:
--toolslimits which built-in tools exist. The list is file tools plusSkill, so the agent can load CoAnimator's project guidance. -
Approvals:
--allowedToolspre-approves only what the job needs, which is reads,Skill, edits underproject/and writes toverdict.json. AnEdit(...)rule also coversWrite, which is whyWritehas no rule of its own.--permission-mode dontAskdenies everything else. -
Paths: A settings override turns on
blockReadsOutsideWorkingDirectoriesandblockWritesOutsideWorkingDirectories, so the file tools refuse paths outside the run folder in any permission mode.
These are permission rules inside Claude Code, not an operating-system sandbox. Use a runner that holds no other secrets, and treat the uploaded artifact as readable by anyone with access to the repository. The flags and both settings exist in Claude Code 2.1.328. Pin the version on the runner and confirm that your version has them.
The first episode is worth building interactively with an approval step. The changelog video guide walks through that cut, and the rules above apply once the format is approved. The workflow below wires these pieces together.
The workflow
The workflow builds the folder, runs the agent, runs the gate and renders only when the gate passes.
name: changelog-video
on:
release:
types: [published]
workflow_dispatch:
inputs:
tag:
description: Release tag to replay
required: true
jobs:
episode:
runs-on: [self-hosted, linux]
env:
TAG: ${{ github.event.release.tag_name || inputs.tag }}
GH_TOKEN: ${{ github.token }}
steps:
- uses: actions/checkout@v4
- name: Build the run folder
run: |
echo "SAFE_TAG=$(printf %s "$TAG" | tr / -)" >> "$GITHUB_ENV"
rm -rf run
mkdir -p run/out
cp -r baseline/project run/project
cp -r clips run/clips
cp brief.md run/brief.md
gh release view "$TAG" --json body --jq .body > run/notes.md
sh scripts/check-notes.sh run/notes.md
printf '\nVersion: %s\nFull notes: %s\n' "$TAG" "$(gh release view "$TAG" --json url --jq .url)" >> run/brief.md
- name: Let the agent edit the project
working-directory: run
run: |
claude -p "Follow brief.md. Read notes.md, use only clips/, edit only project/, and write verdict.json. Do not render." \
--tools "Read,Edit,Write,Glob,Grep,Skill" \
--allowedTools "Read" "Glob" "Grep" "Skill" "Edit(/project/**)" "Edit(/verdict.json)" \
--settings '{"permissions":{"blockReadsOutsideWorkingDirectories":true,"blockWritesOutsideWorkingDirectories":true}}' \
--permission-mode dontAsk
- name: Check the verdict
id: gate
run: |
if sh scripts/check-verdict.sh run "$TAG"; then
echo "go=true" >> "$GITHUB_OUTPUT"
else
echo "go=false" >> "$GITHUB_OUTPUT"
fi
- name: Render and build the contact sheet
if: steps.gate.outputs.go == 'true'
working-directory: run
run: |
xvfb-run -a coa render ./project --out ./out/changelog.mp4
sh ../scripts/contact-sheet.sh out/changelog.mp4 out/contact-sheet.png
- name: Keep the review package
if: always()
uses: actions/upload-artifact@v4
with:
name: changelog-video-${{ env.SAFE_TAG }}-attempt-${{ github.run_attempt }}
path: |
run/verdict.json
run/out/
if-no-files-found: warn
-
Replay:
workflow_dispatchtakes a tag, so a past release can be re-run without publishing a new one. It is also the safest way to test the workflow. -
Release text: The notes land in a file through
gh release view. They are never interpolated into a shell command, and the tag travels throughenv. - Runner: Self-hosted, because CoAnimator, the CoAnimator agent skill, FFmpeg, jq, the GitHub CLI and the agent login all have to exist on the machine. There is no hosted render service to submit jobs to.
-
Display: Headless Linux still needs a display server for Electron, so the render runs under
xvfb-run -a. - Licence: The CLI uses the licence cached by the desktop app, so open the app once on the runner to activate it.
A passing render only proves that a file exists, so the review package matters more than the exit code.
The review package
The job uploads the verdict, the MP4 and a contact sheet, and a person decides what ships.
The contact sheet samples twelve frames evenly across the video and tiles them into one image, so a reviewer sees the whole arc before pressing play.
#!/usr/bin/env sh
# usage: contact-sheet.sh <video.mp4> <out.png>
set -eu
dur=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$1")
rate=$(awk -v d="$dur" 'BEGIN { printf "%.6f", 12 / d }')
ffmpeg -y -loglevel error -i "$1" -vf "fps=$rate,scale=480:-1,tile=4x3" -frames:v 1 "$2"
When a frame looks wrong, the same project opens in the studio for a manual fix instead of another agent run.
Three checks stay with the reviewer:
- Truth: Every picked change appears in the MP4 exactly as its clip shows it, under the right version label.
- Access: Rollout limits sit beside the feature and not only on the closing card.
- Privacy: No tokens, account details or private paths appear in a terminal recording.
Runs that never reach the review package need their own handling.
Runs that fail
Know exactly what survives a failure.
- Agent step fails: A non-zero exit stops the job, no render runs, and the review step uploads the verdict only if one was written.
- Gate fails: No render runs. The artifact holds the verdict, and the job log names the reason.
-
Render exits 1: The job fails and that run has no MP4. Each run builds a fresh
out/folder, so there is no earlier file to protect. - What is never touched: The job does not publish anything. A video you already published and the artifacts of earlier runs stay as they are.
- Re-runs: Each attempt uploads a package named by tag and attempt number, so a re-run adds a package and replaces nothing. Artifacts expire on the repository's retention schedule, 90 days by default.
-
Notes edited after publishing: The trigger fires only on
published, so the video reflects the notes at that moment. Replay the tag to refresh it.
What remains are limits that no pipeline setting fixes.
Where this falls short
- Agent dependence: Output quality depends on the connected agent, the prompt and how much direction it gets. The gate catches missing and mismatched inputs and not weak pacing.
- Clips: Someone still records the released build for each change. Automating the edit does not automate the recording.
- Analytics: CoAnimator has no built-in analytics, so tracking who watched or who tried the feature has to be built separately.
- Fit: If the video has to live inside a React codebase as a component, Remotion is built for that and fits better.
- Cost: CoAnimator is free forever with a one-time lifetime license, and agent usage is billed by its provider.
Beyond the first episode
Once the verdict file exists, it can carry more than a go or no-go. Add a rollout field and the availability line comes from data instead of memory. Feed the same notes and clips into a second project with a portrait layout, which needs its own composition and not a crop. Check first use of each featured change a week after release, and keep showing the kinds of changes people actually tried.
Before trusting a live release event, record one clip of your latest change, build a baseline episode by hand and replay that tag through the workflow. The coa CLI reference covers install and render flags, and the scheduled changelog setup shows the same idea on a cron job.

Top comments (2)
Good call making the gate check references rather than trusting the agent's output. Do you have a plan for when a release note mentions a feature that has no approved clip yet, skip that line or fail the whole run?
If the feature is selected for the video but has no approved clip, the verdict becomes
needs_clipsand rendering stops. If it's not selected, it goes intoheld_backwith a reason, and the other changes can proceed. That way, nothing gets shown without supporting footage.