Working with Packages

OneDev has built-in package registries for Docker, NPM, NuGet, Maven, PyPI and RubyGems.

Compared to using a standalone package registry, the integrated package registries have below benefits:

1. Sharing the same account and permission system with OneDev
2. High availalability and scalability for package storage (available in EE edition)
3. Powerful and sophiscated package query like other parts of OneDev
4. Subscribe to package query to get notifications of new packages
5. Access published packages from CI/CD build directly
6. Generate change log automatically for packages published via CI/CD

Enable Project Package Management

To publish packages under a project, the package management option needs to be enabled:

Once enabled, the packages menu item will be available (for all users with package read permission) displaying published packages of the project:

Permission to Access and Publish Packages

Package read permission is required to access packages of a project, and write permission is required to publish packages to a project. Package permission can be configured via role (which can be associated with project via authorization) like below:

Publish Packages

While it is possible to publish packages outside of OneDev, we highly recommend to publish packages in your CI/CD job to automate things. Also packages published via CI/CD job will be linked with build, code and issues automatically for cross reference.

Push Container Images

OCI-compliant container images can be pushed to project repository via build image step (or its Kaniko alternative) like below:

Here tags property is specified to push image to built-in registry server. The image repository points to current project, but you can push to any other projects if necessary. Image tag is specified as version of current build. Note that registry server should be the same as server url (without protocol part) of system setting, or you can use @server@ to make sure it always uses the correct one.

The property Built-in Registry Access Token Secret should also be specified as a job secret with value set to access token of a user who has permission to publish packages to desired projects.

Deploy Maven Artifacts

Any project can be used as maven artifact repository as long as package management is enabled for the project. To deploy artifacts to a project:

1. Add repository information in pom.xml like below:

   <repositories>
       <repository>
           <id>onedev</id>
           <url>$OneDev_server_url/$project_path/~maven</url>
       </repository>
   </repositories>
   <distributionManagement>
       <repository>
           <id>onedev</id>
           <url>$OneDev_server_url/${project_path}/~maven</url>
       </repository>
       <snapshotRepository>
           <id>onedev</id>
           <url>$OneDev_server_url/${project_path}/~maven</url>
       </snapshotRepository>
   </distributionManagement>

   Here $OneDev_server_url should be replaced by root url of OneDev server, and $project_path should be replaced by path of OneDev project to be used as Maven artifact repository

2. Add below to $HOME/.m2/settings.xml if you want to deploy from command line

   <servers>
       <server>
           <id>onedev</id>
           <!-- Make sure the account has package write permission over the project -->
           <username>onedev_account_name</username>
           <password>onedev_password_or_access_token</password>
       </server>
   </servers>

3. For CI/CD job, it is more convenient to use a custom settings.xml, for instance via below code in a command step:

   cat << EOF > settings.xml
   <settings>
       <servers>
           <server>
               <id>onedev</id>
               <!-- Use job token as user name so that OneDev can know which build is deploying packages -->
               <username>@job_token@</username>
               <!-- Job secret 'access-token' should be defined in project build setting as an access token with package write permission -->
               <password>@secret:access-token@</password>
           </server>
       </servers>
   </settings>
   EOF
   
   mvn --settings settings.xml clean deploy

Publish NPM Packages

Any project can be used as NPM package registry as long as package management is enabled for the project. To publish packages to a project:

1. Configure your package scope to use project registry like below:

   npm config set @myscope:registry $OneDev_server_url/$project_path/~npm/
   npm config set -- '//$OneDev_server_url_without_protocol/$project_path/~npm/:_authToken' "$OneDev_access_token"    

   Here:

   $OneDev_server_url: should be replaced by root url of OneDev server, for instance https://onedev.example.com

   $project_path: should be replaced by path of OneDev project to be used as NPM package registry

   $OneDev_server_url_without_protocol: should be replaced by OneDev server url without protocol part. For instance onedev.example.com

   $OneDev_access_token: should be replaced by access token of a user with package write permission over the project

2. Then publish package from project directory by running:

   npm publish

3. For CI/CD job, run below to publish the package via a command step:

   # Use @@ to reference scope in job commands to avoid being interpreted as variable
   npm config set @@myscope:registry $OneDev_server_url/$project_path/~npm/
   
   # Use job token to tell OneDev the build publishing the package
   # Job secret 'access-token' should be defined in project build setting as an access token with package write permission
   npm config set -- '//$OneDev_server_url_without_protocol/$project_path/~npm/:_authToken' "@job_token@:@secret:access-token@"
   
   npm publish

   Here placeholder $OneDev_server_url, $project_path, and $OneDev_server_url_without_protocol are same as above

Access Published Packages

Published packages will be listed as shown below:

From here, you may query/subscribe interesting packages, or select a package to view its detailed information:

If the package is published via CI/CD job, you may compare it with any previous versions published by same project to get fixed issues or code changes as indicated above.

Also packages published via CI/CD job will be linked with relevant build automatically like below: