build_manifests/README.md

build_manifests

Device manifests for the A-Team Jenkins build pipelines.

Each base branch has one Jenkins job (named after the branch) running the shared Jenkinsfile from main. It rolls the base's warm source tree back to @warm, drops one device XML into .repo/local_manifests/, syncs only the projects listed in it, reads the device info from its annotations and the base settings from the branch's build.toml.

Layout

One branch per build base, one file per device.

ofrp-12.1/      genevn.xml  milanf.xml  rtwo.xml ...
twrp-12.1/      genevn.xml ...
aera-16.0/      genevn.xml  milanf.xml ...

A job points at a branch + file, e.g. ofrp-12.1 / genevn.xml.

Device XML

A standard repo local manifest, plus ateam.* annotations on the device tree project.

<?xml version="1.0" encoding="UTF-8"?>
<manifest>
  <remote name="ateam" fetch="ssh://git@ateam.gotadell.com/" />

  <project path="device/motorola/genevn"
    name="A-Team_Digital_Solutions/recovery_device_motorola_genevn"
    remote="ateam" revision="ofrp-12.1">
    <annotation name="ateam.model"        value="XT2315"/>
    <annotation name="ateam.device_name"  value="Moto G Stylus 5G 2023"/>
    <annotation name="ateam.manufacturer" value="Motorola"/>
    <annotation name="ateam.partition"    value="recovery"/>
  </project>
</manifest>

Annotations

All four are required; the build stops if one is missing.

Annotation	Used for	Example
ateam.model	Release file name, portal device name	XT2315
ateam.device_name	Portal device name	Moto G Stylus 5G 2023
ateam.manufacturer	Portal	Motorola
ateam.partition	Build target and flash target	recovery

ateam.partition must be one of:

Value	Builds
recovery	recoveryimage
boot	bootimage
vendor_boot	vendorbootimage

The portal shows the device as <device_name> (<model>).

Projects

• List the device tree plus anything else the device needs (kernel, vendor, common trees).
• Every project listed gets synced; nothing else in the base tree is touched.
• Any git source works. Add another <remote> for GitHub or elsewhere; the device tree doesn't have to live on A-Team Forgejo.
• Pin revision to the branch for that base (e.g. ofrp-12.1).
• Don't add projects that override the base's own repos. Device-specific fixes go in the device trees.

Release naming

Builds come out as:

<RECOVERY>-<ver>_A-Team_<codename>_<model>-<YYMMDD>.<img|zip>

plus a .sha256 for each, e.g. OFRP-12.1_A-Team_genevn_XT2315-261009.zip.

Adding a device

1. Clone and switch to the base branch:

   git clone ssh://git@ateam.gotadell.com/A-Team_Digital_Solutions/build_manifests.git
   cd build_manifests
   git checkout ofrp-12.1
   

2. Copy an existing XML to <codename>.xml and edit the projects and annotations.
3. Commit and push.
4. That's it: the branch's Jenkins job (named after the branch, e.g. ofrp-12.1) lists the new XML in its DEVICE dropdown, and the portal picks it up on its next device sync.

Adding a base

1. Create a new branch named <base>-<version> (e.g. shrp-12.1) and add a device XML for each device built on it. Each base has its own copy of a device's XML, so update model or name changes on every branch that has that device.
2. Add a build.toml (see the README on main) describing the base: portal project, release naming, ZFS dataset, lunch target and release files.
3. Prepare the warm source tree on buildBox and snapshot it as <dataset>@warm.
4. Create a Jenkins job named exactly like the branch, using Pipeline script from SCM on build_manifests branch main, script path Jenkinsfile.
5. Map the portal project to the job in the portal admin.

Build pipeline

Jenkinsfile on main is the build pipeline for every base. Each base branch has one Jenkins job named exactly like the branch (ofrp-12.1, twrp-12.1, ...), set to Pipeline script from SCM on this repo, branch main, script path Jenkinsfile. A job named cms-<branch> builds the same base for the cms test portal (test bucket, test credentials, ateam-cms.gotadell.com).

Per run the job:

1. checks the device codename, resolves build.toml for that device (pipeline/build_config.py) and checks the warm snapshot and its mountpoint;
2. rolls the base back to <zfs_dataset>@warm and checks the warm base is clean (no device tree for the device, empty out/target/product, empty .repo/local_manifests);
3. copies <DEVICE>.xml into .repo/local_manifests/, fixes branch-name case, reads the ateam.* annotations and syncs only the listed projects;
4. runs lunch, m installclean and mka <make_extra> <partition target>;
5. picks the release files from out/target/product/<codename>/, verifies their native checksums, renames them to the A-Team scheme with a .sha256 each, uploads them to Garage and registers the build with the portal as testing (including the portal request id when the portal started it);
6. rolls the base back to @warm again (on failure the tree is left for diagnosis; the next run rolls it back).

A base's live and cms- jobs share one ZFS dataset and hold the warm-base:<branch> lock (Lockable Resources plugin) for the whole run.

Parameters: DEVICE (lists the branch's XMLs), CHANGELOG, PORTAL_REQUEST_ID and PORTAL_USER (set by the portal's Start build), and MANIFEST_REF (cms- test jobs only, to build from an unmerged branch).

build.toml

Every base branch has a build.toml next to the device XMLs. It is data only: unknown keys, wrong types or placeholders other than {codename} stop the build.

[base]
project      = "orangefox"           # portal project slug
project_name = "OrangeFox"
version      = "R12.1"               # version shown in the portal
release_tag  = "OFRP"                # <release_tag>-<release_ver>_A-Team_<codename>_<model>-<YYMMDD>
release_ver  = "12.1"
source_root  = "/build/ofox-12.1"    # mountpoint of zfs_dataset; out/ lives inside it
zfs_dataset  = "build/ofox-12.1"     # rolled back to @warm before and after every build
warm_check   = ["vendor/recovery"]   # must exist in the warm base
lunch_target = "twrp_{codename}-eng"
make_extra   = ["adbd"]              # built together with the ateam.partition target
changelog    = "Automated OrangeFox testing build."

[base.env]                           # extra environment for lunch and the build
FOX_BUILD_DEVICE = "{codename}"

[outputs.img]                        # release files in out/target/product/<codename>/, exactly one match each
glob     = "OrangeFox-*.img"
checksum = "md5"                     # native sidecar to verify: md5 | sha256 | none

[outputs.zip]
glob     = "OrangeFox-*.zip"
checksum = "md5"
test_zip = true

[devices.sycamore_row_5G]            # optional per-device overrides: lunch_target, make_extra, env, outputs
lunch_target = "twrp_sycamore_row_5G-eng"

Each [outputs.<ext>] becomes <release name>.<ext> plus <release name>.<ext>.sha256.