azldev
Read this before running azldev or editing azldev config, and whenever working in a repo that contains an azldev.toml file; do not guess azldev's commands or config. Explains how to use the azldev CLI to build a distro from TOML config, including the core concepts (components, overlays, distros, rendered specs, locks), running azldev (repo root or -C, plus the -q and -O json flags), the common commands, and where to go for each workflow. Triggers include azldev, comp build, comp render, comp update, build a component, add a component, distro config.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 5.4k
- Forks
- 714
01 前言 Front Matter
- name
- azldev
- description
- Read this before running azldev or editing azldev config, and whenever working in a repo that contains an azldev.toml file; do not guess azldev's commands or config. Explains how to use the azldev CLI to build a distro from TOML config, including the core concepts (components, overlays, distros, rendered specs, locks), running azldev (repo root or -C, plus the -q and -O json flags), the common commands, and where to go for each workflow. Triggers include azldev, comp build, comp render, comp update, build a component, add a component, distro config.
03 SKILL.md 正文
Using azldev
azldev builds a Linux distribution from TOML configuration. It imports RPM specs from an upstream distro and customizes them with an overlay system — no spec forking. Components render to specs and sidecar build inputs, then build into RPMs; images assemble RPMs into bootable artifacts.
Orient yourself
- Run azldev from the repo root (where
azldev.tomllives), or pass-C <dir>. - Global, agent-friendly flags:
-q(quiet) and-O json(machine-readable output). They work on every command. - Config is a stitched TOML hierarchy:
azldev.tomlincludes the distro and project config, which include the component files (**/*.comp.toml) into one namespace.
Core concepts
- Component — a unit of packaging that renders to a spec and sidecar build inputs, then builds into one or more RPMs. Its spec source is upstream (default), a pinned upstream distro/version, or a local spec.
- Overlay — a semantic patch applied to a spec or source file at render time, so you customize upstream without forking it.
- Distro — a named build target (
*.distro.toml) with upstream URIs, release versions, and build inputs. - Rendered spec — the generated
.specafter overlays; a build input, never hand-edited. - Lock — a per-component file pinning the resolved upstream commit and an input fingerprint.
Common commands
Top-level commands in this build:
azldev completion— Generate the autocompletion script for the specified shellazldev component— Manage componentsazldev config— Manage tool configurationazldev docs— Documentation commandsazldev image— Manage Azure Linux imagesazldev package— Manage binary package configurationazldev project— Manage Azure Linux projectsazldev repo— Inspect and manage RPM repositoriesazldev version— Print the CLI version
Everyday tasks (add -q -O json when scripting):
| Task | Command |
|---|---|
| List components | azldev comp list -a |
| Inspect one component | azldev comp list -p <name> |
| Add a component | azldev comp add |
| Build a component | azldev comp build -p <name> |
| Render specs | azldev comp render -p <name> (or -a) |
| Refresh a lock | azldev comp update -p <name> |
| List / build images | azldev image list / azldev image build |
comp is an alias for component. Always confirm current syntax with
azldev <command> --help.
The hidden advanced group (adv) contains specialist integrations such as MCP and
mock helpers; it is intentionally omitted from normal help.
Where to go next
- Add a new component — read the
azldev-add-componentskill. - Edit or review a component's TOML — read the
azldev-comp-tomlskill. - Add or change overlays — read the
azldev-overlaysskill. - Annotate an overlay's intent (category, upstream status, provenance) — read the
azldev-overlay-metadataskill. - Build, iterate, and debug a component — read the
azldev-build-componentskill. - Build, boot, and register images — read the
azldev-imageskill. - Refresh a lock and finalize for a PR — read the
azldev-update-componentskill. - Remove a component — read the
azldev-remove-componentskill. - Test built RPMs in a chroot — read the
azldev-mockskill.
Golden rules
- Never edit generated output — rendered specs and the output/work/log dirs are produced by azldev. Change the source config and re-render.
- Re-run
azldev comp updatebefore opening a PR — the lock fingerprint covers the whole component config, and lock / rendered-spec CI checks run on committed state. - Every overlay needs a
descriptionexplaining why the change is needed.
Generated by azldev docs agent; do not hand-edit.
04 同仓库更多 Skills
skill-metrics
[Skill] metrics, azure-monitor, aks - Query Azure Monitor metrics for Koji AKS node CPU, memory, disk usage, and pod readiness.
skill-mass-triage
[Skill] Batch-triage build failures from a JSON results file — diagnose with parallel sub-agents, bucketize by root cause, and produce a consolidated summary. Use when asked to triage a Koji results file. Triggers: batch triage, mass triage, triage results file, bucketize failures.
skill-kql-queries
[Skill] kql, queries, log analytics, container logs - KQL query templates for Koji container logs, pod errors, restarts, Kubernetes events, build job activity, and node resource usage via Log Analytics.
skill-koji-triage
[Skill] Examine Koji builds, fetch task info and logs from the Koji Web UI, identify failures, and provide root cause analysis. Use when triaging Koji build failures, investigating failed tasks, downloading build logs, or searching for broken packages. Triggers: koji failure, koji build failed, koji task, koji log, koji triage, build failure analysis.
skill-fedora-mirror-injections
[Skill] Diagnose Azure Linux Stage 1 (bootstrap-mirror) BuildRequires resolution failures and backfill missing RPMs into the prod Fedora updates mirror via the azl-infra injections file. Use when triaging stage-1 / azl4-bootstrap-mirror build failures, finding dependency gaps in the Fedora mirror, deciding whether a failure is a real mirror gap vs a transient timeout or a spec bug, adding entries to azl4-stage1-injections.yaml, or opening a PR with mirror injections. Triggers: bootstrap-mirror, stage 1 build failure, fedora mirror gap, missing BuildRequires, nothing provides crate, no match for argument, injections file, azl4-stage1-injections, mirror injection.
skill-deployment-context
[Skill] deployment context, aks, azure, koji - Resolve Koji AKS deployment context -- resource group, cluster name, subscription, Log Analytics workspace, and monitoring resource names from deployment_summary.yaml when available, or discover them dynamically from Azure.