Unity Automated Semver

Github Action to increment relevant project settings "version" numbers per semantic versioning.

Read more about semantic versioning and its spec on the website: https://semver.org/

Example Usage

In your repository containing a Unity project, you should have a Github Actions workflow file set up in your .github/workflows directory. Name it whatever you want (as long as it ends in ".yml"!). After letting this action run, you then have to sort out committing & pushing the changed file(s) to your repo from within the workflow. The example code below shows all of this; it updates the patch number in every push made to the repository.

Currently, the big downside to this process is that all developers working on the repo must then fetch & pull the changes made by this action. No one should be editing the ProjectSettings.asset file anyway so this shouldn't cause any merge or pull/push issues, but still worth noting.

name: Update Unity project semantic versioning

on: [push, workflow_dispatch]

jobs:
    create:
        name: Update semver
        runs-on: ubuntu-latest

        steps:
            # You must ALWAYS checkout your repo so that actions in the workflow can use it.
            - name: Checkout
              uses: actions/checkout@v4

            - name: Find ProjectSettings.asset & increment its bundleVersion number
              uses: AlexStormwood/[email protected] # Change v1.1.1 to whatever tag is newer in the AlexStormwood/UnityAutomatedSemver repository.
              id: semver-update
              with:
                  updateMode: "patch" # Change this string to any suitable string mentioned in the Inputs section of this action's readme to suit your needs.
                  projectSettingsPath: "ProjectSettings/ProjectSettings.asset" # optional: specify the exact location of the ProjectSettings file, otherwise action will attempt to automatically find it.

            # Validate that the number has been incremented correctly.
            - name: Get the new semver value
              run: echo "The new semver number for this Unity project is ${{ steps.semver-update.outputs.semver-string }}"

            - name: Get the full semver data from the action
              run: echo "Full semver data is ${{ steps.semver-update.outputs.semver-full-data }}"

            # Commit & push the updated semver number back into the repo. Yes, you have to fetch & pull in your local workstation after this step is done.
            - name: Push changed files back to repo
              uses: stefanzweifel/git-auto-commit-action@v5
              with:
                  commit_message: "Updated semver via automated action."
                  commit_options: "--no-verify --signoff"

You could even use other actions to determine the semver bump type, and pass that result into your usage of this action. The example below is suitable for projects that make GitHub Releases for each Unity semver update, since the additional action used determines the semver bump type by looking at releases in the repository alongside your git commit messages (use conventional commits!).

            # Determines semver bump type to use since the last GitHub release occurred
            - name: Determine the semver bump type
              id: determined_bump_version
              uses: mathieudutour/[email protected]
              with:
                github_token: ${{ secrets.GITHUB_TOKEN }}
                default_bump: patch
                # dry_run: true # If this is set to true, no release tag is created. 


            - name: Find ProjectSettings.asset & increment its bundleVersion number
              uses: AlexStormwood/[email protected]
              id: semver-update
              with:
                  updateMode: ${{steps.determined_bump_version.outputs.release_type }} # Will be major, minor, or patch, depending on commits since last GitHub release.
                  projectSettingsPath: "ProjectSettings/ProjectSettings.asset"

And if you just want to apply labels to an existing version, such as creating a nightly build, you can try out this:

            - name: Find ProjectSettings.asset & increment its bundleVersion number
              uses: AlexStormwood/[email protected] 
              id: semver-update
              with:
                  updateMode: "no-bump" # Anything other than major, minor, patch or quad will actually NOT do a number bump. 
                  releaseLabel: "rc1"
                  buildLabel: "nightly" # Even if the updateMode is invalid, you can still add a release and/or build label to the output. 
                  bundleVersion: "{major}.{minor}.{patch}-{releaseLabel}+{buildLabel}" #Specify a custom format for the semver to make sure your data comes through.
                  projectSettingsPath: "ProjectSettings/ProjectSettings.asset"

