In an azure-pipelines.yml file, how do stages, jobs and steps nest, and which of the three is the unit that gets an agent?

## The three levels Azure Pipelines describes a run with three nested constructs, written top-down in a YAML file that is conventionally named `azure-pipelines.yml`: - **stages** — the coarsest grouping, usually one per delivery phase (`Build`, `Test`, `Deploy`). - **jobs** — a unit of work inside a stage. - **steps** — the individual commands: a `task:` (a packaged unit from the task library, referenced as `TaskName@version`), or one of the script shorthands `script:`, `bash:`, `pwsh:`, `powershell:`. ```yaml stages: - stage: Build jobs: - job: Compile pool: vmImage: ubuntu-latest steps: - script: ./gradlew assemble displayName: Compile - task: PublishPipelineArtifact@1 inputs: targetPath: build/libs artifact: app ``` ## The job is the allocation unit The single fact that makes this hierarchy behave the way it does: **an agent is assigned per job**. Azure DevOps takes a job off the queue, finds an agent in the job's pool that satisfies its demands, and that one agent executes every step of the job, sequentially, in one workspace directory. Steps therefore share everything for free — the filesystem, the installed toolchain, the process environment, the checked-out source. Jobs share none of that. Two jobs in the same stage can be dispatched to two different agents on two different machines. Even on a single self-hosted agent, there is no guarantee both jobs land there, and Azure will not reuse one job's workspace as another's. So the moment you split work into two jobs, you have to *transport* anything they share: - **Files** — publish from the producer (`PublishPipelineArtifact@1`) and download in the consumer (`DownloadPipelineArtifact@1`); a `checkout` also happens per job by default. - **Values** — mark a variable as an output variable when you set it, then read it through the `dependencies` context in the consuming job. This is the number-one surprise for people new to the platform: a `cd` or a `npm install` in job A means nothing to job B. ## Ordering: sequential stages, parallel jobs By default, **stages run one after another** in the order written, and a stage only starts if the previous one succeeded. **Jobs inside a stage run in parallel** by default. Both defaults are overridden with `dependsOn`, which turns the flat list into an explicit dependency graph: ```yaml jobs: - job: A steps: [ { script: echo a } ] - job: B steps: [ { script: echo b } ] - job: C dependsOn: [ A, B ] # fan-in: waits for both steps: [ { script: echo c } ] ``` An empty `dependsOn: []` on a stage removes its implicit dependency on the previous stage, letting stages run concurrently. How much of that parallelism you actually get is capped by the parallel-job slots the organisation has bought or been granted, so a fan-out of twenty jobs may still execute a few at a time. ## Implicit shorthands Azure lets you omit the outer levels when you do not need them, and quietly supplies them: - A file with only `steps:` at the root becomes **one stage containing one job containing those steps**. - A file with only `jobs:` becomes one implicit stage. That shorthand is why small pipelines look nothing like the three-level model, and why the model still applies to them: the single implicit job is still what receives the agent. ```yaml trigger: [ main ] pool: vmImage: ubuntu-latest steps: - script: npm ci && npm test ``` One caveat worth remembering: as soon as you introduce `stages:`, every job must live under a stage — you cannot mix a top-level `steps:` or `jobs:` with `stages:` in the same file. ## Where `pool` sits Because the job is what gets an agent, `pool` is fundamentally a job-level property. You may write it once at the root or on a stage as a default, but it is inherited *down to each job*, and a job-level `pool` wins over the inherited one. A stage with two jobs can perfectly well run one on a Linux image and the other on Windows. ## Why interviewers ask The question separates people who have written a pipeline from people who have only read one. The three-level vocabulary is easy to recite; the consequence — that the job boundary is a machine boundary, so state must be published across it — is what actually shows up as a broken pipeline on someone's first week.