Skip to content

A GitHub Action that prepares your Unity package for UPM (Unity Package Manager) distribution by creating a dedicated UPM branch with the correct structure.

License

Notifications You must be signed in to change notification settings

NoTaskStudios/upmizer

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

26 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Upmizer GitHub Action

Version License

A GitHub Action that prepares your Unity package for UPM (Unity Package Manager) distribution by creating a dedicated UPM branch with the correct structure.

Description

Upmizer automates the process of preparing Unity packages for distribution via the Unity Package Manager. It:

  1. Creates a clean UPM branch containing only your package content
  2. Correctly handles samples by moving them to the UPM-compliant "Samples~" directory
  3. Pushes the UPM branch to your repository

Inputs

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 -

Permissions

The action requires the following permissions to function correctly:

  • contents: write - To create and push the UPM branch
  • packages: write - To publish the package to the registry (if applicable)

Usage

- 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 }}

How It Works

  1. The action extracts your package from the specified root directory using git subtree
  2. It creates or updates the UPM branch with your package content
  3. If a Samples directory exists, it renames it to "Samples~" as required by UPM guidelines
  4. Finally, it pushes the UPM branch to your repository
  5. If the publish flag is set to true, it publishes the package to the specified registry using the provided token
  6. If versioning is enabled, it updates the package version in the package.json file according to the specified strategy (semantic, tag, or custom)
  7. The action also handles versioning by updating the package.json file with the new version number

Recommended Folder Structure

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
  β”‚               └── ...
  β”œβ”€β”€ ...

Examples

Example 1: Basic Usage

- 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.

Example 2: Publishing to NPM

- 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.

Example 3: Versioning

- 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.

Example 4: Advanced Usage

- 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.

Notes

  • Make sure your package contains a valid package.json file
  • The GitHub token requires write permissions to your repository

About

A GitHub Action that prepares your Unity package for UPM (Unity Package Manager) distribution by creating a dedicated UPM branch with the correct structure.

Topics

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Contributors 2

  •  
  •