# Marketing video in CI (opt-in)

The video suite ([Add videos to your project](https://kinhin.dev/guide/videos-for-your-project.md)) can build a launch video, social cuts and a preview of video
changes in GitHub Actions, from committed sources, with no secrets. It is **off by default**: a repository that does not
opt in gets no jobs, no cost and no new permissions.

[← Back to README](https://kinhin.dev/index.md) · [Add videos to your project](https://kinhin.dev/guide/videos-for-your-project.md) · [The plan behind it](https://github.com/RabinApps/kinhin/blob/main/docs/plans/marketing-suite-in-ci.md)

## Switch it on

Three switches, all off until you flip them:

1. **Repository variable.** Settings → Secrets and variables → Actions → Variables → `VIDEO_CI` = `true`. Without it every
   job in the Video workflow is skipped. This is the kill switch: set it back to `false` to stop everything.
2. **`video/ci.json`.** Set `"enabled": true`, then turn on the triggers you want (`triggers.release`,
   `triggers.pullRequest`, `triggers.schedule`). A manual run does not need `enabled`.
3. **The `marketing` environment** (Settings → Environments). Add required reviewers. Publishing (attaching to a release,
   opening a site pull request) waits for approval there, and only runs when `publish.release` or `publish.site` is `true`.

```json
{
  "enabled": true,
  "triggers": { "release": true, "pullRequest": false, "schedule": false },
  "projects": [
    { "project": "launch", "looks": [{}, { "theme": "midnight", "format": "9:16" }, { "format": "4:5" }] }
  ],
  "publish": { "release": true, "site": false },
  "budgets": { "mp4MB": 10, "seconds": 90, "buildMinutes": 20 }
}
```

## What runs, and when

| Trigger | When | Builds | Publishes |
|---|---|---|---|
| **Manual** (Actions → Video → Run workflow) | You pick project, theme, format, adapter | Exactly that, one look | Nothing: download the artifact |
| **Release** (`triggers.release`) | After the Release workflow succeeds for a tag | Every look in `projects` (the launch video, a vertical cut, a 4:5 cut) | The release (`publish.release`) and a site pull request (`publish.site`), each behind the `marketing` environment |
| **Pull request** (`triggers.pullRequest`) | A same-repository PR with the `video-preview` label, or one that changes a `previewPaths` file | The `preview` set, fast (a quicker encode) | Nothing: artifact and a job summary |
| **Schedule** (`triggers.schedule`) | The first of each month | Every look in `projects` | Nothing |

Pull requests from forks never build. Nothing here needs a secret: the build uses the workflow's read-only token, and only
the two publish jobs get `contents: write` (and `pull-requests: write` for the site pull request).

## The jobs

```
plan ──► claims ──► build (one job per look) ──► publish-release / publish-site (reviewed)
```

- **plan** decides whether to build and what, in seconds.
- **claims** is the honesty gate: it fails when a video says something the product does not support (for kinhin, any of the
  planned platforms such as Buildkite or Windows without saying they are planned, and tone words like "fastest"). The rules
  live in the adapter (`video/adapters/<name>/claims.json`) and the project file.
- **build** runs `video/scripts/build.sh --container --runtime docker` on a hosted Linux runner (the same command you run
  locally), then **verifies** the result and writes a summary table. A release build pulls the image published for that release
  (`ghcr.io/rabinapps/kinhin-video:<version>`, made by `video-image.yml`) instead of building it once per look; a pull request,
  a manual run, or a release whose image is not published yet builds it from the checked-out sources.
- **verify** is the same checker the end-to-end tests use (`video/scripts/verify.mjs`): the frame size, the length against the
  timeline, an audio track near -16 LUFS, no black frames, one caption per cue, a poster and a hero GIF that are not blank, and
  the size and length budgets. A video that fails is not published.

A failed video job never blocks a release, a docs deploy or a pull request: nothing depends on it.

## Store screenshots in the mobile cut

`examples/mobile-30s` is a launch cut that shows store screenshots. Its look sets `"screens": true` in `video/ci.json`, so
the plan adds one job before the build:

- **`mobile-capture`** runs on the macOS pool (`kinhin-xcode`), because the iOS simulator needs macOS. It generates the iOS
  example, runs `bundle exec fastlane screenshots` for `en-US` and `fr-FR`, and uploads the PNGs as the `mobile-screens`
  artifact. Only looks that set `screens` run it; other builds are unchanged.
- **`build`** (Linux, in the container) downloads `mobile-screens` into `video/screens/mobile/` for that look only, then
  renders. The cut's `device` scenes point at those files with `props.screens` (see [making a video](https://kinhin.dev/guide/making-a-video.md#screenshots-as-a-scene)).

There is one capture job per platform a look needs (`ios` and `android`), and each look picks its platform in `video/ci.json`.
The Android capture boots the pool's emulator (`KINHIN_AVD`, default `Pixel_9`) and needs its system image on the runner; the
iOS capture is verified locally, the Android one is not yet verified on the pool.

## Your own product's videos on your fleet

`kinhin video build <name> --on-fleet` runs a video of *your* repository on a runner kinhin serves, with no `video/` folder:
`kinhin video init --workflow` writes `.github/workflows/kinhin-video.yml` (pinned actions, read-only token, no secrets), and
`--on-fleet` dispatches it with `gh`, follows the run and downloads the result. See
[Building on your fleet](https://kinhin.dev/guide/videos-for-your-project.md#building-on-a-runner-or-in-ci). The opt-in `video.yml` described on this page is a
different thing: it builds *kinhin's* own videos from this repository.

## Try it without GitHub

The decisions are a script you can run here:

```bash
cd video
node scripts/video-ci.mjs validate                        # is ci.json valid?
node scripts/video-claims-lint.mjs --all                  # does every video say only true things?
VIDEO_CI=true GITHUB_EVENT_NAME=workflow_dispatch INPUT_PROJECT=launch \
  node scripts/video-ci.mjs plan                          # what would a manual run build?
scripts/build.sh --container --project examples/hello     # the build itself
node scripts/video-ci.mjs verify out                      # the checks, on a finished build
```

`scripts/video-check.sh` runs the first two plus the unit tests, and `scripts/check.sh` and the CI docs job run it on every
change. See [the tests](https://kinhin.dev/guide/making-a-video.md#tests) (kinhin's own guide).

## Use it for another product

Do not copy `video.yml`: it builds *kinhin's own* videos from this repository. For your product, keep your videos in `.kinhin/videos/`
and build them with `kinhin video build` on your Mac, or on your fleet with `kinhin video init --workflow` and `--on-fleet` (see
[Add videos to your project](https://kinhin.dev/guide/videos-for-your-project.md#building-on-a-runner-or-in-ci)). That generated workflow is manual (`workflow_dispatch`)
and pulls the published video image, so you need no `video/` folder; to build on every release, add a `release:` trigger to it yourself.

## When something fails

| Symptom | Likely cause |
|---|---|
| The workflow shows every job skipped | `VIDEO_CI` is not `true`, or `ci.json` has `"enabled": false`, or the trigger's switch is off. The plan job's log says which. |
| `claims` fails | A scene mentions something the adapter's `claims.json` lists as planned, or a tone word. The message names the scene and the text. |
| `build` fails in `verify` | The log lists each failed check (size, length, loudness, black frames, captions). Budgets are in `ci.json`. |
| A pull request got no preview | It is from a fork, or has neither the `video-preview` label nor a changed `previewPaths` file. |
| `publish-*` waits | It is waiting for approval in the `marketing` environment. |
