Upstream sources play a key role in a professional approach towards Package Management. MyGet gives you the option to specify one or more upstream sources for a package feed. Even though this feature has been available on MyGet for years now, we feel it upstream sources deserve a place in the spotlight once: they enable various scenarios that are impossible on any other package management service, and above all: they are a huge facilitator for a smooth and automated development workflow (and thus developer happiness :-)).
In this post:
- Why upstream sources?
- Supported upstream sources
Why use upstream sources?
- Upstream sources make it very easy to pull in packages from other package sources onto your downstream MyGet feeds.
- You can also target these upstream sources to push packages upstream from your MyGet feeds.
- Any configured upstream source on your MyGet feed will be made available to you in MyGet Build Services, without having to commit any secrets such as credentials or API keys in your source repository. If you're using NuGet: no need to create a nuget.config file!
If you are confused about the usage of "upstream" and "downstream" in the context of package sources, we've got a little poetic explanation for you, which may already help you visualize the relationship between package consumers, your MyGet feeds, and your feed's upstream sources.
Consider the direction in which packages are flowing from a given package source to an ocean of consumers.Your package may have dependencies "upstream", to packages on another feed. From the point of view of those dependencies, the depending package is located "downstream". When a user consumes the downstream package, it will also fetch the upstream dependencies.The consumer, however, is only allowed to fetch or query those upstream packages if the feed being queried (downstream) is also configured to proxy (or mirror) the upstream package source.
<h2>Supported upstream sources</h2>
By default, MyGet feeds have the public, central repositories configured for each package type. This includes:
- NuGet: https://www.nuget.org/api/v2
- Bower: https://bower.herokuapp.com
- npm: http://registry.npmjs.org
- Maven: https://repo1.maven.org/maven2
To configure an additional upstream source for your MyGet feed, navigate to Feed Settings > Upstream Sources. Then click Add Upstream Source and select the package source type you want to add.
A dialog will prompt your for upstream source information and will also expose a few common presets for you to take advantage of. Did you know we even support Dropbox?!
Upstream Source Credentials
If you have any access privileges to other MyGet feeds, you will see those in the MyGet Feeds presets, so you can easily build a chain of package sources to facilitate a package promotion flow.
If you select a private MyGet feed you have access to as an upstream source, there's no need to provide credentials to be able to restore packages from it on MyGet Build Services. MyGet will impersonate your user account when authenticating against that upstream source.
For any non-MyGet upstream source that requires authentication to pull packages, you'll have to provide username and password to be used during Basic Authentication.
In the opposite direction, in order to push packages from your downstream MyGet feed to the upstream source, you may need to configure a (scoped) API key or access token.
Package Source Filtering
When the upstream source is a v2 NuGet feed, you may configure additional OData filtering. Filtering is based on the OData v3 Filtering System. Valid filters are similar to
Id eq 'jQuery' or
IsLatestVersion eq true and Id ne 'Foo'.
Adding a package from an upstream source
You can easily add packages to your MyGet feed originating from an upstream source, such as nuget.org, nmpjs.org, etc. This is using the feed's configured upstream sources under the hood. If you want to add a package from another feed onto your MyGet feed, the other feed needs to be configured as an upstream source to that feed.
Adding a package from an upstream source can happen in three ways: manually, by reference (proxying), or by value (mirroring).
- Manually: you can add packages from an upstream source to your feed manually by using the Add Package button you will find under your feed's Packages page.
Select From Feed in the dialog that prompts.
- Proxying: the package metadata is copied to the MyGet feed, the package itself remains hosted on the upstream source. When querying the package, we call the upstream source to fetch the package.
- Mirroring: the package metadata and the package itself are copied onto the MyGet feed. When querying the package, we server the package directly and don't use the upstream source. Mirroring of a package version happens upon the first request for that given package version.
Configuring upstream sources on your MyGet feed unlocks quite a few integration scenarios and automation opportunities!
Proxy packages from an upstream source
You can configure an upstream source to proxy upstream packages through your MyGet feed to your feed consumers. Proxying makes it easy to have a single MyGet feed aggregate packages from multiple sources. Package consumers need only to configure a single MyGet feed, and all packages available on upstream, proxied package sources will become available to them.
- upstream packages do not count against your MyGet storage quota
- authentication against upstream, private MyGet sources happens automatically (see Upstream Source Credentials)
- especially for NuGet: no longer subject to chatty clients reaching out to all configured feeds during dependency resolution (MyGet can be smarter server-side)
- every package request will incur additional latency as opposed to storing the package onto the MyGet feed
The following diagram illustrates the effects of upstream source proxying.
To enable upstream source proxying, you must tick the check-mark next to Make all upstream packages available in clients.
Mirror packages from an upstream source
You can configure an upstream source to mirror upstream packages onto your MyGet feed. This configuration is similar to package proxying, but takes it one step further.
Whenever someone requests a particular package from your MyGet feed for the first time, MyGet will query the upstream source and copy the package onto the MyGet feed.
- No additional latency (except for the first hit that triggers the package mirroring)
- Protected against upstream source availability issues
- Protected against upstream package removal
- Authentication against upstream, private MyGet feeds happens automatically (see Upstream Source Credentials)
- Faster builds!
- Mirrored packages count towards your MyGet storage quota (a classic storage versus speed trade-off, you can always upgrade your subscription or request a quote!)
The following diagram illustrates the effects of upstream source mirroring.
To enable upstream source mirroring, you must tick the check-mark next to Automatically add downloaded upstream packages to the current feed (mirror).
Optionally, you can also tick the third check-mark to indicate that any package found upstream is to be considered a package dependency (and should not be consumed directly). This will hide those packages from search results, whilst still allowing you to restore them.
Once upstream source mirroring is enabled, we can consume our MyGet feed from Visual Studio which will also list upstream packages. For example, the example acmecompany feed only lists one package:
When searching in Visual Studio, we do see packages that originate from upstream sources:
After installing this package, our feed now automatically contains a copy of the jQuery package:
From now on, the package is available from our MyGet feed directly, without having to explicitly add it manually from the upstream source.
Using a MyGet feed as a staging area (before pushing upstream)
Many development teams are using some kind of package promotion workflow: pushing a package from one feed to another based on quality gates, target audience, or any other criteria. This is very typical scenario for which upstream sources are essential.
Of course, all of this can happen in an automated fashion using package manager client. However, as promoting a package typically involves some kind of human intervention (e.g. release manager approval), we've also made it a first-class feature in the MyGet web site.
Simply pick the package version you want to promote from the package details page, and hit the Push button to initiate the package promotion flow.
A dialog will provide you with additional options. MyGet is also smart enough to detect any package dependencies you might want to push along in one go as part of this package promotion flow.
At this point, you can still make a few metadata changes before pushing upstream. This dialog allows you to:
- modify or remove the prerelease label of the upstream package version. This allows you to e.g. drop the prerelease label to release a package without rebuilding/repackaging.
- add release notes to be included in the package metadata. MyGet will even support release notes written in markdown and render them properly on the web site!
- modify or remove the SemVer2 build metadata part of the upstream package version
- exclude any detected dependencies or satellite packages from the push action
- apply source labeling if the package was built using MyGet Build Services. When enabled, MyGet will find the build from which the package originated and will add a label to the source control revision it was built from.
To edit a package's metadata, simply click the Edit button next to it and make the modifications. To apply a given modification to all packages in the dialog, hit the rain drop button next to the editable field.
Using upstream sources on MyGet Build Services
Upstream sources for a feed are also available during build. This can be useful in the following scenarios:
- An additional upstream source is needed during build. MyGet will make the upstream source available during build if it has been added to the feed's upstream sources.
- If you have a private feed requiring authentication but do not wish to add credentials to source control, credentials can be added to the feed's upstream source. These credentials will be available during build and allow you to consume a protected feed with ease.
- The API key for an upstream source is also made available during the build process. This means during a build, you can call into
nuget.exe pushand push packages to configured upstream sources.
- If you want to make use of
nuget.exe pushin a build script without having to specify the
-Sourceparameter. This requires a default upstream source to be defined.
Setting default upstream sources to be used on MyGet Build Services
NuGet.config file on our build agents is configured using NuGet's defaults, enriched with all NuGet upstream sources configured for your MyGet feed. Based on these defaults, the following conventions are active:
- The default upstream source is set to
(Aggregate Source), meaning all feeds will be queried for packages in the order defined in the feed's upstream sources.
- The default push source (when using
nuget pushwithout the
-Sourceparameter) is NuGet.org.
Both of these conventions can be overridden by editing the build source configuration.
Auto updating packages
MyGet feeds can automatically fetch package updates made available through the upstream sources.
When adding or editing a upstream source, we can enable this behaviour per package source, as well as an interval when MyGet should check for updates.
The following options are available:
- E-mail me when package updates are available: Sends an e-mail to the specified recipient(s) when package updates are available on the upstream source.
- Include prerelease versions: By default, MyGet will only consider stable packages. When enabled, we will also check pre-release packages from the upstream source.
- Automatically update packages to their latest versions: Enables the behavior of automatically updating packages from the upstream source.
- Update interval: Depending on your subscription plan, we can specify how often MyGet should check for updates (up to every 30 minutes on a Professional subscription)