⚠️Notice: This project and its documentation are a work in progress. Use with care.

Deploy

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

Platforms supported to build:
- Windows
- Linux
- MacOS
- WebGL
- Android
Platforms supported to deploy:
- Telegram
- Itch.io
- Play Store (Google Play)
Override variables

Requirements

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

How to install

Via OpenUPM

To install it with OpenUPM run: openupm add com.facticus.deploy

Via Git URL

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.

How to setup

Create the workflow

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.

Configure Secrets

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.

General secrets (required for any build and deploy platform)

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.

Build platforms' secrets

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

Deploy platforms' 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 for ITCH_GAME would be example-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 for ITCH_USER would be username.
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.

Notification platforms' secrets

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
- TELEGRAM_TOKEN: same as Telegram deploy platform above.
- TELEGRAM_CHAT_ID: same as Telegram deploy platform above.

Secrets security

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.

How to use

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

Documentation

The full documentation is in the wiki. You will find there a more detailed description of each Deploy's feature.

Known issues

TODO

Acknowledgements

GameCI for creating and making accessible to everyone the tools used by Deploy to build Unity projects.

Support me

License

MIT License

mnicolas94/facticus-deploy