diff --git a/docs/03-github/05-returning-a-license.mdx b/docs/03-github/05-returning-a-license.mdx index 08a7b671..ef0fc226 100644 --- a/docs/03-github/05-returning-a-license.mdx +++ b/docs/03-github/05-returning-a-license.mdx @@ -1,14 +1,43 @@ # Returning a license -Manually returning a license is **usually never necessary**, unless when running into an -_unrecoverable error_ while having a license active. +GameCI returns a license automatically at the end of a normal build or test job +when it activated a seat for that job. Manually returning one is usually only +needed after an interrupted job or a confirmed unavailable-seat error on a +later run. -Also, Unity only allows returning professional licenses. +Unity documents command-line return for serial and named-user licenses. Its +documented Personal flow is to sign out of Unity Hub, so do not rely on a +command-line cleanup step as the recovery mechanism for a Personal seat. + +## Return warnings + +Unity's licensing client can print authentication or licensing errors while a +return has succeeded, and can use the same messages for permanent failures. +Therefore, a `License return failed` message alone does **not** prove that a +seat was leaked. Read the surrounding Unity licensing output for a successful +return message or a specific cause. + +GameCI retries only an explicit licensing-client timeout during cleanup. It +does not retry generic messages such as `Access token is unavailable`, because +waiting and repeating the return has not been shown to fix those cases. Clearing +the GitHub Actions cache does not affect Unity's server-side licensing state. + +If later runs report that no seats are available, release the stale activation +in [Unity ID](https://id.unity.com/). This is also the recovery route when the +machine that activated the license is unavailable or its machine binding has +changed. ## Basic setup -You may use [Unity - Return license](https://github.com/marketplace/actions/unity-return-license) to -return your license and free up a spot towards the maximum number of active licenses. +The normal GameCI build already performs its return in the same process and +container that activated the license. Do not add a second return step to every +hosted-runner build: a separately started Docker container has a different +machine identity and Unity can reject its return. + +On a self-hosted runner, where the manual return runs on the same persistent +machine that activated a serial license, you may use +[Unity - Return license](https://github.com/marketplace/actions/unity-return-license) +to release it. Add this step to your workflow: