Skip to content

Automation for developers and maintainers

Core automation for generating images for release are held at armbian/os

Note

For monitoring Armbian action scripts status and execution details, visit https://actions.armbian.com/

Prepare build lists

Recommended images on download pages and in Armbian imager are automatically generated via regular expression mapping file exposed.map. This file is generated by the generate_targets.py script from image-info.json.

Example:

Text Only
1
2
bananapim7/archive/Armbian_[0-9].*Bananapim7_noble_vendor_[0-9]*.[0-9]*.[0-9]*_gnome-kisak_desktop.img.xz
bananapim7/archive/Armbian_[0-9].*Bananapim7_bookworm_vendor_[0-9]*.[0-9]*.[0-9]*_minimal.img.xz

Maximum 2 images per board: bookworm minimal for all boards, plus a second image based on hardware classification (see table below). LoongArch boards only get one image (bookworm minimal only).

Standard support images

Target generation

Build target YAML files are automatically generated from image-info.json, which is produced by the build framework’s command: ./compile.sh inventory-boards.

Generated files:

Note

For changes to target generation logic, submit PR to the Python script at armbian.github.io

Hardware-based board classification

Boards are automatically classified by hardware speed and architecture to determine appropriate desktop environments:

Category Condition Desktop (nightly/community)
Fast HDMI ARM64/x86 with video, not in slow list GNOME
Slow HDMI ARM 32-bit or specific slower SoCs XFCE
Headless Boards without video output CLI only
RISC-V ARCH = riscv64 CLI only
LoongArch ARCH = loongarch64 CLI only (sid only)

Slow hardware list (gets XFCE):

  • ARM 32-bit (arm/armhf) architecture
  • Allwinner H3/H5/H6 (sun50iw*, sun55iw*)
  • Amlogic S905X/S912/S905X2/S922X/A311D (meson-gxbb, meson-gxl, meson-g12a, meson-g12b, meson-sm1)
  • Nuvoton MA35D1
  • Rockchip RK3328/RK3399/RK3399PRO

All other ARM64 and x86 boards with video are classified as fast (gets GNOME).

Automatic extensions

Fast HDMI boards automatically receive these extensions:

  • v4l2loopback-dkms - Video4Linux loopback device support
  • mesa-vpu - VPU driver for video acceleration

These can be supplemented with manual extensions via the extensions map.

Manual overrides

Blacklisting - exclude boards from automatic generation:

Files: targets-release-nightly.blacklist, targets-release-community-maintained.blacklist

Manual targets - add custom build targets:

Files: targets-release-nightly.manual, targets-release-community-maintained.manual

Extensions - add board-specific extensions:

File: targets-extensions.map

Format:

Text Only
1
BOARD_NAME:branch1:branch2:...:ENABLE_EXTENSIONS="ext1,ext2"

Example:

Text Only
1
khadas-edge2:legacy:vendor:,ENABLE_EXTENSIONS="image-output-oowow,v4l2loopback-dkms,mesa-vpu"

Wildcards apply to all branches:

Text Only
1
BOARD_NAME::ENABLE_EXTENSIONS="ext1,ext2"

Note

Manual extensions are merged with automatic extensions, not replaced.

Kernel Descriptions for Download Pages

Each kernel branch can include an optional description, automatically generated by the generate-build-lists workflow and published to kernel-description.json.

Descriptions are generated from image-info.json using template-based categorization (current/edge/legacy/vendor/custom) with version-appropriate naming and platform-specific optimization details.

Testing

Unfortunatelly this part does not have testing at PR stage.

Prepare Standard Support images for release

Info

Manual executing permissions are tied to release manager role.

Build Standard Support Images

This build workflow is executed manually when making:

  • a set of images for specific device
  • a set of images for specific maintainer
  • a full set of stable release images (default)

Notes:

  • this process prepares images for release without pushing them to the download pages
  • you can only generate images that are defined in targets-release-standard-support.yaml build lists!
  • images generation workflows are compiled and are pretty much the same, just with different defaults

