Edit This Page

This tutorial takes a small class library from dotnet pack to a package in your Repsy Open Source NuGet repository, restores it in a second project, and explains the rules Repsy applies to a push and what each refusal looks like. It complements Publishing a NuGet Package and Installing a NuGet Package, which show the same setup in short.

Prerequisites

• A NuGet repository on your Repsy Open Source instance, see Creating a Private NuGet Repository. The examples use the address of its service index, https://<your-repsy-host>/<repo-name>/v3/index.json. There is no username in the address, and https://<your-repsy-host> stands for the address of the package protocol port of your instance, for example http://localhost:9090 for a local start.
• The .NET SDK. The commands were checked with the .NET SDK 10.0.401, and the notes on older SDKs with 8.0.425.
• A credential: your username and password, or a deploy token. A deploy token needs the Read/Write access type to push, and a Read Only token is enough to restore. With a deploy token, the username can be any non-empty value.

dotnet new classlib -n Example.Library
cd Example.Library

<PropertyGroup>
  <PackageId>Example.Library</PackageId>
  <Version>1.0.0</Version>
  <Authors>Your Name</Authors>
  <Description>An example package.</Description>
</PropertyGroup>

dotnet pack --configuration Release

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="repsy" value="https://<your-repsy-host>/<repo-name>/v3/index.json" />
  </packageSources>
</configuration>

dotnet nuget add source https://<your-repsy-host>/<repo-name>/v3/index.json --name repsy --configfile nuget.config

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSourceCredentials>
    <repsy>
      <add key="Username" value="MY REPSY USERNAME" />
      <add key="ClearTextPassword" value="MY REPSY PASSWORD OR DEPLOY TOKEN" />
    </repsy>
  </packageSourceCredentials>
</configuration>

dotnet nuget add source https://<your-repsy-host>/<repo-name>/v3/index.json --name repsy --username <username> --password <password-or-token> --store-password-in-clear-text

dotnet nuget push bin/Release/Example.Library.1.0.0.nupkg --source repsy --api-key <deploy-token>

Pushing Example.Library.1.0.0.nupkg to 'https://<your-repsy-host>/<repo-name>/v3/package'...
  PUT https://<your-repsy-host>/<repo-name>/v3/package/
  Created https://<your-repsy-host>/<repo-name>/v3/package/ 143ms
Your package was pushed.

dotnet package search Example.Library --source repsy

curl -u <username>:<password-or-token> https://<your-repsy-host>/<repo-name>/v3/package/example.library/index.json

{"versions":["1.0.0"]}

dotnet new console -n Example.App
cd Example.App
# copy the nuget.config from above into this directory
dotnet add package Example.Library --version 1.0.0

<ItemGroup>
  <PackageReference Include="Example.Library" Version="1.0.0" />
</ItemGroup>

Using Repsy Next to nuget.org

Repsy Open Source does not proxy or mirror nuget.org, so a repository only holds what you pushed. A project that needs both keeps both sources. Without a mapping, NuGet considers every source for every package. Package source mapping makes the choice explicit: it says which source a package id may come from.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="repsy" value="https://<your-repsy-host>/<repo-name>/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="repsy">
      <package pattern="Example.*" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

With this file, Example.* packages come only from Repsy and everything else comes from nuget.org. Use a prefix that is yours for your own package ids.

HTTP and HTTPS

NuGet only accepts a source over HTTPS unless you allow plain HTTP for that source, so a local instance at http://localhost:9090 needs one more step. Without it, the .NET SDK 10 stops the restore with NU1302 and the push with You are running the 'push' operation with an 'HTTP' source, and the .NET SDK 8 only warns with NU1803.

Allow HTTP for the source with the allowInsecureConnections attribute:

<add key="repsy" value="http://localhost:9090/<repo-name>/v3/index.json" allowInsecureConnections="true" />

