GitHub Actions for Unity.
Details
- Overview
- Required Settings
- Settings for Different Scenarios
- Is Building Unity Packages Necessary?
- Manual Release
- Release Through Pull Requests
- Recommendations
- Adding Unity Test Framework (formerly Test Runner)
- Adding Package Generation
- PackageExporter
- C# Style Check
- Style Check in Pull Requests
- Manual Execution for Style Check
- Job Descriptions
- About GitHub Actions Usage Fees
- Referenced Repository
This repository provides automation for Unity package releases using GitHub Actions.
This action automates the following tasks:
- Update the package manifest version
- Generate releases
- Create tags
- Run tests using the Unity Test Framework (formerly Test Runner)
- Build packages
- Upload the packages to the release page
- Perform C# style checks
You can choose to execute only specific tasks you need.
When commit messages start with specific keywords like feat or fix, they will be automatically included in the release notes.
| Type | Description |
|---|---|
| feat: | Add new features |
| fix: | Fix bugs |
| docs: | Update or fix documentation |
| style: | Code style fixes (e.g., remove whitespaces) |
| refactor: | Refactor without changing functionality |
| perf: | Changes to improve performance |
Set Read and write permissions for Settings > Actions > General > Workflow permissions.
By default, permission errors will occur. You need to configure GitHub Apps to bypass these protection rules.
- Create a GitHub App
- Install the app and configure it for your repository.
- Add
BOT_APP_IDandBOT_PRIVATE_KEYto the repository's secrets. - Update the app permissions so it can bypass protection rules.
For more details, refer to GitHubApp.md.
Unity needs to be executed in batch mode, which requires Unity account information.
Refer to Activation for the necessary details and configure them in your repository.
Tests and package generation utilize GameCI.
Depending on your Unity license, either UNITY_LICENSE for Personal or UNITY_SERIAL for Pro is mandatory. Add these to the repository's secrets.
| Name | Description |
|---|---|
| UNITY_EMAIL | Email address for Unity login |
| UNITY_PASSWORD | Password for Unity login |
| UNITY_LICENSE | Required for Personal license |
| UNITY_SERIAL | Required for Pro license |
Since Unity 2018, it has been possible to manage packages via the Package Manager (UPM), and now almost all supported Unity versions are compatible with UPM. Because of this, the traditional process of generating Unity packages has become largely unnecessary. As a result, the main workflow we provide does not include the release of Unity packages.
graph LR
validate-branch --> update-packagejson
update-packagejson --> merge-and-push
merge-and-push --> release-notes
release-notes --> create-release
create-release --> clean-branch
For manual releases:
- Navigate to the Actions tab.
- Select
Manual Release (Merge to Default)>Run workflow.
| Option | Description | Default | Example |
|---|---|---|---|
| tag | Git tag to create | N/A | 1.0.0 |
| clean-branch | Whether to delete non-default branches | false | |
| fast-forward | Whether to allow fast-forward merging | false | |
| include-default-branch | Whether to include the default branch in the workflow | false | |
| dry-run | Simulate without committing or pushing changes | false | |
| draft-release | Set to true for a draft release, false for final |
false |
- Create a new branch (e.g.,
release). - Prepare the release in this branch.
- Trigger a manual release using
Run workflow.
- Copy the code from .github/workflows/build-release_merge.yaml to a new YAML file in your project's
.github/workflowsdirectory. - Update the
file-pathinupdate-packagejsonto match your project structure. - If not using branch protection rules, remove references to
secrets.BOT_APP_IDandsecrets.BOT_PRIVATE_KEY.
Note: In case of permission errors during execution, configure proper permissions.
build-release_pull-request.yaml
graph LR
extract-tag --> update-packagejson
update-packagejson --> release-notes
release-notes --> create-release
Create a pull request from any branch to the default branch. Ensure the release title matches the tag name (e.g., 1.0.0). The release will be created automatically after merging the pull request.
Releases are created automatically post-merge.
A release will be created if:
- The pull request title includes a version number (e.g.,
1.0.0). - The base branch is the default branch.
- Create a branch (e.g.,
release). - Prepare the release in this branch.
- Create a pull request from this branch to the default branch with the title set to the version (e.g.,
v1.0.0). - Merge the pull request.
- The release will be generated automatically.
- Copy the code from .github/workflows/build-release_pull-request.yaml to a YAML file in your
.github/workflowsdirectory. - Update the
file-pathinupdate-packagejsonto match your project structure. - If not using branch protection rules, remove references to
secrets.BOT_APP_IDandsecrets.BOT_PRIVATE_KEY.
Even if you primarily use the pull-request-based release method, it is recommended to configure manual release as a fallback.
Execute tests within Unity Editor. Configuration is required to use this feature. Please refer to the Setup section.
Tests are executed using GameCI's Test Runner.
There’s no need to specify individual tests; it will automatically run Edit Tests and/or Play Tests created in UnityEditor.
Please refer to build-release_merge_test.yaml as an example implementation.
- Add
checks: writetopermissions - Add a
unity-testjob - Specify the Unity Editor version in
unity-version(e.g.,2021.3.45f1)
Supported Unity Editor versions can be checked here.
By default, both Edit Mode and Play Mode tests are executed.
If you want to run only specific modes, specify the test-modes parameter. Valid parameters can be found in Game CI - testMode.
To specify multiple modes, separate them with commas.
test-modes: 'playmode,editmode'You can view the list of executed tests.
Sample Execution Result
Unity - Code Coverage will be included in the artifacts.
Refer to build-release_merge_package.yaml for implementation details. Configuration is required, as explained in the Setup section.
This process allows you to:
- Generate packages (UPM package)
- Attach the generated package to the assets section of the release page
The package generation uses GameCI's Builder.
Packages cannot be generated if the package path is outside the Assets folder in Unity Editor.
- [Works]
Assets/MyPackage/ - [Fails]
Packages/MyPackage/
- Add a
build-packagejob - Specify the package name without the extension in
package-name(e.g.,TestPackage) - Specify the Unity Editor version in
unity-version(e.g.,2021.3.45f1) - Add a
release-package-uploadjob
Supported Unity Editor versions can be checked here.
A script for generating packages is required. Please use the provided PackageExporter.
The built package will appear in the release.
Sample Execution Result
This script generates packages. It is lightweight and only functional in the Editor, with no additions to build outputs.
Install it using one of the following methods:
Open Unity Editor, and go to "Window > Package Manager > Add package from git URL...". Enter the following URL to install:
URL: https://github.com/IShix-g/Unity-GitHubActions.git?path=Assets/PackageExporter
Download the package from the Assets section of the release page as PackageExporter_xxx.unitypackage, and install it.
- Open "Window > Test Export Package" in Unity Editor
- Enter the necessary information and run the export
- If no errors appear in the console and the path of the exported package is displayed, the process is successful
Install the exported package in a test project to verify its functionality.
In many teams, there are specific coding conventions such as:
- Private fields should be named using
_myFieldstyle (_+ camelCase) ifstatements must always use{}braces- Indentation should use spaces instead of tabs
A style check enforces these rules automatically when a pull request is opened or a manual trigger is executed, reducing the burden on reviewers.
lint-unity-cs-pull-request.yaml
If there are style issues, the action will fail, and the pull request will display comments highlighting the problems.
The style check runs on newly committed or modified .cs files in the pull request.
- A pull request is created.
- The style check runs automatically when the pull request is created.
- (If issues are found) Fix the issues and commit, triggering another style check.
- Copy the code from lint-unity-cs-pull-request.yaml and create a YAML file in the
.github/workflowsfolder of your project. - Specify the branch for style checks under
branches(e.g.,'main'). - Specify the target paths under
paths(e.g.,Assets/**). Multiple paths can be specified. - (Optional) Configure style check targets with
include-pathsusing regular expressions, separated by,(e.g.,Assets/.*). - (Optional) Exclude paths from style checks with
exclude-paths. - Create a style rule configuration file. Refer to this example to create an .editorconfig.
See the execution example at:
https://github.com/IShix-g/Unity-GitHubActions/actions/runs/13626333298
The style check runs on all specified .cs files.
Click the Run workflow button to execute the style check.
- Copy the code from lint-unity-cs-dispatch.yaml and create a YAML file in the
.github/workflowsfolder of your project. - (Optional) Configure style check targets with
include-pathsusing regular expressions, separated by,(e.g.,Assets/.*). - (Optional) Exclude paths from style checks with
exclude-paths. - Create a style rule configuration file. Refer to this example to create an .editorconfig.
Main Job Descriptions.
.github/workflows/reusable-validate-tag.yaml
This action checks if the tag format is valid and returns outputs.normalized-tag, a normalized version of the tag with only numeric values.
| id | description | default |
|---|---|---|
| require-validation | true to disallow old or invalid tags. false to proceed even if validation fails. |
true |
| validate-semantic-versioning | Specifies whether to validate the tag format using Semantic Versioning. | true |
| tag | The tag to validate (e.g., 1.0.0). |
| id | description |
|---|---|
| normalized-tag | Normalized tag (e.g., tag without the v prefix). |
| tag | Same as the input tag. |
| validated | Indicates whether the tag passed validation. |
.github/workflows/reusable-update-packagejson.yaml
This action updates the version in package.json and commits the changes.
| id | description | default |
|---|---|---|
| file-path | Path to the package.json file to update. You can provide multiline paths. Only package.json files are supported. |
|
| tag | The Git tag to assign (e.g., 1.0.0). |
|
| dry-run | true to simulate the update and commit without actual changes being pushed. |
|
| require-validation | true requires tag validation to pass, false allows proceeding even if it fails. |
true |
| ref | The branch or tag to check out before updating. | |
| commit-message-format | Template for the commit message when updating package.json. Example: Update package.json to {v}. |
Update package.json to {v} |
For branch or tag protection:
| id | description |
|---|---|
| BOT_APP_ID | Specify the application ID |
| BOT_PRIVATE_KEY | Set the private key for the app |
| id | description |
|---|---|
| normalized-tag | Normalized tag (tag without the v prefix). |
| sha | Git commit SHA after the package.json update. |
| changed | Indicates if the Git branch was modified or created. |
.github/workflows/reusable-merge-and-push.yaml
This action merges branches and pushes the changes.
| id | description | default |
|---|---|---|
| target-branch | The target branch from the repository to merge. | |
| push-branch | The branch to push the changes into. | |
| commit-id | Commit ID for creating a release and tag. | |
| dry-run | Enables dry-run mode (simulate without committing). | false |
| fast-forward | Allows a fast-forward merge. | false |
For branch or tag protection:
| id | description |
|---|---|
| BOT_APP_ID | Specify the application ID |
| BOT_PRIVATE_KEY | Set the private key for the app |
| id | description |
|---|---|
| sha | Git commit SHA after the merge. |
| merged | Indicates if the branches were successfully merged. |
.github/workflows/reusable-release-notes.yaml
This action generates release notes based on commit messages. Messages beginning with fix: or feat: will be included in the release notes.
| id | description | default |
|---|---|---|
| from-tag | The starting tag (default: first commit if unset). | |
| to-tag | The ending tag (default: latest commit if unset). | |
| commit-message-format | Format for commit messages (see https://git-scm.com/docs/pretty-formats for details). | - %s (%h) |
| commit-id | Commit ID for release and tag. | |
| derive-from-tag | true to auto-determine from-tag using previous tags; false to configure manually. |
true |
| id | description |
|---|---|
| notes | The generated release notes. |
.github/workflows/reusable-create-release.yaml
This action creates a release and optionally adds a tag.
| id | description | default |
|---|---|---|
| commit-id | Commit ID for creating the release and tag. | |
| dry-run | true to perform a dry run (does not create the release). |
|
| require-validation | true enforces validation; false skips validation and proceeds. |
true |
| wait-before-delete | The wait time (in seconds) before deleting temporary branches. | 25 |
| tag | The Git tag to create (e.g., 1.0.0). |
|
| release-format | Template for the release title. E.g., Ver.{0} will title the release as Ver.1.0.0. {0} omits prefixes. |
Ver.{0} |
| release-note | Custom release notes to include. | |
| draft-release | true for a draft release; false for a final release. |
false |
For branch or tag protection:
| id | description |
|---|---|
| BOT_APP_ID | Specify the application ID |
| BOT_PRIVATE_KEY | Set the private key for the app |
.github/workflows/reusable-unity-test.yaml
- Executes either Edit Tests, Play Tests, or both using Unity Editor
- Test results can be viewed under the Sample Execution Result
- Requires setup to be completed
※ This workflow uses GameCI's Test Runner to execute tests.
| ID | Description | Default Value |
|---|---|---|
| unity-version | Specifies the Unity version. If set to auto, the project's Unity version is used |
auto |
| project-path | Specifies the path to the Unity project | |
| test-modes | Specifies which tests to run | playmode,editmode |
| coverage-options | Sets options for code coverage | generateAdditionalMetrics;generateHtmlReport;generateBadgeReport |
Check supported Unity versions here.
The following secrets are required to execute Unity Editor in batch mode:
| ID | Description |
|---|---|
| UNITY_EMAIL | Email address to log in to Unity |
| UNITY_PASSWORD | Password to log in to Unity |
| UNITY_LICENSE | Required if using a Personal license |
| UNITY_SERIAL | Required if using a Pro license |
For more details, please refer to the setup section.
.github/workflows/reusable-build-package.yaml
- Executes the package build
- Packages must be located under the
Assetsdirectory - Requires the installation of PackageExporter
- Requires setup to be completed
※ This workflow uses GameCI's Builder to generate packages.
| ID | Description | Default Value |
|---|---|---|
| tag | The Git tag to apply (e.g., 1.0.0) |
|
| package-name | Specifies the package name without the extension (e.g., TestPackage) |
|
| commit-id | Commit ID for creating releases or tags | |
| unity-version | Specifies the Unity version. If set to auto, the project's Unity version is used |
auto |
| project-path | Specifies the path to the Unity project | |
| build-method | Name of the script method to build the package, including the namespace | PackageExporter.Editor.CLIBuilder.Build |
| retention-days | Specifies how long the artifact is retained | 0 |
Check supported Unity versions here.
If uploading generated packages to the release page, setting retention-days to 1 day is sufficient.
| ID | Description |
|---|---|
| package-name | The specified package name |
| export-path | Output path of the generated package |
| artifact-url | Download URL of the generated package |
| package-hash | SHA-256 hash of the generated package |
※ export-path is for verification purposes. Due to GitHub Actions' limitations, it will be deleted after the workflow is completed.
The following secrets are required to execute Unity Editor in batch mode:
| ID | Description |
|---|---|
| UNITY_EMAIL | Email address to log in to Unity |
| UNITY_PASSWORD | Password to log in to Unity |
| UNITY_LICENSE | Required if using a Personal license |
| UNITY_SERIAL | Required if using a Pro license |
For more details, please refer to the setup section.
.github/workflows/reusable-release-package-upload.yaml
This action uploads a package to the release page.
| ID | Description | Default Value |
|---|---|---|
| release-tag | Tag of the release to upload the package to (e.g., 1.0.0) |
|
| artifact-package-name | Name of the uploaded artifact package (e.g., TestPackage_1.0.0.unitypackage) |
|
| package-hash | SHA-256 hash of the target package | |
| dry-run | Set to true if only testing; no upload will occur |
false |
If generating the SHA-256 hash yourself, follow the example below:
Note that the artifact-digest produced during artifact upload is also a SHA-256 hash but cannot be reused here.
hash=$(sha256sum "$package_path" | awk '{ print $1 }')This action performs style checks on the specified C# files.
- dotnet format: Used for performing style checks.
- StyleCop.Analyzers: Used for enforcing style guidelines during checks.
- reviewdog: Used for posting messages to pull requests and other reporting purposes.
| ID | Description | Default Value |
|---|---|---|
| ref | Specifies the branch or commit ID to use. | Default branch is used if unspecified. |
| editorconfig-branch | Specifies the branch where the .editorconfig file is located. |
Uses ref if unspecified. |
| files | Specifies the target files in the Assets directory, separated by commas. |
|
| review-reporter | Specifies the reviewdog reporter. | github-pr-review |
| review-level | Specifies the reviewdog level. | warning |
| review-exit-code | Specifies the reviewdog exit code. | error |
When using GitHub Actions in a private repository, usage fees apply. For public repositories, it remains free.
While fees are incurred, there is a free usage allowance available. You can check the details via Billing and plans > Plans and usage > Usage this month.
This repository served as a reference or inspiration for the workflows and configurations described above.
![@github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=64&v=4){kind=small}