1. Open workflow and click

Run Workflow

2. Select board

Workflow

Bump version: Select if you want to trigger system wide version bump. Version override: Set version under which you want to release images.

Images versions are stored in JSON files:

3. Run workflow

Build

(Workflow takes around 15 minutes to complete. In case of network issues it can also take hours)

Generated images are uploaded to incoming folder https://rsync.armbian.com/incoming/ under your GitHub username and once they are confirmed working, please notify @igorpecovnik to move them to official download pages. Once images are moved to main download section, automation refreshes download pages index within 15-30 minutes.

Aditional options

Generates stable images defined in targets-release-standard-support.yaml.

We are generating several images for each download / hardware target. They are automatically sorted by sections:

  • Desktop releases
  • Server and IOT releases
  • Dedicated applications

Images generation can be customized:

  • Framework build branch
    • main (make images from trunk)
    • vXX.X (previous stable release)
  • Bump Version (system wide version bump)
  • Version override (in case you don’t want to use latest)
  • Board (make images for one board only)
  • Maintainer (make images for selected maintainer)

Prepare application images for release (release manager)

Build Dedicated Application Images

This build workflow is executed manually when making:

  • a set of application images for specific device
  • a set of application images for specific maintainer
  • a full set of application images (default)

Notes:

  • application images are released 10-15 minutes after build finishes succesfully
  • you can only generate images for applications that are defined in targets-release-apps.yaml build lists!
  • images generation workflows are compiled and are pretty much the same, just with different defaults

1. Open workflow and click

Run Workflow

2. Select board

Workflow

Version override: Use this feature if you want to keep them under the same version, but not lower then last released.

3. Run workflow

Build

(Workflow takes around 15 minutes to complete. In case of network issues it can also take hours)

Generated images are hosted at GitHub https://github.com/armbian/distribution/releases and released at once. Automation refreshes download pages within 15-30 minutes after/if workflow finished succesfully.

Dedicated Application Images

Aditional options

Generates dedicated application images defined in targets-release-apps.yaml. This file is automatically generated from image-info.json by the generate-targets workflow.

Images generation can be customized:

  • framework build branch
    • main (make images from trunk)
    • vXX.X (previous stable release)
  • Bump Version (system wide version bump)
  • Version override (in case you don’t want to use latest)
  • board (make images only for one board)
  • maintainer (make images for selected maintainer)

Repository update (cronjob/release manager)

This pulls packages from build framework OCI cache located at GitHub and from various 3rd party repositories such as Chrome, Chromium, Code, Discord, (latest) ZFS, Thunderbird, Zoom, … and pushes them to:

  • apt.armbian.com (only new packages are added)
  • beta.armbian.com (whole repository is recreated from scratch)

1. Open workflow and click

Run Workflow

Action is executed automatically when artifact generations completes. Or manually.

2. Include artifacts from generated image(s)

When - [ ] Add https://netcup.armbian.com/partial/ to stable repo

is selected.

3. Run workflow

Build

(Workflow takes around 60 minutes to complete)

Build all artifacts (cronjob)

Build All Artifacts

Generates all build artifacts cache for targets defined in targets-all-not-eos.yaml. This build job runs every 8 hours and can also be run manually when needed.

This build job needs to be successfully completed in order to proceed generating any OS images!

Build Rolling Release Images (cronjob)

Build Nightly Images

Generates all nightly (Rolling Release) images defined in targets-release-nightly.yaml. This file is automatically generated from image-info.json by the generate-targets workflow.

This build job runs every day at 9 a.m. UTC and can also be run manually when needed. Download pages are refreshed automatically after successful build.

Build

Full distro test builds (cronjob/release manager)

Build Nightly Images

Generates all supported build combinations (minimal, cli, desktops) for x86 architecture to check package level changes inconsistency and dependencies.

Options:

  • Framework build branch
    • main
    • testing_branch (string)

Build all artifacts (admin/PR)

Generates artifacts at Pull Requests code. Build starts when label of Pull Request is set to “Build”. Requires administration privileges.