CI/CD Architecture¶

This is the canonical reference for FastVideo's CI/CD system. Contributor-facing PR steps live in Pull Requests, and test-authoring guidance lives in Testing.

Overview¶

FastVideo splits validation across GitHub Actions, Buildkite, and Modal:

PR opened or updated
  |
  |-- Tier 1: pre-commit
  |     GitHub Actions on ubuntu-latest
  |     style, lint, type, spelling, Markdown, workflow syntax, filenames
  |
  |-- Tier 2: Fastcheck
  |     Buildkite orchestrates Modal GPU jobs
  |     path-filtered component and unit checks
  |
  |-- /merge, /test full, or ready label
        |
        `-- Tier 3: Full Suite
              Buildkite orchestrates Modal GPU jobs
              path-filtered integration, SSIM, training, eval, and performance checks
              |
              pass -> Mergify squash-merges when all merge conditions pass
              fail -> fix, push, and re-run

CI is not one monolithic job:

• GitHub Actions owns pre-commit, slash-command handling, aggregate status updates, docs deployment, image builds, package publishing, and community automations.
• Buildkite owns the GPU test pipeline and path filtering.
• Modal owns the actual GPU execution environment for test jobs.
• Mergify owns merge protection, labeling, and the final squash merge.

CI Tiers¶

Tier 1: Pre-commit¶

The workflow runs .pre-commit-config.yaml with --hook-stage manual.

Run the pre-commit command above to reproduce failures locally. Do not bypass the project hook chain by calling individual tools directly unless you are debugging a hook implementation.

Tier 2: Fastcheck¶

Fastcheck uses Buildkite's monorepo-diff plugin. Jobs whose watched paths did not change are skipped and do not block the aggregate fastcheck-passed status.

Tier 3: Full Suite¶

Full Suite is also path-filtered. It validates broader behavior before Mergify can merge a PR.

A ready-labeled PR does not hit Buildkite immediately: ci-trigger-full-suite.yml first runs .github/scripts/gate_full_suite.sh, which waits for the cheap Tier-1 checks (pre-commit, docs build) on the PR head. A red cheap check blocks the suite (fail closed; the next push re-arms it), while a GitHub outage or a >25 min wait lets it run anyway (fail open). /test full bypasses the gate.

See Performance Benchmarks for the performance lane's thresholds, rolling baseline, artifacts, and reseeding process.

Slash Commands¶

Slash commands are handled by .github/workflows/ci-slash-commands.yml. Repository write permission is required.

Valid direct test names:

When a direct test completes successfully, Buildkite posts direct-test-completed. .github/workflows/ci-aggregate-status.yml then reads the latest Buildkite statuses for the commit and updates fastcheck-passed or full-suite-passed if all jobs in that group are green.

Skipped path-filtered jobs have no status entry and do not block the aggregate.

Merge Protection¶

Mergify enforces these conditions before it squash-merges to main:

The final merge action is a squash merge. Mergify also labels conflicting PRs with needs-rebase and removes that label after conflicts are resolved.

Title Tags And Labels¶

PR title tags are the source for type:* labels and are required by merge protection.

Scope labels are inferred from changed files.

Process labels:

Modal Test Entrypoints¶

All Buildkite test jobs go through .buildkite/scripts/pr_test.sh, which:

1. Reads Buildkite secrets for Modal, Hugging Face, and W&B when needed.
2. Selects a Modal function based on TEST_TYPE.
3. Passes Buildkite metadata into the Modal container.
4. Runs the selected test command from fastvideo/tests/modal/pr_test.py or fastvideo/tests/modal/ssim_test.py.
5. Uploads performance artifacts for TEST_TYPE=performance.

If you add a new CI test category:

1. Add the Modal function in fastvideo/tests/modal/pr_test.py or a focused companion module.
2. Add the TEST_TYPE case in .buildkite/scripts/pr_test.sh.
3. Add the Buildkite direct-test step and any Fastcheck/Full Suite path filters in .buildkite/pipeline.yml.
4. Add or update the /test mapping in .github/workflows/ci-slash-commands.yml.
5. Document the lane here and link any domain-specific authoring guide.

CD And Release Workflows¶

Documentation¶

.github/workflows/infra-docs.yml builds documentation for PRs that touch docs/**, mkdocs.yml, requirements-mkdocs.txt, or the workflow itself. On pushes to main, it also deploys the built site to GitHub Pages.

The docs job:

1. Installs the pinned MkDocs dependencies.
2. Runs mkdocs build; the native MkDocs hook generates example pages before the build.
3. Runs python scripts/check_docs_links.py against the generated documentation.
4. Uploads the Pages artifact and deploys only from main.

Docker Images¶

.github/workflows/infra-build-image.yml supports manual workflow_dispatch runs and automatically rebuilds the CUDA matrix when a repository-controlled image input changes on main in the canonical repository. Those inputs include the CUDA Dockerfile and reusable workflow, dependency metadata, Docker context policy, fastvideo-kernel/**, and the kernel artifact metadata/key helper. Manual runs let maintainers choose which image families to build. The fastvideo-dev matrix builds Python 3.12 images for CUDA 12.6 and CUDA 13 on native amd64 and arm64 runners, then publishes one multi-platform manifest per CUDA version. CUDA 12.6 owns the py3.12-latest and global latest tags, as well as the explicit py3.12-cuda12.6.3-latest alias. CUDA 13 is published under the explicit py3.12-cuda13.0.0-latest tag. This publication policy does not change the unparameterized docker/Dockerfile build defaults, which remain CUDA 13 and cu130.

Published amd64 development images keep their configured Hopper kernel wheel installed and also carry an immutable SM89 wheel under /opt/fastvideo-kernel-prebuilt. Modal PR and SSIM jobs select the exact source, ABI, and GPU-architecture match from that directory, so L40S jobs reuse the trusted image artifact while kernel-changing PRs still build locally. Once a kernel or artifact-key change reaches main, the image workflow republishes the matching trusted artifact before later jobs consume the updated image tag.

The optional Dreamverse matrix builds backend and UI images for CUDA 12.6 and CUDA 13 on amd64. Dreamverse remains amd64-only because its FA4 dependency stack is not yet validated on ARM64.

The reusable implementation lives in .github/workflows/_template-build-image.yml.

Package Publishing¶

Community Automations¶

File Reference¶