In Azure Artifacts, what does an upstream source on a feed do the first time a build restores a package the feed does not already hold?

## The problem upstreams solve Without upstream sources a build has two package sources configured: your private feed for internal libraries and the public registry for everything else. That is two URLs to keep in sync across every repo and agent, two sets of network egress rules, and — critically — a client that is free to choose between them by version number rather than by trust. Upstream sources collapse that into one endpoint. ## What happens on a miss Configure `nuget.org` (or `npmjs.com`, Maven Central, PyPI) as an upstream on your feed, point the client only at the feed, and then: 1. The client asks the feed for `Newtonsoft.Json 13.0.3`. 2. Azure Artifacts checks the feed's own contents first — the `@local` view, which holds everything published to the feed plus everything previously saved from upstream. 3. Not found locally, so it walks the configured upstream sources **in order**. 4. The first upstream that has that exact version supplies it. Azure Artifacts streams it to the client **and saves a copy into the feed**. 5. Every later request for that version is answered from the feed. Upstream is not contacted again for it. This is a save, not a transient cache with an expiry you have to reason about. Once the version is in the feed it is a first-class package there: it appears in the feed's package list, it is covered by feed permissions, and it is subject to the feed's retention policy. ## Who is allowed to trigger a save Saving from upstream is a privileged act, because it puts new bytes into a registry your whole organization consumes. The feed roles gate it: - **Reader** — can download packages already in the feed, but a request for a version that is not there will not be saved on their behalf. - **Collaborator** — can cause packages to be saved from upstream, but cannot publish packages of their own. - **Contributor** and **Owner** — can do both. Collaborator exists precisely so you can let CI (or most engineers) hydrate the feed from public registries without granting the right to publish under an internal package name. In CI this matters because the build identity's role decides whether a fresh dependency restores or fails. ## What upstreams can point at Beyond the big public registries, an upstream can be **another Azure Artifacts feed**. That is how a layered setup works: a curated "golden" feed with vetted packages, and team feeds that take the golden feed as their upstream. Consuming a feed that lives in a *different organization* is done through one of its **views** rather than the raw feed, which is one of the main practical reasons views exist at all. ## What it buys you - **One URL.** Client config names the feed and nothing else. There is no second source for a client to prefer. - **Continuity.** If a package is unpublished, yanked, or the upstream registry has an outage, the versions you already consumed are still in your feed. Teams that lived through a popular package being unpublished remember this one. - **An audit point.** Everything the organization has ever pulled from a public registry is enumerable in one place, which is what a supply-chain review actually needs. - **Fewer egress paths.** Build agents talk to one host, which simplifies proxy and firewall rules on locked-down networks. ## What it does not buy you An upstream source is not a scanner and not an approval gate. Azure Artifacts saves what the build asked for; it does not judge whether the package is safe. If you want vetting, you need a curated feed that engineers consume and a separate, more permissive feed where new packages arrive — or a scanning step in the pipeline. Nor is it a mirror: nothing is pre-fetched. The feed only ever holds versions someone actually asked for, which is usually what you want but does mean a brand-new dependency still needs a live upstream at first restore. ## The failure modes worth naming - A pipeline restoring a *new* dependency fails while the same restore works locally: the build identity has Reader, not Collaborator, so nothing can be saved on its behalf. - An air-gapped or proxy-restricted agent fails on first restore of a package but succeeds afterwards, because only the miss path needs upstream connectivity. - Upstream ordering surprises: with two upstreams that both carry a name, the first one in the list that has the requested version wins, so the order in feed settings is a trust decision, not cosmetics.