/jetson-promote-image

name: jetson-promote-image
description: >-
  Use to promote overlay files and built artifacts into the staged
  BSP image. Do NOT use to flash or build. Triggers: promote bsp
  image.
version: 0.0.1
license: "Apache-2.0"
metadata:
  data-classification: public
  author: "Jetson Team"
  team: pts
  tags:
    - bsp
    - promote
    - deploy
  domain: meta

Promote BSP Image

Purpose

Stage every Customize-* and Build output into `bsp_image` so it is ready for `/jetson-flash-image`. This is the **promote leg of Deploy** — it copies files, never flashes and never builds.

Prerequisites

• Active target-platform profile with both `source:` and `bsp_image:`

resolved (run `/jetson-init-source` and `/jetson-init-image` first).

• `<source.root_path>/Linux_for_Tegra/` initialized as a git repo

(overlay tracker) with a clean working tree.

• `<bsp_image.root_path>/Linux_for_Tegra/` extracted from a BSP

tarball + `apply_binaries.sh` already run.

• `git`, `yq`, `cmp`, and `sudo` (for `rootfs/*` destinations) on

the host.

• `<source.root_path>/.build-manifest.yaml` + `.build-state.yaml`

from `/jetson-build-source` (required when kernel-side repos have customize-* commits).

Overview

This is the **promote leg of Deploy** — see [`../../context/bsp-customization-workflow.md`](../../context/bsp-customization-workflow.md) for the pipeline view. The two channels this skill walks are:

| Channel | Source | Carrier | Owner | |---|---|---|---| | **Overlay tracker** | `<source.root_path>/Linux_for_Tegra/` (git repo at HEAD) | Customize-* outputs that don't require a build (e.g. `nvfancontrol.conf`, `nvpmodel.conf`, BPMP DTB hand-edits) | Customize `customize-*` skills commit here | | **Build manifest** | `<source.root_path>/.build-manifest.yaml` | Rebuilt kernel `Image`, in-tree `.ko`, OOT `.ko`, NVIDIA DTBs | Build [`jetson-build-source`](../jetson-build-source/SKILL.md) writes here |

The skill computes the union of files to copy and writes each into `<bsp_image.root_path>/Linux_for_Tegra/` with diff-aware skip-if-identical logic. When the copy pass touches the kernel `Image` or anything under `rootfs/lib/modules/`, it also rebuilds the initramfs via NVIDIA's `tools/l4t_update_initrd.sh` so the freshly promoted kernel + modules ship in the initrd the bootloader actually loads. After it returns, `bsp_image` carries every Customize and Build output. The skill does **not** flash and does **not** modify the workspace.

When to invoke

• First leg of the typical Deploy chain

`jetson-promote-image → jetson-flash-image → jetson-validate-image`.

• Standalone, when the user wants `bsp_image` updated but isn't

ready to flash yet (e.g. to inspect resolved files, run an out-of-band build that reads bsp_image, or hand bsp_image to a separate flashing host).

Procedure

Resolve active target + paths

Resolve the active profile per the contract in [`../../context/target-platform-contract.md`](../../context/target-platform-contract.md).

Refuse and route in these cases:

| Condition | Refuse with | |---|---| | No active profile, or `active: NA` | Route to `/jetson-set-target` or `/jetson-init-target`. | | Profile lacks `bsp_image:` | Route to `/jetson-init-image`. | | `<bsp_image.root_path>/Linux_for_Tegra/` missing | Route to `/jetson-init-image`. | | `<source.root_path>/Linux_for_Tegra/` missing or not a git repo | Route to `/jetson-init-source`. |

Resolve paths:

• `<workspace>` = parent of the active profile's `target-platform/`

directory (discovered at load time).

• `<bsp_image.root_path>` from `bsp_image.root_path:` if present,

else `<workspace>/Image`.

• `<source.root_path>` from `source.root_path:` if present, else

`<workspace>/Source`.

Bind shell variables for the rest of the procedure:

LFT_SRC="<source.root_path>/Linux_for_Tegra"   # overlay tracker
LFT_DST="<bsp_image.root_path>/Linux_for_Tegra"
MANIFEST="<source.root_path>/.build-manifest.yaml"   # build outputs

Validate the two channels

The skill needs at least one channel populated. Refuse if the overlay tracker has uncommitted changes (`status --porcelain` non-empty), if `$MANIFEST` exists but doesn't parse as YAML, or if both channels are empty. Records `OVERLAY_HAS_COMMITS` / `OVERLAY_HEAD` and `MANIFEST_PRESENT` for downstream steps.

See [`references/copy-pass-snippets.md`](references/copy-pass-snippets.md#validate-the-two-channels) for the shell snippet and refuse messages.

Verify build-source freshness

Refuse if `.build-state.yaml` shows any kernel-side repo in `Source/bsp_sources/` dirty since the last `/jetson-build-source` — otherwise the copy pass would silently ship stale artifacts. Detection rules + shell snippet in [`references/build-source-freshness-gate.md`](references/build-source-freshness-gate.md). Records `BUILD_FRESH=1`.

Pre-promote collision check (overlay only)

When the overlay tracks a remote, refuse if upstream has commits not yet pulled. Skip gracefully when no remote is configured (the default `git init` empty tracker from `jetson-init-source`). Manifest channel has no git remote concept — this check is overlay-only. Records `COLLISION_CHECK` for the Summary.

See [`references/copy-pass-snippets.md`](references/copy-pass-snippets.md#pre-promote-collision-check-overlay-only) for the shell snippet.

Enumerate sources (both channels)

**Channel A — overlay**: `git ls-files` against `$LFT_SRC` is the source of truth (transparent to symlink mounts when `source.repos.Linux_for_Tegra` was overridden, excludes untracked / `.gitignore`d files). Each entry maps `src = $LFT_SRC/<rel>` → `dst = $LFT_DST/<rel>`.

**Channel B — manifest**: parse `artifacts[].{src,dst}` from `$MANIFEST`. Refuse if any `src` is missing on disk (build was interrupted, or manifest stale — re-run `/jetson-build-source`). The manifest schema is written by [`jetson-build-source` v0.2.0](../jetson-build-source/references/manifest-schema.md).

See [`references/copy-pass-snippets.md`