NuGet .NET Package Manager
Problem to solve
.NET developers need a mechanism to create, share, and consume packages that contain compiled code and other content in projects that consume these packages. For .NET, the Microsoft-supported mechanism for sharing code is NuGet, which defines how packages for .NET are created, hosted, and consumed, and provides the tools for each of those roles.
By integrating with NuGet, GitLab will provide a centralized location to store and view those packages, in the same place as their source code and pipelines.
This issue will contribute to the vision of the GitLab Package stage to provide a single interface for managing dependencies, registries, and package repositories.
Intended users
Proposal
Provide support for users coding in .NET by integrating with NuGet and allowing developers to publish, share and consume .NET packages alongside their source code and CI/CD pipelines.
- We must allow, and provide documentation for, configuring the NuGet client to add GitLab to the remote list.
- We must allow the user to authenticate with their personal access token
- Developers need the ability to create and upload packages to the GitLab remote
- All users (Reporter and up) need the ability to view their packages
As an MVC, we plan to limit the scope in several ways. First, we will focus first on allowing users to push dependencies to their project and allow for pulling dependencies at the Instance level, similar to how we implemented Maven and Conan. Based on customer feedback, instance level is the top priority. We can also limit the scope by limiting authentication to personal access tokens and create a separate issue for supporting CI_JOB_TOKEN
.
Further details
User stories (MVC ONLY)
Administrator
- I as an administrator of GitLab, need the ability to enable/disable the NuGet Repository, so that I can ensure the developers in my organization have access to the features that they are supposed to.
- I as an administrator of Gitlab, need the ability to configure object storage for the GitLab Package Registry, including the NuGet Repository, so that I can optimize how my organization utilizes storage.
Developer
- I as a developer, need the ability to configure NuGet to point to GitLab as a remote repository, so that I can push, pull and view my NuGet Packages with GitLab.
- I as a developer, need the ability to setup authentication between GitLab and NuGet using my personal access token, so that I can push and pull packages to the GitLab NuGet Repository.
- I as a developer, need the ability to run NuGet primary commands from the NuGet CLI to push, pull and update NuGet packages in the GitLab NuGet Repository at the instance and project level.
- I as a developer, need the ability to view basic meta data about packages from within the GitLab UI, so that I can verify package info and ensure my project is using the correct dependencies.
- I as a developer need the ability to view meta data from the .nuspec file associated with a package, so that I can understand how a package was built, by whom and when.
- I as a developer, need the ability to delete packages from within the GitLab UI, so that I can remove old packages and ensure they are not accidentally used in my project.
Reporter
- I as a project-stakeholder need the ability to view and pull packages from the NuGet Repository, so that I can view, inspect and download NuGet packages.
NuGet Commands (MVC)
Configuration and Authentication
-
nuget config
: Gets or sets NuGet configuration values. The user will configure NuGet based on GitLab documentation -
nuget setapikey
: Saves an API key for a given package source when that package source requires a key for access. The user will use their GitLab personal access token for authentication.
Create, publish and consume
-
nuget pack
: Creates a NuGet package from a .nuspec or project file. When running on Mono, creating a package from a project file is not supported. -
nuget push
: Publishes a package to a package source. -
nuget list
: Displays packages from a given source. -
nuget delete
: Removes or unlists a package from a package source.
NuGet Commands (Beyond the MVC)
-
nuget spec
: Generates a .nuspec file, using tokens if generating the file from a Visual Studio project. -
nuget update
: Updates a project's packages to the latest available versions. Not supported when running on Mono. -
nuget restore
: Restores all packages referenced by the package management format in use. When running on Mono, restoring packages using the PackageReference format is not supported.
User Interface
Package Information
This data will populate /packages
Priority | Data Point |
---|---|
P1 | Name |
P1 | Version |
P1 | Type (NuGet) |
P1 | Created date |
Package Info (expanded)
This data will populate the top portion of /packages/<PACKAGE_ID>
Priority | Data Point |
---|---|
P1 | Name |
P1 | Repository Path |
P1 | Module ID |
P1 | Deployed by |
P1 | Size |
P1 | Created date |
P1 | Last updated date |
P2 | Licenses |
P2 | Downloads |
P2 | Last Downloaded |
P3 | Remote Downloads |
NuPkg Info
We will utilize the UI pattern from our Conan implementation to include additional meta data section for NuGet packages. The below info will be included in an expandable table titled NuPkg Info
Priority | Data Point |
---|---|
P1 | ID |
P1 | Title |
P1 | Version |
P1 | Authors |
P1 | Owners |
P1 | License URL |
P1 | Dependencies |
P2 | Languages |
P2 | Require License Acceptance |
P2 | Summary |
P2 | Project URL |
P2 | Tags |
P3 | Release Notes |
P3 | Copyright |
P3 | Description |
Artifacts
In the user interface we will allow developers to download the .nupkg
file associated with a given package. .nupkg
is a single zip file that contains:
- Compiled code (DLLs)
- Other files related to that code
- A descriptive manifest that includes information like the package's version number.
NOTE: NUPKG files are built from .NUSPEC files, which themselves are built from .DLL assemblies.
.nuspec.xml
The NuGet Manifest - Describes the package's contents and is itself included in the package.
- Drives both the creation of the package and instructs NuGet on how to install the package into a project. For example, the manifest identifies other package dependencies such that NuGet can also install those dependencies when the main package is installed.
Competitor Examples
PackageReference vs. Packageconfig
For the MVC we will implement support for PackageReference. The below lists detail the benefits and limitations of using PackageReference as per Microsoft's documentation.
Benefits of using PackageReference
- Manage all project dependencies in one place: Just like project to project references and assembly references, - NuGet package references (using the PackageReference node) are managed directly within project files rather than using a separate packages.config file.
- Uncluttered view of top-level dependencies: Unlike packages.config, PackageReference lists only those NuGet packages you directly installed in the project. As a result, the NuGet Package Manager UI and the project file aren't cluttered with down-level dependencies.
- Performance improvements: When using PackageReference, packages are maintained in the global-packages folder (as described on Managing the global packages and cache folders rather than in a packages folder within the solution. As a result, PackageReference performs faster and consumes less disk space.
- Fine control over dependencies and content flow: Using the existing features of MSBuild allows you to conditionally reference a NuGet package and choose package references per target framework, configuration, platform, or other pivots.
- PackageReference is under active development: See PackageReference issues on GitHub. packages.config is no longer under active development.
Limitations
- NuGet PackageReference is not available in Visual Studio 2015 and earlier. Migrated projects can be opened only in Visual Studio 2017 and later.
- Migration is not currently available for C++ and ASP.NET projects.
- Some packages may not be fully compatible with PackageReference. For more information, see package compatibility issues.
Permissions and Security
The permissions should follow the same levels as NPM, Maven and Conan.
Group/Project Permissions: UI
Action | Guest | Reporter | Developer | Maintainer | Owner |
---|---|---|---|---|---|
Pull from Maven, NPM, Conan, NuGet | x | x | x | x | |
Publish to Maven, NPM, Conan, NuGet | x | x | x |
Project Permissions: API
Action | Guest | Reporter | Developer | Maintainer | Owner |
---|---|---|---|---|---|
List project packages (5) | x | x | |||
Get a project package | x | x | |||
List package files | x | x | |||
Delete a project package | x | x |
Group Permissions: API
Action | Guest | Reporter | Developer | Maintainer | Owner |
---|---|---|---|---|---|
List the packages of a group (coming soon) | x | x |
Instance Level Permissions
Action | Guest | Reporter | Developer | Maintainer | Owner |
---|---|---|---|---|---|
Enable the Packages feature | x | ||||
Migrate local packages to object storage | x | ||||
Disable the Packages feature | x |
Documentation
- Add a new section to the package registry user guides for the NuGet Repository at https://docs.gitlab.com/ee/user/project/packages/nuget_repository.html
- Packages API
- Packages Admin
What does success look like, and how can we measure that?
This is a new feature, and below are the metrics that we would like to track to measure success.
Priority | Category | Metric | Aggregated by | SMAU Eligible? | Data available? |
---|---|---|---|---|---|
P1 | Package Registry | NuGet Registry enabled/disabled |
|
Yes | No |
P1 | Package Registry | # of page views of /packages
|
|
Yes | Yes |
P1 | Package Registry | # of packages pushed to the NuGet Registry |
|
Yes | No |
P2 | Package Registry | # of NuGet packages deleted |
|
Yes | No |
P2 | Package Registry | # of NuGet packages updated |
|
Yes | No |
Future Development
- Add NuGet Packages to storage counter
- Authenticate with
CI_JOB_TOKEN
- Push/pull NuGet packages at the Group level
- Push NuGet packages at the Project level
- Quotas and limits