GitLab CI

GitLab CI

This project uses GitLab CI to build the nvmpi library, patch and compile ffmpeg across multiple versions, and run hardware encode/decode tests on NVIDIA Jetson hardware.

The canonical GitLab remote is origin at https://gitlab.timmertech.nl/timmertech/jetson-ffmpeg.git.

Runner Tag Convention

Tag	Purpose
(none)	Build stages have no tags — they run on any available runner.
jetson + <variant>	Hardware-specific (e.g. orin-nx, agx, nano). HW test jobs target specific Jetson hardware.

This means:

• Build jobs run on any available runner (no GPU needed, stubs build).
• HW test jobs run once per variant listed in the CI matrix, targeting jetson + <variant>.
• Adding new hardware = request a token, register a project runner with jetson, <variant>, add a matrix entry.

Pipeline Overview

Stage	Job(s)	What it does	GPU required
build	nvmpi:jp6, nvmpi:jp5	Compile libnvmpi with stubs (WITH_STUBS=ON)	No
build	ffmpeg:jp6 (matrix: 6.0–8.1), ffmpeg:jp5 (matrix)	Clone FFmpeg, patch, configure and build with nvmpi	No
test	test:ffmpeg-<ver>:jp6	Hardware encode/decode — one job per FFmpeg version × Jetson variant	Yes
dist	dist:jp6 (matrix), dist:jp5 (matrix)	Build release archives with libnvmpi + FFmpeg (tag pipelines only)	No
release	release	Generate changelog, create GitLab + GitHub releases (tag pipelines only)	No

Each test job reuses its version's build artifact, so the Jetson runner does not rebuild. Build jobs use parallel:matrix — a single job definition covers all FFmpeg versions, replacing the previous 7+ individual per-version jobs. Why one job per version (and why 6.0–7.1 compile identical wrapper code) is explained in the "Wrapper code paths by FFmpeg version" table in Development Guide.

Adding a New Hardware Variant

Step 1: Request a runner token

Open an issue using the GitLab Runner Token Request template. A maintainer will create a project runner with tags jetson, <variant> and share the glrt-... token with you.

Step 2: Set up the runner

Follow the guide matching your environment:

Environment	Guide
Kubernetes (k3s / k8s)	GITLAB_RUNNER_K8S.md
Bare-metal Jetson OS	GITLAB_RUNNER_MANUAL.md

Step 3: Add the variant to the CI matrix

In .gitlab-ci.yml, add your variant to the shared .hw-test parallel matrix (the test:ffmpeg-*:jp6 jobs all inherit it via the &hw-test anchor, so one edit covers every version):

.hw-test: &hw-test
  parallel:
    matrix:
      - JETSON_VARIANT: orin-nx
      - JETSON_VARIANT: agx        # <-- add your variant here
      # - JETSON_VARIANT: nano

Submit a merge request with this change. Once merged, every per-version HW test job runs on your hardware alongside existing variants. If no runner with matching tags is available, that matrix entry stays pending until one comes online.

L4T Version

The pipeline tests both JetPack 6 (L4T r36.x, default) and JetPack 5 (L4T r35.x) via separate matrix definitions. The jp6 jobs use L4T_TAG: "r36.4.0" by default; jp5 jobs use the corresponding r35.x tag.

If your Jetson runs a different JetPack/L4T version, update the variable in .gitlab-ci.yml:

variables:
  L4T_TAG: "r36.3.0"  # match your JetPack version

Check your installed version:

cat /etc/nv_tegra_release
# or
dpkg -l | grep nvidia-l4t-core

Troubleshooting

"No matching runner found"

• Verify runner is online in Settings > CI/CD > Runners
• Build jobs have no tags — any runner can pick them up
• HW test jobs need a runner tagged both jetson AND <variant> matching the matrix entry
• If your variant is commented out in the matrix, uncomment it

Build fails with missing Jetson Multimedia API

The l4t-jetpack container image should include it. If not:

apt-get install -y nvidia-l4t-jetson-multimedia-api

The CI before_script already handles this fallback.

HW test fails with "nvmpi encoders missing"

• The NVIDIA runtime is not injecting Tegra libraries
• See troubleshooting in GITLAB_RUNNER_K8S.md or GITLAB_RUNNER_MANUAL.md

Artifacts too large or jobs timing out

• Reduce the ffmpeg version matrix (remove older versions from .gitlab-ci.yml)
• Increase the runner pod/host resource limits
• Use a persistent volume or cache for build artifacts

Docker Image Builds

CI Docker images (builder, l4t-jetpack, release-tools) are gated behind the BUILD_IMAGES CI variable. Set BUILD_IMAGES=true in a pipeline to trigger image rebuilds — Dockerfile changes alone no longer auto-trigger builds.

See Scripts and Commands — build-images.sh for building images locally.

File Reference

File	Purpose
.gitlab-ci.yml	Pipeline definition with hardware variant matrix
test/hw-all.sh	Per-feature hardware test suites (auto-discovered)
scripts/build.sh	Build/install libnvmpi (auto-detects stubs vs Jetson)
scripts/ffpatch.sh	Patches ffmpeg source with nvmpi codec support
ffmpeg/patches/	Generated patch files for all supported FFmpeg versions
GitLab Runner Kubernetes	Runner setup guide for Kubernetes
GitLab Runner Manual	Runner setup guide for bare-metal Jetson
.gitlab/issue_templates/GitLab Runner Token Request.md	Issue template for requesting a runner token