A GitHub Action that prepares your Unity package for UPM (Unity Package Manager) distribution by creating a dedicated UPM branch with the correct structure.
Upmizer automates the process of preparing Unity packages for distribution via the Unity Package Manager. It:
- Creates a clean UPM branch containing only your package content
- Correctly handles samples by moving them to the UPM-compliant "Samples~" directory
- Pushes the UPM branch to your repository
Name | Description | Required | Default |
---|---|---|---|
upm_branch |
The name of the branch that will be created for UPM distribution | No | upm |
package_root |
Path to your package's root directory | Yes | - |
samples_root |
Path to your samples directory | No | Samples |
docs_root |
Path to your documentation directory | No | Documentation |
publish |
Flag to allow publishing the package to registry like npm or github | No | false |
registry_url |
The URL of the registry to publish the package to | No | https://registry.npmjs.org/ |
registry_token |
Token for authenticating with the registry ( not needed when github) | Yes | - |
github_token |
GitHub authentication token with repo permissions | Yes | - |
versioning |
Strategy enum to enable versioning for the package [semantic, tag, custom] | Yes | semantic |
version |
The version of the package to publish when versioning is set to custom | No | - |
The action requires the following permissions to function correctly:
contents: write
- To create and push the UPM branchpackages: write
- To publish the package to the registry (if applicable)
- uses: NoTaskStudios/upmizer@v1
with:
# You can specify a different branch name if needed
# Default: upm
upm_branch: "upm"
# Required, path to your package's root directory
package_root: "Assets/MyPackage"
# Optional, path to your package's samples directory
# Default: Samples
samples_root: "CustomPathToSamples/Samples"
# Optional, path to your package's documentation directory
# Default: Documentation
docs_root: "CustomPathToDocs/Documentation"
# Optional, flag to allow publishing the package to registry like npm or github
# Default: false
publish: false
# Optional, the URL of the registry to publish the package to
# Default: https://registry.npmjs.org/
registry_url: "https://registry.npmjs.org/"
# Optional, token for authenticating with the registry (not needed when github)
registry_token: ${{ secrets.REGISTRY_TOKEN }}
# Optional, strategy enum to enable versioning for the package [semantic, tag, custom]
# Default: semantic
versioning: "semantic"
# Optional, the version of the package to publish when versioning is set to custom
version: "1.0.0"
# Required, GitHub token with repo permissions
# You can use the default GITHUB_TOKEN secret provided by GitHub Actions
github_token: ${{ secrets.GITHUB_TOKEN }}
- The action extracts your package from the specified root directory using
git subtree
- It creates or updates the UPM branch with your package content
- If a Samples directory exists, it renames it to "Samples~" as required by UPM guidelines
- Finally, it pushes the UPM branch to your repository
- If the publish flag is set to true, it publishes the package to the specified registry using the provided token
- If versioning is enabled, it updates the package version in the
package.json
file according to the specified strategy (semantic, tag, or custom) - The action also handles versioning by updating the
package.json
file with the new version number
When developing Unity packages for UPM distribution, organizing your repository with the proper structure is essential. The following structure is recommended as it:
- Conforms to Unity's package layout standards
- Facilitates seamless UPM conversion
- Improves discoverability of package components
- Simplifies maintenance and versioning
<root>
βββ README.md
βββ Assets
β βββ [YourPackageName]
β βββ package.json
β βββ Runtime
β β βββ [YourPackageName].asmdef
β β βββ ...
β βββ Samples
β β βββ Sample 1
β β βββ Sample 2
β β βββ Sample 3
β β βββ ...
β βββ Documentation
β βββ Doc 1.md
β βββ Doc 2.md
β βββ Doc 3.md
β βββ ...
βββ ...
- uses: NoTaskStudios/upmizer@v1
with:
package_root: "Assets/MyPackage"
github_token: ${{ secrets.GITHUB_TOKEN }}
This example demonstrates the basic usage of the Upmizer action. It creates a UPM branch from the specified package root directory and pushes it to the repository.
- uses: NoTaskStudios/upmizer@v1
with:
package_root: "Assets/MyPackage"
publish: true
registry_url: "https://registry.npmjs.org/"
registry_token: ${{ secrets.NPM_TOKEN }}
github_token: ${{ secrets.GITHUB_TOKEN }}
This example shows how to publish the package to NPM after creating the UPM branch. The publish
flag is set to true
, and the registry URL and token are provided.
- uses: NoTaskStudios/upmizer@v1
with:
package_root: "Assets/MyPackage"
versioning: "semantic"
github_token: ${{ secrets.GITHUB_TOKEN }}
This example demonstrates how to enable versioning for the package. The versioning
input is set to semantic
, which will automatically update the package version based on semantic versioning rules.
- uses: NoTaskStudios/upmizer@v1
with:
# Package configuration options
upm_branch: "upm"
package_root: "Assets/MyPackage"
samples_root: "CustomPathToSamples/Samples"
docs_root: "CustomPathToDocs/Documentation"
# Publishing to NPM
publish: true
registry_url: "https://registry.npmjs.org/"
registry_token: ${{ secrets.NPM_TOKEN }}
github_token: ${{ secrets.GITHUB_TOKEN }}
# Custom versioning
versioning: "custom"
version: "1.0.1" # Updated version number
This example demonstrates advanced usage of the Upmizer action. It specifies custom paths for the samples and documentation directories, enables publishing to NPM, and sets a custom version number for the package.
- Make sure your package contains a valid
package.json
file - The GitHub token requires write permissions to your repository