Unity Package Manager (UPM) Metadata

This package is used to store metadata about other Unity packages.
It is used by the Package Manager server to fulfill client requests.

Description

Scoped package registry

In Unity 2018.3, UPM supported scoped package registry.
A scoped registry allows you to use a registry in addition to the Unity default registry where you can host your own packages.

In addition, you can use 3rd-party registries such as openupm, xcrew.dev and upm-packages.dev.

However, to use a scoped registry, you must add a scopedRegistries field in Packages/manifest.json.
You also need to add a scopes field depending on the package domains.
This feels a little annoying.

{
  "scopedRegistries": [
    {
      "name": "YourPackageRegistry",
      "url": "https://your.package.registry.com",
      "scopes": [
        "com.your.package-one",
        "com.another.package-two",
        ...
      ]
    }
  ],
  "dependencies": {
    "com.your.package-one": "1.0.0",
    "com.another.package-two": "2.0.0",
    ...
  }
}

A Metadata Package for UPM

The UPM system searches the packages based on a metadata package com.unity.package-manager.metadata.
The package contains a list of all packages searchable in the UI.
See searchablePackages field.

What are the benefits?

If you use verdaccio for package registry, this repository will benefit you.

You can access all packages in your package registry.
- Of course, the official package is also included.
Search, install, update, and remove packages in your package registry from the Package Manager UI without any editor extensions.
The scopedRegistories field in manifest.json is no longer needed.
- Instead, use the registry field (supported in Unity 2017.x or later.)
- Just edit as below:

{
  "registry": "https://your.package.registry.com",
  "dependencies": {
    "com.your.package-one": "1.0.0",
    "com.another.package-two": "2.0.0",
    ...
  }
}

System Requirement

This repository works on GitHub Actions.

If you update locally, request the following:

bash
node 10.18 or later
jq

Usage

Configure your verdaccio according to Verdaccio Configuration.
Fork this repository and clone it.
Change publishConfig.registry field in package.json to the URL of your package registry.

"publishConfig": {
  "registry": "https://your.package.registry.com"
},

You can schedule the workflow to check the official package registry to run at specific UTC times using POSIX cron syntax.
Edit .github/workflows/update.yml as following to change the schedule:

on:
  schedule:
    # check the official package registry daily.
    - cron: "* 0 * * *"

The workflow will push updates to the repository.
See Creating secrets in GitHub and add GH_TOKEN secret on GitHub.
(Optional) To publish this package to your package registry, follow these steps:
1. add NPM_TOKEN secret on GitHub. For details, see Creating secrets in GitHub.
2. Edit .releaserc as follows:

{
  "plugins": [
    [
      "@semantic-release/npm",
      {
        "npmPublish": true
      }
    ],
    ...
  ]
}

(Optional) Update searchable packages manually

Verdaccio Configuration

Verdaccio has a feature called uplinks.
Packages that do not exist in your package registry can be found from an proxy registry.
For example, the com.unity.* packages will be found from Unity official package registry.

In addition, multiple proxies can be configured using uplinks.

Edit the verdaccio configuration file config.yml as follows:

uplinks:
  # the official package registry
  unity:
    url: https://packages.unity.com

  # the third party package registry (e.g. openupm)
  third_party:
    url: https://packages.third.party.com

packages:
  # the metadata package should be found in your package registry
  "com.unity.package-manager.metadata":
    access: $all
    publish: $authenticated

  # unity official packages should be found in official package registry
  "com.unity.*":
    access: $all
    proxy: unity

  # other packages
  "**":
    access: $all
    publish: $authenticated
    unpublish: $authenticated

    # if package is not available locally, proxy requests to other registries
    proxy:
      - third_party
      - unity

# notify to GitHub Actions on published a new package
notify:
  method: POST
  headers:
    [
      { "Content-Type": "application/json" },
      { "Accept": "application/vnd.github.v3+json" },
      { "User-Agent": "verdaccio" },
      { "Authorization": "token {GITHUB_TOKEN}" },
    ]
  endpoint: "https://api.github.com/repos/{OWNER}/unity.package-manager.metadata/dispatches"
  content: '{ "event_type":"package_published", "client_payload": {"name": "{{ name }}" } }'

NOTE: (2020/02/21) Verdaccio v4.4.2 does not support environment variables in config.yml.
Please correct {OWNER} and {GITHUB_TOKEN} to the correct values.
NOTE: (2020/02/21) DO NOT use OpenUPM as a uplink registry.
For details, see openupm/openupm#68.

Creating secrets in GitHub

On GitHub, navigate to the main page of the repository.
Under your repository name, click Settings.
In the left sidebar, click Secrets.
Type a name for your secret in the Name input box.
Type the value for your secret.
Click Add secret.

Variable	Description
`GH_TOKEN`	Required. The token created via GitHub personal access token.
`NPM_TOKEN`	Npm token created via npm token create

Update Searchable Packages Manually

If you do not need GitHub Actions, you can remove .github/workflows/update.yml.
To update searchable packages manually, execute the following commands:

export GH_TOKEM=*********
export NPM_TOKEM=********* # optional
npm ci
npm run update -- --no-ci

NOTE: Execute these commands each time a new package is added to your package registry.

Development Notes

The official staging package registry (https://staging-packages.unity.com) has been decommissioned.
https://forum.unity.com/threads/how-to-use-both-packages-and-staging-packages.534115/
Huge registries such as https://registry.npmjs.org and https://npm.pkg.github.com are not supported.
To update searchable packages on Circle CI, Travis CI, Jenkins, etc., please refer to .github/workflows/update.yml.
(2020/02/21) Verdaccio v4.4.2 does not support environment variables in config.yml.
Please correct {OWNER} and {GITHUB_TOKEN} to the correct values.
(2020/02/21) DO NOT use OpenUPM as a uplink registry.
For details, see openupm/openupm#68.

Support

This is an open-source project that I am developing in my free time.
If you like it, you can support me.
By supporting, you let me spend more time working on better tools that you can use for free. :)

License

Author

mob-sakai

mob-sakai / unity.package-manager.metadata