Diffvideo/Docs

Rules Engine

The rules engine is how you control Diffvideo's automation. Rules define what triggers video generation, what type of video is created, and whether it's suggested for review or generated autonomously.

Anatomy of a rule

Every rule has three components:

  • Trigger — What event starts the rule (PR merge, release, push, schedule, or comment mention)
  • Action — What happens when the trigger fires (suggest a video or auto-generate)
  • Configuration — Additional settings like video type, target repository, and filter conditions

Trigger types

PR merged

Fires when a pull request is merged into the target branch. This is the most common trigger type. You can filter by:

  • Target branch (e.g., only PRs merged to main)
  • Source branch pattern (e.g., feature/*)
  • PR labels
  • File path patterns (e.g., only when src/api/** changes)

Push

Fires when commits are pushed to a specified branch. Useful for teams practicing trunk-based development where PRs aren't always used. You can filter by branch name and file paths.

Release

Fires when a new release is published on GitHub. Diffvideo summarizes what shipped since the previous release. You can filter by release tag patterns (e.g., v* for semantic versioning).

Schedule

Fires on a recurring schedule you define — daily, weekly, bi-weekly, or custom. Scheduled rules aggregate all changes within the time window into a single summary video. The schedule configuration specifies:

  • Frequency (daily, weekly, bi-weekly, monthly, or custom cron)
  • Which repositories to include
  • What time of day to generate
Scheduled rules are ideal for sprint recaps and engineering updates. See Sprint Recap Videos for a detailed walkthrough.

Comment mention

Fires when a comment on a PR or issue mentions Diffvideo. This allows team members to request a video on-demand by commenting on specific PRs or issues.

Action types

Suggest video

Diffvideo creates a video suggestion in your Inbox. You review the draft, optionally edit it, and approve or reject the suggestion. Only approved suggestions are rendered into videos.

This is the default action and is recommended when you want human oversight over every generated video.

Auto-generate

Diffvideo generates the video immediately. No manual review step. The finished video appears directly in your Videos library.

Use autonomous mode when you trust automated output for a specific trigger (e.g., release-triggered changelog videos) and want fully hands-off operation.

Creating a rule

  1. Navigate to Settings → Rules in your dashboard.
  2. Click Create rule.
  3. Name the rule (e.g., "Release changelog videos").
  4. Select the trigger type and configure its filters.
  5. Choose the action type (suggest or auto-generate).
  6. Select the video type (changelog, product update, feature demo, or helpdesk).
  7. Optionally scope the rule to a specific repository or apply it organization-wide.
  8. Save the rule. It takes effect immediately.

Rule priority

When multiple rules match an event, Diffvideo uses priority to determine which rule takes precedence. Higher-priority rules are evaluated first. If a higher-priority rule matches, lower-priority rules are skipped.

You can reorder rules by priority in the Rules settings page using drag-and-drop.

Natural-language rule builder

You can draft rules by describing what you want in plain English. For example: "Generate a changelog video every time we create a release tag starting with v" — the builder configures the trigger, filters, and action for you.

Access it from Settings → Rules → Rule builder.

Next steps