Configuration reference

The embeddedci.yaml file defines your build pipeline. Place it in the root of your project (or a subdirectory) and submit it via the API or GitHub Actions.

Minimal example

A minimal config that builds STM32 firmware and runs a hardware test:

version: 1
name: my-firmware-project
builds:
  my-build:
    targets:
      - id: beaglebone-black-c3
    packs:
      - id: firmware/stm32-build
        config:
          build_system: make
          cmd: make -j$(nproc)
          artifact_elf: build/main.elf
          artifact_bin: build/main.bin
          toolchain: arm-none-eabi
      - id: test/hardware
        config:
          platform: nucleo-f446re
          success_pattern: "SELFTEST PASS"

Top-level fields

Field	Required	Description
`version`	Yes	Must be `1`.
`name`	No	Human-readable project name. Defaults to `firmware-project`.
`builds`	Yes	Map of build names to build definitions. At least one build is required.

Build definition

Each key under builds is a named build (e.g. my-build).

Field	Required	Description
`targets`	Yes	List of target boards. Each entry has an `id` field matching a board in the registry (e.g. `beaglebone-black-c3`, `qemu-aarch64`, `nucleo-f446re`).
`packs`	Yes	Ordered list of buildpack references. Packs run in dependency order.

Pack reference

Each entry in the packs list selects a buildpack and configures it.

Field	Required	Description
`id`	Yes	Pack identifier matching a directory in the registry, e.g. `firmware/stm32-build`, `system/kernel-linux`, `apps/build`.
`targets`	No	Optional list of target IDs. When set, this pack only runs for the listed targets. Useful when a pack applies to one board but not others.
`config`	No	Key-value map of pack-specific settings. Keys are merged with the pack's defaults and exposed as uppercase environment variables during the build. See Buildpacks for per-pack config keys.

Example of a pack restricted to a specific target:

packs:
  - id: system/initramfs-busybox
    targets: ["qemu-aarch64"]
    config:
      ref: "1_36_1"

Full example: Linux kernel + rootfs + test

This builds a Linux kernel, U-Boot, a userspace application, a root filesystem with the application installed, and runs a hardware test:

version: 1
name: linux kernel + rootfs + hardware test
builds:
  my-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
          artifact: selftest
      - id: system/rootfs-image
        config:
          artifact: selftest
          app_dst: /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"

The apps/build pack compiles your application source from the project root (no src field needed when your code lives alongside embeddedci.yaml). The system/rootfs-image pack picks up the binary and installs it at app_dst.

Source resolution

When you submit a job via the GitHub Action or archive mode, your project files are uploaded alongside the YAML. Packs that need source code (like apps/build or firmware/stm32-build) will use your project files automatically.

No src field: the pack builds from your project root (most common for user repos).
Relative path: src: my-subdir/ builds from a subdirectory of your project.

GitHub Actions integration

Use the embeddedci-com/submit-job-action to submit jobs from GitHub Actions. The action archives your source code and sends it with the YAML to the EmbeddedCI API.

name: EmbeddedCI
on:
  push:
    paths:
      - "my-project/**"
      - ".github/workflows/embeddedci.yml"

jobs:
  submit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Submit job to EmbeddedCI
        uses: embeddedci-com/submit-job-action@main
        with:
          api_url: ${{ secrets.EMBEDDEDCI_API_URL }}
          api_key: ${{ secrets.EMBEDDEDCI_API_KEY }}
          source_path: my-project

Input	Required	Description
`api_url`	Yes	Your EmbeddedCI API URL. Store as a repository secret.
`api_key`	Yes	Your API key (generated on the Get Started page). Store as a repository secret.
`source_path`	Yes	Path to the directory containing `embeddedci.yaml` and your source files. The action archives this directory and submits it.

Add EMBEDDEDCI_API_URL and EMBEDDEDCI_API_KEY as repository secrets in your GitHub repo settings.