Developing the Azure Linux distro

Getting Started

Install azldev

The azldev CLI tool drives all component, image, and build workflows. Install it from source (requires Go):

go install "github.com/microsoft/azure-linux-dev-tools/cmd/azldev@$(cat .azldev-version)"

Note: azldev is still in active development, using the latest commit from the main branch is recommended for the most up-to-date features and fixes.

Render specs

The specs/ directory (as specified by rendered-specs-dir config) contains "rendered" spec files created by azldev. They are a read-only snapshot of the final spec files after all overlays and modifications have been applied. They are the canonical source for what will be built and packaged.

They can be updated at any time by running azldev component render -a, or a single component can be rendered with azldev component render <name>.

AI-Assisted Development (VSCode + GitHub Copilot CLI)

This repo includes GitHub Copilot prompt files in .github/ that automate common workflows. Open VS Code with Copilot Chat in Agent mode, attach a prompt (📎), and fill in the inputs.

Important: VSCode works properly when opened as a workspace (i.e. open code ~/repos/azurelinux, NOT code ~/repos). Otherwise, Copilot may not find the prompt files and won't load the skills.

If the workspace is opened correctly, the agent will automatically gain access to the relevant instructions.

You may need to ensure ⚙️chat.useAgentSkills is enabled in your VSCode settings for skills to work properly.

Prerequisites

The azl-diagnose agent and Koji-related tools require:

1. MCP Python packages — the MCP servers won't start without them:

   pip3 install --user -r scripts/mcps/requirements.txt
   

2. Network access to the internal Koji instance — The internal Koji is only accessible via VPN or the corporate network. If the agent reports connection errors, verify you are connected before retrying.
3. (Optional) .env configuration — Create a .env file (in the workspace root or scripts/mcps/) to pre-configure MCP server settings like the Koji base URL and pre-approved insecure URLs. This avoids the agent having to set the URL or approve self-signed certificates every session. See scripts/mcps/.env.example for available variables.

Ask Copilot about any aspect of the project — it can reference the instructions and skills to provide detailed, actionable answers or perform tasks. For example:

> Add the cowsay package, but make it clippysay and make clippy the default

In VSCode, there are specialized prompts for common tasks. They can be accessed from the chat window by typing /azl-... to filter for Azure Linux prompts:

Prompt	What it does
azl-diagnose	Diagnose a build failure using a Koji task ID, URL, or package name. Great starting point for any build issue.
azl-add-component	Import a package from Fedora — overlays, build & test.
azl-update-component	Version bump, dependency change, or overlay edit.
azl-debug-component	Triage build failures, overlay errors, or packaging issues.
azl-review-component	Audit a component for hygiene and best practices.
azl-migrate-component	Move an inline entry to a dedicated .comp.toml file.
azl-mass-triage	Batch-triage build failures from a JSON results file — diagnose, bucketize, and summarize.

Agents

In addition to prompts, the repo includes chat agents that can be selected from the chat participant dropdown (the model/agent next to the Copilot Chat panel). Select the agent, then type your query:

Agent	What it does
azl-diagnose	Diagnose build failures — fetch task info/logs, identify root cause, and suggest fixes. Give it a task ID, URL, or package name.
spec-review	Review spec files against packaging best practices and produce a structured findings report.

Example: select azl-diagnose from the dropdown, then type:

> what is the status of the lolcat package

> https://koji.example.com/koji/taskinfo?taskID=1234

Copilot CLI

The skills and instructions are also compatible with the GitHub Copilot CLI which can be used directly from the terminal without opening VSCode.

# Fully interactive mode (from the repo root)
copilot --add-dir .

# Run a specific prompt, then drop to interactive mode
copilot --add-dir . -i "Upgrade vim to the next stable release"

Note: copilot supports fully autonomous operation (no interactive mode) with -p <prompt> however, until azldev supports a full MCP mode the tool approvals are very difficult. --yolo (same as --allow-all-tools --allow-all-paths --allow-all-urls) is an option, but use with extreme caution since it grants the agent unrestricted access to your filesystem and network. For now, it's recommended to use -i to at least have visibility into the agent's thought process and tool usage.

Using as a plugin (cross-repo access)

This repo includes a Copilot plugin manifest that makes its skills available from any working directory — not just the repo root. This is useful when you're working in another repo but want access to azurelinux skills (component builds, overlay debugging, Koji triage, etc.).

Install as a plugin (local clone):

# One-time install — skills persist across sessions
copilot plugin install --plugin-dir /path/to/azurelinux

# Or load for a single session
copilot --plugin-dir /path/to/azurelinux

After installing, all skills are available regardless of your current directory. Use /skills to list them.

Note: Remote install via copilot plugin install microsoft/azurelinux will work once this branch (4.0) becomes the repo's default branch on GitHub. Until then, use the local path.

Dockerized Batch Triage

For batch triage of build failures, a containerized wrapper runs the azl-diagnose agent inside an Azure Linux 3.0 container. The repo is mounted read-only, the agent analyzes a results JSON file, and writes triage reports to out/triage/.

# Default: reads ./results.json
scripts/batch-triage/triage.sh

# Custom results file
scripts/batch-triage/triage.sh --results /path/to/results.json

# With extra instructions
scripts/batch-triage/triage.sh --results /path/to/results.json 'only triage one package'

Requirements:

• Docker (buildx recommended)
• GitHub auth (copilot env var, copilot logged in, or gh logged in)
• a .env file (see above).

Output lands in out/triage/.

See scripts/batch-triage/ for the Dockerfile and wrapper script.

CLI Agents

Copilot CLI also supports agents, use /agent to select one, or start the CLI with a specific agent:

copilot --add-dir . --agent azl-diagnose