embeddedCI documentation

YAML config and artifacts

EmbeddedCI is definition-driven: behavior should come from YAML, not hardcoded engine rules. This page documents how pack config, dependencies, and artifacts work in embeddedci.yaml.

Where config lives

  • Build-level config (selected packs and per-build overrides) is in embeddedci.yaml.
  • Pack-level config is in each pack's definitions.yaml under registry/packs/....
  • Boards define board-level information; packs define build scripts, dependencies, and produced artifacts.

Pack definition model

KeyRequiredDefaultDescription
typeNo—Pack type used for grouping and behavior.
scripts.buildNo—Script executed by the pack.
default_varsNo—Default template variables for the pack.
dependenciesNo—Upstream artifacts required before this pack runs.
artifactsNo—Outputs this pack produces.
configNo—Values exported as environment variables to build scripts.
skip.check_pathsNo—If outputs already exist, skip pack unless rebuild is requested.

Template syntax is {{var}}. Runtime values come from pack default_vars plus build-level vars overrides in embeddedci.yaml.

Variable resolution

  • Script env uses merged pack vars plus build_root, project_root, and arch_image_name.
  • Env keys are uppercased before script execution.
  • JSON-looking config values are kept literal unless they include {{...}}.

Dependencies

Each dependency declares pack, dest, and optionally src, optional, and copy_source_dir.

KeyRequiredDefaultDescription
packYes—Producer pack ID (or fetch).
destYes—Destination path/key template resolved with variables.
srcNo—Required for fetch dependencies; can be templated.
optionalNofalseIf true, missing dependency does not fail the build.
copy_source_dirNofalseCopy source parent directory instead of a single file.

If name is omitted and producer has multiple artifacts, all are consumed. Use eitherdest: out/path/{{artifact}} or a trailing slash destination.

Named dependency example

dependencies:
  - name: app_bin
    pack: apps/build
    dest: "out/app-build/{{artifact}}"

Consume all artifacts from a pack

dependencies:
  - pack: apps/build
    dest: "out/app-build/"

Artifacts

Artifacts define what a pack produces and how outputs are collected.

KeyRequiredDefaultDescription
pathYes—Logical artifact path. Supports template variables.
nameNo—Artifact identifier used for dependency lookup. Defaults to resolved path.
source_pathNo—Override source path used during output collection.
optionalNofalseIf true, missing output is allowed.
  • Artifact key format is packID::normalized(name).
  • Artifacts are copied into artifactsDir/<path>.
  • Pack scripts receive PACK_ARTIFACTS_JSON with resolved name, path, source_path, and optional.

Importing prebuilt outputs

artifacts:
  - path: kernel/zImage
    source_path: prebuilt/zImage
  - path: uboot/u-boot.bin
    source_path: /absolute/path/to/u-boot.bin

Current demo pipelines

minimal.yaml

version: 1
name: minimal build example
builds:
  example-build:
    targets:
      - id: beaglebone-black-c3
    packs:
      - id: system/kernel-linux
        config:
          ref: v6.12
          arch: arm64
      - id: system/uboot
        config:
          ref: v2026.01
          arch: arm64
      - id: apps/build
        config:
          cmd: make
          src: git+https://github.com/embeddedci-com/examples.git//selftest?ref=main
        artifacts:
          - path: selftest
            name: selftest
      - id: system/rootfs-image
        config:
          app_dst:
            - name: selftest
              path: /usr/bin/selftest
          size_mb: "64"
          hostname: embedded-ci-1
          console_login: enabled
          rootfs_user: embeddedci
          rootfs_password: embeddedci
          rootfs_root_password: embeddedci
      - id: test/hardware
        config:
          platform: beaglebone-black
          boot_success_pattern: "Linux embedded-ci-1 6.12.0-dirty"

buildroot.yaml

version: 1
name: buildroot example
builds:
  example-build:
    targets:
      - id: beaglebone-black-c3
    packs:
      - id: system/buildroot-kernel
        config:
          ref: v6.12
          arch: arm
          source: git+https://github.com/embeddedci-com/examples.git//buildroot-external/generic-kernel?ref=main
          defconfig: arm_defconfig
      - id: system/uboot
        config:
          ref: v2026.01
          arch: arm
      - id: apps/build
        config:
          cmd: make
          src: git+https://github.com/embeddedci-com/examples.git//selftest?ref=main
        artifacts:
          - path: selftest
      - id: system/buildroot-rootfs
        config:
          source: git+https://github.com/embeddedci-com/examples.git//buildroot-external/generic-rootfs?ref=main
          defconfig: arm_defconfig
          app_artifacts:
            - artifact: selftest
              dst: /usr/bin/selftest
              mode: "0755"
          overlays:
            - board/generic-rootfs/overlays/common
            - board/generic-rootfs/overlays/debug
          outputs:
            - ext4
      - id: test/hardware
        config:
          platform: beaglebone-black
          boot_success_pattern: "Linux embedded-ci-1 6.12.0-dirty"

Pack snippets used in demos

system/kernel-linux

- id: system/kernel-linux
  config:
    ref: v6.12
    arch: arm64

system/uboot

- id: system/uboot
  config:
    ref: v2026.01
    arch: arm64

apps/build

- id: apps/build
  config:
    cmd: make
    src: git+https://github.com/embeddedci-com/examples.git//selftest?ref=main
  artifacts:
    - path: selftest
      name: selftest

system/rootfs-image

- id: system/rootfs-image
  config:
    app_dst:
      - name: selftest
        path: /usr/bin/selftest
    size_mb: "64"
    hostname: embedded-ci-1
    console_login: enabled
    rootfs_user: embeddedci
    rootfs_password: embeddedci
    rootfs_root_password: embeddedci

system/buildroot-kernel

- id: system/buildroot-kernel
  config:
    ref: v6.12
    arch: arm64
    source: git+https://github.com/embeddedci-com/examples.git//buildroot-external/generic-kernel?ref=main
    defconfig: arm_defconfig

system/buildroot-rootfs

- id: system/buildroot-rootfs
  config:
    source: git+https://github.com/embeddedci-com/examples.git//buildroot-external/generic-rootfs?ref=main
    defconfig: arm_defconfig
    app_artifacts:
      - artifact: selftest
        dst: /usr/bin/selftest
        mode: "0755"
    overlays:
      - board/generic-rootfs/overlays/common
      - board/generic-rootfs/overlays/debug
    outputs:
      - ext4

test/hardware

- id: test/hardware
  config:
    platform: beaglebone-black
    boot_success_pattern: "Linux embedded-ci-1 6.12.0-dirty"

Next steps