Configure upstream behavior
TFS 2017
Upstream sources enables developers to use a single feed to publish and consume packages from Artifact feeds and public registries such as NuGet.org or npmjs.com. To set up upstream sources for your feed, check the box to include packages from common public sources. This will allow your feed to use packages from the common public registries.
Previously, Artifact feeds combined a list of available package versions from the feed and all the upstream sources.
Upstream behavior is a feature that enables developers to choose if they want to consume externally-sourced package versions. Upstream behavior dictates which packages will be made available from the public registries for individual packages.
When the upstream behavior is enabled, when a package is published to your Azure Artifacts feed, any version from the public registry will be blocked and not made available for download.
This approach provides another layer of security by blocking the exposure to malicious packages that may infiltrate the public registries.
Users will still be able to toggle off the upstream behavior setting and consume packages from the public registries if they choose to do so.
Note
The new behavior won't affect any package versions that are already in use. Those are stored in the feed's @local view.
Applicable scenarios
The next section shows a few common scenarios where the upstream behavior is triggered to block externally sourced package versions along with few other cases where no blockage to the public packages is needed.
Public versions will be blocked
Private package version made public: in this scenario, a team has a private package that was made public. The upstream behavior in this case will be triggered to block any new public versions (untrusted packages).
Having both private and public packages: in this scenario, if a team already has both private and public packages, enabling the upstream behavior will result in blocking any new package versions from the public registry.
Public versions will not be blocked
All packages are private: if all existing packages are private and the team won't be consuming any public packages, the new upstream behavior will have no effect on the team's workflow in this scenario.
All packages are public: if all the packages consumed are public, whether it's from the public registry or any other open-source repositories, the new upstream behavior will have no effect on the team's workflow in this scenario.
Public package made private: if a public package is switched to a private package, the new upstream behavior will have no effect on the team's workflow in this scenario.
Allow external versions
Note
Only feed owners are allowed to configure the upstream behavior. See Feed permissions for more details.
To configure the new upstream behavior, select a package from within your feed then select the toggle button to Allow external sourced versions.
Allow external versions using the REST API
Aside from using the feed's user interface, you can also configure the upstream behavior using the Azure DevOps Services REST API. Select the appropriate tab and find the links to the REST API docs.
Allow external versions with PowerShell
To successfully execute the next steps in this section, you will need to create a personal access token with packaging Read, write, & manage permissions. See Use personal access tokens to learn how to create your personal access token.
In an elevated PowerShell command prompt window, run the following command to create an environment variable for your personal access token.
$env:PATVAR = "YOUR_PAT_GOES_HERE"
The following commands will convert your personal access token to baser64 encoded string and construct the HTTP request header.
$token = [Convert]::ToBase64String(([Text.Encoding]::ASCII.GetBytes("username:$env:PatVar")))
$headers = @{
Authorization = "Basic $token"
}
Invoking the REST method requires an endpoint url. Enter your OrganizationName, ProjectName, FeedName, Protocol, and your PackageName to construct the $Url variable. (Project-scoped feed example: /pkgs.dev.azure.com/MyOrg/MyProject/_apis/packaging/feeds/MyFeed/nuget/packages/Myapp1.0.nupkg/upstreaming?api-version=6.1-preview.1)
- Project-scoped feed:
$url = "https://pkgs.dev.azure.com/{OrganizationName}/{ProjectName}/_apis/packaging/feeds/{FeedName}/{Protocol}/packages/{PackageName}/upstreaming?api-version=6.1-preview.1"
- Organization-scoped feed:
$url = "https://pkgs.dev.azure.com/{OrganizationName}/_apis/packaging/feeds/{FeedName}/{Protocol}/packages/{PackageName}/upstreaming?api-version=6.1-preview.1"
Now that we have both the header and the endpoint URL set up, we can start sending HTTP requests to get, set, and clear upstreaming for any specific package.
Get upstreaming behavior
Run the following command to retrieve the upstream behavior state of your package. $url and $headers are the same variables we used in the previous section.
Invoke-RestMethod -Uri $url -Headers $headers
Set upstreaming behavior
Run the following commands to allow externally sourced versions for your package. This will set versionsFromExternalUpstreams to AllowExternalVersions, and will use the $url and $headers variables to query the REST API.
$body = '{"versionsFromExternalUpstreams": "AllowExternalVersions"}'
Invoke-RestMethod -Uri $url -Headers $headers -Body $body -Method Patch -ContentType "application/json"
Clear upstreaming behavior
To clear the upstream behavior for your package, run the following commands to set versionsFromExternalUpstreams to Auto and query the REST API.
$body = '{"versionsFromExternalUpstreams": "Auto"}'
Invoke-RestMethod -Uri $url -Headers $headers -Body $body -Method Patch -ContentType "application/json"
Note
In some cases, configuring the upstream behavior can take time to propagate across the service. If your package is not available after updating the settings, please allow up to 3 hours for the new settings to take effect.