For Large Projects

If your project takes a long time to checkout in git, you may benefit from doing a sparse checkout when running this action. We don't need your entire Unity project to be checked out into the action runner's workspace, we just need the ProjectSettings.asset file to be somewhere in the action runner's workspace.

For example, if the ProjectSettings folder is in the root of the repo, then this variation of the checkout step will checkout just that folder. Since it includes the ProjectSettings.asset file within that folder, and no paths are changed by a sparse checkout, the rest of a workflow using this action can remain unchanged.

 - name: Checkout 
        uses: actions/checkout@v4
        with:
          sparse-checkout: ProjectSettings

As long as the ProjectSettings.asset file exists somewhere in the action runner's workspace, this action will find it and be able to update it.

Inputs

This is the data that you must set up in your own workflow file to use this action properly.

All inputs are optional, as the action has logic and fallbacks to figure out essential data.

To reiterate: ALL inputs are optional.

If no inputs are provided, the action will attempt to:

automatically find a ProjectSettings.asset file in the given workspace directory (the directory that the GitHub Action runs in and contains the repository that you've checked out)
increment its PATCH number
write the new semver string back into the ProjectSettings.asset file using platform-appropriate version numbering
- this does basically mean that nothing will change for PlayStation platforms, as their version numbering does not seem to use PATCH numbers explicitly.

projectSettingsPath (optional)

The path to the ProjectSettings/ProjectSettings.asset file for your unity project.

If this is not specified, then the action will attempt to automatically find it within the GitHub Action runner's workspace. If you've checked out one single valid Unity project, it'll find the right file automatically. If multiple Unity projects are checked out, the first* ProjectSettings.asset file found will be used.

* I have no idea what "first" will be here, and can't picture any reason to have multiple Unity projects within a single repo - so this should be fine.

backupAssetFile (optional)

Make a copy of the ProjectSettings.asset file, named as ProjectSettings-BACKUP.asset, which reflects the original file before any of this action's modifications were applied.

Useful for keeping a copy of the file if you're still sorting out exactly what version formatting you want to use - just keep in mind that this is not gonna help you if you run this action twice and then check the backup. Run the action, check the backup, copy the backup out to somewhere else, and then run the action again!

updateMode (optional)

When calling this action, you can specify the type of semver update you'd like to perform. Suitable values are:

major
minor
patch
quad

These properties have a priority order. Whichever property is chosen will increment by one, and reset the lower-priority values to zero.

For example, if you have a semver string like "1.2.3", and set this input value to "major", then the new semver string will be "2.0.0".

This is because semver strings follow this priority rule:

major -> minor -> patch

Quads - the fourth number in a semver string - are not part of the semver spec, but are still required by some platforms such as Xbox and Microsoft Store. Since they are not in the semver spec, they will be treated as lowest priority items in that numbering system. So, the full version number priority flow for this action is:

major -> minor -> patch -> quad

There is no automatic mode in this action.

If you want to write a workflow that automatically updates your Unity project's semver based on your conventional commit message history, then you must combine additional steps or actions into your workflow to figure out what type of semver update must be made before running this action.

treatBuildAsPatch (optional)

Defaults to true.

This property allows your patch and build numbers to be identical. This is useful if you're doing a multi-platform project, where you need the build number for UWP platforms and the patch number for non-UWP platforms, and still use the same numbers across each platform.

For comparison of patch and build in common semver formats:

major.minor.patch
major.minor.build.revision

Patches are higher priority than builds since patches are in the semver spec and builds are not, so if build and patch both have data, then build be assigned the value that patch has. The patch value never gets overwritten by the build value.

For 99.9999% of use cases, just leave this as-is.

treatRevisionAsQuad (optional)

Defaults to true.

If you, for whatever reason, need your revision number to be something other than the value in the 4th position of the semver string, set this to false.

For 99.9999% of use cases, just leave this as-is.