Deploy is a Unity package that allows you to build your game for multiple platforms and deploy them to various stores, remotely (rather than on your PC) and with a single click inside Unity. It uses GitHub Actions and GameCI under the hood to run the builds on GitHub servers.
- Features
- Requirements
- How to install
- How to setup
- How to use
- Documentation
- Known issues
- Acknowledgements
- Platforms supported to build:
- Windows
- Linux
- MacOS
- WebGL
- Android
- Platforms supported to deploy:
- Telegram
- Itch.io
- Play Store (Google Play)
- Override variables
- Your project has to be hosted on GitHub.
- I only tested it on 2021.1+ Unity versions. Versions prior to that one should work, but I'm not sure.
-
TODO
To install it with OpenUPM run:
openupm add com.facticus.deploy
Install dependencies first
- open Package Manager
- click +
- select Add from Git URL
- paste
https://github.com/mackysoft/Unity-SerializeReferenceExtensions.git?path=Assets/MackySoft/MackySoft.SerializeReferenceExtensions
- click Add
Then https://github.com/mnicolas94/UnityUtils.git
with the same method.
And finally, install the Deploy package itself https://github.com/mnicolas94/facticus-deploy.git
.
- Inside Unity open the Deploy's editor window with
Tools/Facticus/Deploy/Open Deploy editor window
. - [optional] Dock the window somewhere within your editor. This is recommended due to a known issue where the window wont open anymore if you lose its focus while it is floating.
- Click on the
Package settings
tab. - First configure the
Git Directory
field if needed. It should point to your git repository's root directory relative to your Unity project's root. Commonly, both directories match, in which case you should leave the field empty. - Then, click the
Generate workflow
button and choose whatever name you want. This will be the name of the GitHub Actions workflow yml file created to build and deploy the project. Just keep this in mind to select a name different from other existent workflows you already have in your project. - Leave the other fields as they are for now and commit and push your changes. This will push the created workflow to GitHub in order for it to be called later.
You need to configure some Secrets in your Github repository in order to use this package. To add secrets you have to go to your repository's Settings -> Secrets and variables -> Actions
. Almost each build and deploy platform has its own set of secrets that need to be configured in order to use it. You only need to configure the secrets of platforms you intend to use.
- UNITY_LICENSE: The contents of a Unity license file (Unity_v20XX.x.ulf). Info on how to get it here.
- UNITY_EMAIL: The email address that you use to login to Unity.
- UNITY_PASSWORD: The password that you use to login to Unity.
Deploy does not acquire nor store your Unity email, password, or license file contents. They are required by GameCI to activate the license during build. More info here.
- Android:
- ANDROID_KEYSTORE_NAME: Your Android keystore name. More info here.
- ANDROID_KEYSTORE_BASE64: The base64 encoded contents of the android keystore file. You can obtain it by running
base64 $androidKeystoreName
whereandroidKeystoreName
is the path to your keystore file. More info here. - ANDROID_KEYSTORE_PASS: The keystore password. More info here.
- ANDROID_KEYALIAS_NAME: The keystore alias name. More info here.
- ANDROID_KEYALIAS_PASS: The keystore alias password. More info here.
- Other platforms do not need to configure secrets.
- Telegram: for Telegram, you need to create a Telegram bot. You only need to create it, no coding is required.
- TELEGRAM_SESSION: can be any string you like, e.g. "deploy". Once used do not change it.
- TELEGRAM_API_ID: id of your telegram app. Visit https://my.telegram.org/apps to get one. More info in Pyrogram setup. Only needed if your build exceeds 50 MB of size.
- TELEGRAM_API_HASH: hash of yout telegram app. Visit https://my.telegram.org/apps to get it. More info in Pyrogram setup. Only needed if your build exceeds 50 MB of size.
- TELEGRAM_TOKEN: the token of your bot. You should have got this when created the bot.
- TELEGRAM_CHAT_ID: the chat ID you want to send the build to. This StackOverflow answer describes how to get it;
- Itch
- ITCH_BUTLER_CREDENTIALS: The key used by butler to authenticate. To get your Butler credentials, you can follow the CI Builds Credentials documentation on Itch.io
- ITCH_GAME: The logical name the game you want to push to. Eg. If your URL is
https://username.itch.io/example-project
, your value forITCH_GAME
would beexample-project
. - ITCH_USER: The username of the owner of the game you are pushing to. If your URL is
https://username.itch.io/example-project
, your value forITCH_USER
would beusername
.
- Play Store
- PLAY_STORE_SERVICE_ACCOUNT_JSON: The contents of your
service-account.json
file. Follow this instructions on how to get it. - PLAY_STORE_PACKAGE_NAME: The package name, or Application Id, of the app you are uploading, e.g.
com.example.myapp
.
- PLAY_STORE_SERVICE_ACCOUNT_JSON: The contents of your
A notification platform is a channel to notify the success or failure of your workflows. Currently, Deploy only supports Telegram as notification platform. To enable it you have to select Telegram in the Package settings' Notify platform
dropdown field. More info in the docs
- Telegram
Since secrets generally hold sensitive credentials and information, it is important to know how these variables are used by third-party actions and workflows, like the ones Deploy uses. This article describes good practices and security measures to take when using Github Actions. I recommend reading it before using this package.
After setting up the initial configurations you can start configuring your builds. Just go to the Contexts tab (called Sets in the following video as it is from a previous version) in the Deploy's editor window (Tools/Facticus/Deploy/Open Deploy editor window
) and create a new Deploy context.
23-06-08.add.a.build.deploy.set.mp4
Each context has the following fields:
- Repository branch or tag: as the name says, here you must specify the repository's branch or tag you want to build and deploy. The branch or tag must contain the workflow file created in the steps above. Also, you can specify the remote you want to use, in case you have more than one, with the syntax
[remote]/[branch or tag]
. In case you just set[branch or tag]
remote defaults toorigin
. - Override variables: a list of scriptable objects overrides. An override is just a new value that will be overriden in the build for a scriptable object in your project. More info in the docs.
- Platforms: a list of Build-Deploy platforms pairs. Each element of the list describes a platform to build for, a platform to deploy to and whether the build should be flagged with Development build.
After configuring your Context press the Build and Deploy
button to start building your game remotely. The first time, you have to provide a github authentication token. Info on how te get one here and here. This token will be stored in the project's Application.persistentDataPath so it wont be versioned by git for security reasons.
The full documentation is in the wiki. You will find there a more detailed description of each Deploy's feature.
TODO
- GameCI for creating and making accessible to everyone the tools used by Deploy to build Unity projects.
MIT License