Azure DevOps (AZ-400)
Chapter 4 of 12 · Build and release pipelines · 35 practice questions

Package Management

What this chapter covers

  • Recommend package management tools including GitHub Packages registry and Azure Artifacts
  • Design and implement package feeds and views for local and upstream packages
  • Design and implement a dependency versioning strategy for code assets and packages, including Semantic Versioning (SemVer) and date-based (CalVer)
  • Design and implement a versioning strategy for pipeline artifacts

Almost every build both consumes packages (third-party and internal dependencies) and produces them (libraries, containers, deployable bundles). A package management strategy answers four questions: where do packages live, who can read and publish them, how do consumers get only trustworthy versions, and how are versions numbered so that consumers can reason about compatibility. AZ-400 tests all four, with most questions centred on Azure Artifacts feeds, views and upstream sources.

Why a private package manager?

  • Share code as binaries, not as copy-paste. Internal libraries are versioned, published once and consumed by many teams instead of being duplicated across repositories.
  • Single, governed entry point for open source. Upstream sources proxy public registries so every build resolves packages through one feed that you can audit, cache and restrict.
  • Resilience. Once an upstream package is saved into your feed it stays available even if the author unpublishes it or the public registry is down (the left-pad lesson).
  • Protection against dependency confusion. Controlling which versions may come from public registries for a package name that also exists internally blocks substitution attacks.
  • Immutability and traceability. A published version can never be overwritten; you know exactly which bits a build consumed.

Azure Artifacts

Azure Artifacts is the package service of Azure DevOps. It hosts NuGet, npm, Maven, Python (PyPI), Cargo (Rust) and Universal Packages in the same feed, and supports Gradle builds through the Maven protocol. Each organization gets 2 GiB of free storage; beyond that, storage is billed through the Azure subscription linked to the organization. Packages are immutable: once 1.4.0 is published you cannot republish different content as 1.4.0, even after deleting it (deleted versions sit in the feed Recycle Bin for 30 days and the version number stays reserved).

Azure Artifacts feeds, upstream sources and views
Figure 4.1. Azure Artifacts feeds, upstream sources and views

Feeds: project-scoped vs organization-scoped

A feed is a container for packages with its own permissions, views, upstream sources and retention settings. Feeds are created either inside a project or at organization level.

AspectProject-scoped feed (recommended)Organization-scoped feed
VisibilityInherits the project's visibilityAlways private to the organization
Default build identity<Project> Build Service (org)Project Collection Build Service
LifecycleDeleted together with the projectIndependent of any project
DiscoverabilityShown in that project's Artifacts hubShown in every project's feed list
Use whenDefault for new feeds; team/product-ownedLegacy or truly org-wide feed

Feed permissions (roles)

RoleCan do
Feed OwnerEverything: settings, views, upstreams, permissions, delete feed
Feed Publisher (Contributor)Publish, promote, deprecate/unlist, plus all reader rights
Feed and Upstream Reader (Collaborator)Read packages AND save new versions from upstreams
Feed ReaderRead/download packages already in the feed only

Pipelines authenticate as a build service identity: <Project> Build Service (<org>) when job authorization scope is limited to the current project (the default for new projects), or Project Collection Build Service (<org>) when the scope is the whole collection. To publish from a pipeline that identity needs Feed Publisher (Contributor). To restore a package that is not yet cached from an upstream it needs at least Feed and Upstream Reader (Collaborator) - a plain Feed Reader can only consume what is already saved.

Views: @Local, @Prerelease, @Release

A view is a read-only filter over a feed that shows only the package versions that have been promoted into it. Every feed starts with three views:

  • @Local - the default view. Contains every version published directly to the feed and every version saved from upstream sources. Consumers that point at the bare feed URL use @Local.
  • @Prerelease - versions that passed initial validation (for example integration tests).
  • @Release - versions certified for general consumption.

Views let one feed serve both producers and consumers: the producing team publishes every CI build into @Local, then a later stage (or a person) promotes the version to @Prerelease and then @Release. Consumers outside the team reference feed@Release and never see unvalidated builds. Promotion does not copy bits; it marks the existing immutable version as visible in the view, so the same package flows forward. Views can be renamed, you can add your own, view permissions can be set separately from the feed, and a view can be used as an upstream source for another feed.

text
<!-- nuget.config: consume only released versions of the shared feed -->
<configuration>
  <packageSources>
    <clear />
    <add key="contoso-release" value="https://pkgs.dev.azure.com/contoso/
      Platform/_packaging/core-libs@Release/nuget/v3/index.json" />
    <!-- (URL wrapped for print; keep it on one line in the real file) -->
  </packageSources>
</configuration>

Promotion can be done in the web UI, or automated with the Azure Artifacts REST API (a PATCH on the package version that adds a view), typically as the last step of a stage that ran integration tests against the package.

