DEV Community

Cover image for Automate Changelog Videos with GitHub Actions and AI
Harsheen
Harsheen

Posted on

Automate Changelog Videos with GitHub Actions and AI

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.

Flow diagram of the pipeline. A published release creates a run folder, an agent edits the project, and a gate script checks the verdict against the release, the clips and the notes. The statuses needs_clips and skip stop the job, while render produces an MP4 and a 12-frame contact sheet for a person to review.

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
Enter fullscreen mode Exit fullscreen mode
  • 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
Enter fullscreen mode Exit fullscreen mode

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": []
}
Enter fullscreen mode Exit fullscreen mode
  • 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 in open_questions.
  • skip: Nothing in the release is worth showing, and held_back records 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
Enter fullscreen mode Exit fullscreen mode

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.md into source_line and 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.json and 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: --tools limits which built-in tools exist. The list is file tools plus Skill, so the agent can load CoAnimator's project guidance.
  • Approvals: --allowedTools pre-approves only what the job needs, which is reads, Skill, edits under project/ and writes to verdict.json. An Edit(...) rule also covers Write, which is why Write has no rule of its own. --permission-mode dontAsk denies everything else.
  • Paths: A settings override turns on blockReadsOutsideWorkingDirectories and blockWritesOutsideWorkingDirectories, 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
Enter fullscreen mode Exit fullscreen mode
  • Replay: workflow_dispatch takes 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 through env.
  • 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"
Enter fullscreen mode Exit fullscreen mode

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)

Collapse
 
useaifix profile image
AIFix •

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?

Collapse
 
sheen_417f0f3a7f4 profile image
Harsheen •

If the feature is selected for the video but has no approved clip, the verdict becomes needs_clips and rendering stops. If it's not selected, it goes into held_back with a reason, and the other changes can proceed. That way, nothing gets shown without supporting footage.