dotnet nuget add source writes the attribute when you pass --allow-insecure-connections, and dotnet nuget push takes the same option for a source you name by its address. Anything you configure that way sends the credentials in clear text over the network, so use it for a local trial and serve a shared instance over HTTPS, see Enabling HTTPS.

The client does not use the address you configured for the rest of its requests. It reads the service index and follows the addresses in it, and Repsy builds them from the address the request came in on: the scheme, the host and the port. Behind a reverse proxy, the proxy has to send the forwarded headers, or the client is sent to the internal address of Repsy. See Running Behind a Reverse Proxy.

Rules Repsy Applies to a Push

A refused push changes nothing in the repository: nothing is stored and no version appears. dotnet prints only the HTTP status, for example error: Response status code does not indicate success: 409.. The body of the response carries Repsy’s message as {"errors":[{"message":"..."}]}; the messages are in the list below. A push has to pass these checks:

1. Credentials. A user account can push to every repository of the instance. A deploy token can push to its own repository when its access type is Read/Write. A Read Only token, a wrong or expired token, a token of another repository, an account password used as the API key and missing credentials are all refused with 401. Nobody can push anonymously, not even to a public repository.
2. The package. The request has to be a multipart upload, as dotnet nuget push sends it, of a .nupkg file with a .nuspec at its root. Otherwise Repsy answers 400: Content-Type must be multipart/form-data, or The uploaded file is not a valid NuGet package (.nuspec not found)., or The .nuspec in the package is not well-formed XML.
3. The package id. It starts with a letter or a digit, has at most 100 characters and only letters, digits, ., _ and -. Otherwise: 400, Invalid NuGet package id.
4. The version. It has up to four numeric parts, optionally a pre-release label after a hyphen and build metadata after a +, and at most 64 characters, for example 1.2.3, 1.2.3.4, 1.2.3-beta.1, 1.2.3+build5. Otherwise: 400, Invalid NuGet version format. or NuGet version is longer than 64 characters.
5. Version Allowance. The Version Allowance setting of the repository can restrict it to pre-release versions or to stable versions. A version with a hyphen in it, such as 1.0.0-rc.1, is a pre-release version, and every other version is stable. A refused version is answered with 422: Pre-release packages are not allowed in this repository. or Release packages are not allowed in this repository. This check comes before the next one, so pushing a version that exists again to a repository that does not take its kind is 422, never 409.
6. Package Override. See Pushing a Version Again.
7. The size limit. A push of more than 500 MB is refused with 413. An administrator can change the limit with the MULTIPART_MAX_FILE_SIZE and MULTIPART_MAX_REQUEST_SIZE environment variables, see Configuration Reference.

Repsy stores the package id in lower case and the version in a normalized form, and the address of the package uses both. The normalized version is lower case, has no build metadata and keeps its pre-release label; it has at least three numeric parts, and a fourth part that is 0 is dropped:

Build metadata does not count: 1.4.0+a and 1.4.0+b are the same version, and the second push is a push of a version that exists. NuGet clients ignore the case of package ids and versions, so they are not affected.

Pushing a Version Again

Whether you can push a version that already exists is decided by the Package Override setting of the repository. An administrator changes it in the repository settings.

With Deny, dotnet nuget push fails with error: Response status code does not indicate success: 409. and exit code 1. Add --skip-duplicate to a push that may run twice, for example a CI job that was restarted: the client then reports Package '...' already exists at feed '...' and exits with 0.

Publish a new version instead of replacing an old one whenever you can. A client that has already restored a version keeps the copy it has in its global packages folder and does not notice a replaced package; dotnet nuget locals all --clear clears that cache.

Troubleshooting

Failed requests count towards the login throttle of Repsy. See Authenticating from CI if a job that retries with wrong credentials gets 429.

The next step is to unlist a version you do not want to be found any more, or to run the same commands in a CI pipeline.

Installing a NuGet Package Unlisting and Relisting NuGet Packages

Was this page helpful?

Yes No