powershell
# Promote a NuGet package version to @Release via REST (pipeline OAuth token)
$org='contoso'; $project='Platform'; $feed='core-libs'
$pkg='Contoso.Core'; $ver='2.3.0'
$uri = "https://pkgs.dev.azure.com/$org/$project/_apis/packaging/feeds/$feed" +
       "/nuget/packages/$pkg/versions/$($ver)?api-version=7.1-preview.1"
$body = '{"views":{"op":"add","path":"/views/-","value":"Release"}}'
Invoke-RestMethod -Uri $uri -Method Patch -Body $body `
  -ContentType 'application/json' `
  -Headers @{ Authorization = "Bearer $env:SYSTEM_ACCESSTOKEN" }

Upstream sources

An upstream source lets a feed transparently fetch packages it does not hold yet. When a client restores Newtonsoft.Json 13.0.3 from your feed and the feed does not have it, Azure Artifacts searches its upstreams in the configured order, returns the first match and saves a copy into the feed (@Local). From then on the package is served from your feed, even if it is later removed from nuget.org.

Upstream typeExamples
Public registriesnuget.org, npmjs.com, PyPI, Maven Central, Google Maven, crates.io
More public registriesGradle Plugins, PowerShell Gallery
Another Azure Artifacts feedA feed or view (core-libs@Release); same org or same tenant
Not supportedUniversal Packages cannot use public registries as upstreams
  • One feed per consuming team or product, upstreaming to shared feeds, gives a single URL in nuget.config / .npmrc / pip.conf. Configuring several sources in every client defeats ordering and opens the door to dependency confusion.
  • Order matters. Put internal feeds and views first, public registries last.
  • Allow externally-sourced versions. By default, once a package name has been published locally to your feed, versions of that same name are no longer pulled from public upstreams. The per-package 'Allow external versions' setting deliberately relaxes this. This is the built-in defence against dependency confusion.
  • Saving from upstream requires the requesting identity to have Feed and Upstream Reader (Collaborator) or higher.
  • Upstream-sourced packages land in @Local; you can still promote them to a view, which is a common way to publish a curated, approved list of open-source packages.

Retention policies and storage

Feed settings expose two retention controls: maximum number of versions per package and days to keep recently downloaded packages. When a package exceeds the version limit, the oldest versions that have not been downloaded within the configured period are deleted. Versions promoted to a view are exempt from retention - another reason to promote real releases. Deleted versions go to the feed's Recycle Bin. Pipeline-run and pipeline-artifact retention is configured separately in project settings and is covered in the pipeline maintenance chapter.

Retention settings across the toolchain
Figure 4.2. Retention settings across the toolchain

Publishing and consuming from Azure Pipelines

Use the authenticate tasks (NuGetAuthenticate@1, npmAuthenticate@0, PipAuthenticate@1, TwineAuthenticate@1, MavenAuthenticate@0) so the native client picks up a short-lived token for the build identity, then run the native CLI. For a feed in another organization, give the authenticate task a service connection. Never commit PATs in config files.

yaml
# feedUrl = .../_packaging/core-libs/nuget/v3/index.json (set as a pipeline variable)
steps:
- task: NuGetAuthenticate@1
- script: dotnet restore src/Contoso.sln --configfile nuget.config
- script: >
    dotnet pack src/Contoso.Core -c Release
    -o $(Build.ArtifactStagingDirectory) -p:Version=$(packageVersion)
- script: >
    dotnet nuget push $(Build.ArtifactStagingDirectory)/*.nupkg
    --source $(feedUrl)
    --api-key AzureArtifacts
  displayName: Push to core-libs (@Local)
yaml
# npm: the repo's .npmrc points at the feed; npmAuthenticate injects credentials
steps:
- task: npmAuthenticate@0
  inputs:
    workingFile: .npmrc
- script: npm ci && npm run build && npm publish
  displayName: Build and publish npm package

Universal Packages

Universal Packages store any set of files (tools, binaries, ML models, zipped deployment bundles) as a named, versioned package. Names must be lowercase, versions must be SemVer (1.2.3, 1.2.3-beta.1), and a single package can be very large (up to 4 TiB). Content is deduplicated, so uploading a slightly changed multi-GB bundle is fast. Use the UniversalPackages@0 task or the Azure CLI with the azure-devops extension.

bash
az artifacts universal publish --organization https://dev.azure.com/contoso \
  --project Platform --scope project --feed tools \
  --name terraform-modules --version 3.1.0 \
  --path ./modules --description "Approved TF modules"

az artifacts universal download --organization https://dev.azure.com/contoso \
  --project Platform --scope project --feed tools \
  --name terraform-modules --version '3.*' --path ./modules
yaml
- task: UniversalPackages@0
  inputs:
    command: publish
    publishDirectory: $(Build.ArtifactStagingDirectory)/bundle
    feedsToUsePublish: internal
    vstsFeedPublish: Platform/tools
    vstsFeedPackagePublish: web-bundle
    versionOption: patch          # auto-increment patch, or 'custom'
    packagePublishDescription: Build $(Build.BuildNumber)

GitHub Packages

GitHub Packages is GitHub's package registry. It supports the Container registry (ghcr.io), npm, Maven, Gradle, NuGet and RubyGems. Python (PyPI) is not a GitHub Packages registry type, and there is no generic 'universal' type. Packages belong to a user or organization and can be linked to a repository; the Container, npm, NuGet and RubyGems registries support granular permissions (inherit access from the linked repository or set it per package), while the Maven and Gradle registries use only repository-scoped permissions.

  • Authentication in Actions: use GITHUB_TOKEN with permissions: packages: write to publish packages linked to the workflow's repository. Use a PAT (classic) with write:packages/read:packages only when you must cross boundaries that granular permissions cannot grant.
  • Billing: public packages are free; private packages consume the plan's included storage and data transfer (transfer from Actions using GITHUB_TOKEN is free).
  • No upstream proxying of public registries and no views/promotion: if you need a curated, cached proxy of nuget.org/npmjs with promotion stages, Azure Artifacts is the better fit.
  • Container images: ghcr.io/OWNER/IMAGE:tag; integrates with Dependabot, code scanning and build provenance attestations (actions/attest-build-provenance).
yaml
name: publish-npm
on:
  release:
    types: [published]
permissions:
  contents: read
  packages: write
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: https://npm.pkg.github.com
          scope: '@contoso'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
yaml
  image:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ghcr.io/contoso/orders-api:${{ github.sha }}

Choosing a package management tool

RequirementBest fit
Proxy and cache nuget.org/npmjs/PyPI/Maven Central behind one URLAzure Artifacts upstreams
Promotion stages (prerelease -> release) on one feedAzure Artifacts views
Python packages in a private registryAzure Artifacts (GitHub Packages has no PyPI)
Arbitrary large binaries / tool bundles with versionsAzure Artifacts Universal Packages
Code, packages and CI all in GitHub, GITHUB_TOKEN authGitHub Packages
OCI images for AKS/App Service, geo-replication, private linkAzure Container Registry
Container images next to GitHub source with simple authGitHub Container registry (ghcr.io)
Packages for anonymous public consumptionPublic registry or public GitHub package

Dependency versioning strategy

Semantic Versioning (SemVer 2.0)

Semantic and calendar versioning
Figure 4.3. Semantic and calendar versioning

SemVer encodes compatibility in the number MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]:

  • MAJOR - incompatible (breaking) API change. Resets minor and patch to 0.
  • MINOR - backward-compatible new functionality. Resets patch to 0.
  • PATCH - backward-compatible bug fix.
  • Pre-release -alpha.1, -beta.3, -rc.1 - lower precedence than the release: 2.0.0-rc.1 < 2.0.0. Identifiers compare left to right; numeric identifiers numerically (beta.2 < beta.11), alphanumeric ones lexically (alpha < beta < rc).
  • Build metadata +20261007.sha.3f2a1c - ignored for precedence; two versions that differ only in metadata have equal precedence.
  • 0.y.z - initial development; anything may change at any time.

Consumers express acceptable ranges: npm ^1.4.0 (>=1.4.0 <2.0.0) and ~1.4.0 (>=1.4.0 <1.5.0); NuGet [1.4.0,2.0.0); pip ~=1.4. Lock files (package-lock.json, packages.lock.json with locked-mode restore, poetry.lock) pin the resolved graph so builds are reproducible, and Dependabot or Renovate propose controlled upgrades.

Calendar Versioning (CalVer)

CalVer derives the version from the release date, e.g. YYYY.MM.DD, YY.0M (Ubuntu 24.04), or YYYY.MM.MICRO. It suits products released on a schedule, applications and services (where 'breaking API' means little to end users), and content that ages (rule sets, data packages). It communicates age and support windows, not compatibility. Libraries consumed by other code should normally prefer SemVer because consumers need a compatibility signal.

AspectSemVerCalVer
CommunicatesCompatibility / breaking changesRelease date / age
Typical usersLibraries, SDKs, APIs, NuGet/npm packagesApps, OS releases, schedules
Example3.2.1, 4.0.0-rc.22026.10.0, 26.10.1
RiskTeams avoid bumping MAJOR ('0.x forever')No signal about breaking changes

Versioning pipeline artifacts

Run (build) numbers in Azure Pipelines

The run number (Build.BuildNumber) comes from the top-level name: property. Tokens such as $(Date:yyyyMMdd), $(Rev:r) (a counter that restarts at 1 whenever the rest of the formatted number changes), $(SourceBranchName), $(Build.DefinitionName) and your own variables can be combined. Without name: the default is $(Date:yyyyMMdd).$(Rev:r). For SemVer, build the number from variables plus a counter() expression, which keeps an independent, persistent counter per seed (prefix) value.

yaml
# Version 3.4.<patch>; patch auto-increments and restarts when major/minor change
variables:
  major: 3
  minor: 4
  patch: $[counter(format('{0}.{1}', variables['major'], variables['minor']), 0)]
  ${{ if eq(variables['Build.SourceBranch'], 'refs/heads/main') }}:
    packageVersion: $(major).$(minor).$(patch)
  ${{ else }}:
    packageVersion: $(major).$(minor).$(patch)-ci.$(Build.BuildId)

name: $(major).$(minor).$(patch)

steps:
- script: echo "##vso[build.updatebuildnumber]$(packageVersion)"
  displayName: Set run number to package version

##vso[build.updatebuildnumber] changes the run number at runtime; ##vso[build.addbuildtag]release tags the run, and tags can be used by pipeline-resource triggers and filters.

GitVersion

GitVersion calculates a SemVer version from Git history: tags (v2.3.0), branch names (release/2.4 -> 2.4.0-beta.N), merges and +semver: major|minor|patch|none commit-message bumps. It supports GitFlow, GitHub Flow and mainline (trunk-based) modes configured in GitVersion.yml. The GitTools extension provides gitversion/setup and gitversion/execute tasks for Azure Pipelines and equivalent GitHub actions. It needs the full history: set fetchDepth: 0 (Azure Pipelines) or fetch-depth: 0 (actions/checkout), because both default to shallow clones for new pipelines and workflows. Nerdbank.GitVersioning (version.json + commit height) is a popular alternative.

yaml
steps:
- checkout: self
  fetchDepth: 0               # GitVersion needs full history and tags
- task: gitversion/setup@3
  inputs:
    versionSpec: '6.x'
- task: gitversion/execute@3
  name: version
- script: dotnet pack -p:Version=$(version.SemVer) -o $(Build.ArtifactStagingDirectory)
- script: echo "##vso[build.updatebuildnumber]$(version.FullSemVer)"
yaml
# GitHub Actions equivalent
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: gittools/actions/gitversion/setup@v3
        with:
          versionSpec: '6.x'
      - id: gv
        uses: gittools/actions/gitversion/execute@v3
      - run: echo "Version ${{ steps.gv.outputs.semVer }}"

Pipeline artifacts vs build artifacts

AspectPipeline artifacts (recommended)Build artifacts (older)
TasksPublishPipelineArtifact@1 / DownloadPipelineArtifact@2PublishBuildArtifacts@1 / DownloadBuildArtifacts@1
YAML shortcut- publish: and - download: stepsNone
PerformanceDedup + parallel upload; much faster for big outputsSlower
StorageAzure DevOps, kept with the runAzure DevOps or a UNC file share
Typical useAll new YAML pipelinesExisting classic pipelines, file-share drops
yaml
stages:
- stage: Build
  jobs:
  - job: build
    steps:
    - script: dotnet publish src/Web -c Release -o $(Build.ArtifactStagingDirectory)/web
    - publish: $(Build.ArtifactStagingDirectory)/web
      artifact: web
- stage: Deploy
  dependsOn: Build
  jobs:
  - deployment: web
    environment: test
    strategy:
      runOnce:
        deploy:
          steps:
          # deployment jobs auto-download this run's pipeline artifacts into
          # $(Pipeline.Workspace)/<artifact>; use '- download: none' to opt out
          - script: ls $(Pipeline.Workspace)/web
  • In GitHub Actions use actions/upload-artifact@v4 / actions/download-artifact@v4. In v4 artifacts are immutable and names must be unique within a run; default retention is 90 days (configurable at repo/org level and per upload with retention-days).
  • Version the artifact once, at build time, and promote the same artifact through every environment ('build once, deploy many'). Never rebuild per environment.
  • Stamp the version into the binary (assembly version, package.json, image label org.opencontainers.image.version) and tag the commit (git tag v3.4.17) so every artifact traces back to source.
  • Container images: use immutable tags (commit SHA or SemVer) for deployments, optionally a moving tag such as stable for humans; deploy by digest for maximum certainty.

Use case: 'The vanishing package'

Use case comic: governing packages
Figure 4.1. Use case comic: governing packages

Situation. A small open-source package that dozens of services depend on is removed from the public registry. Every build fails within an hour, and nobody knows which versions were in use.

StepPracticeFeature used
1Use one governed source for all packagesAzure Artifacts feed (or GitHub Packages)
2Proxy the public registriesUpstream sources: nuget.org, npmjs, PyPI, Maven Central
3Keep a copy of everything you consumePackages saved to the feed on first use (@Local)
4Share only validated versionsPromote to the @Prerelease / @Release views