Returning a license

unity-builder and unity-test-runner already return the license they activated once the job finishes - manually returning a license is usually never necessary for those, unless you're running into an unrecoverable error while a license is still active. Manually returning one is only really needed after an interrupted job or a confirmed unavailable-seat error on a later run.

unity-activate is different: it deliberately leaves the license active for a later step, and does not return it itself. Workflows using unity-activate on its own need a separate return step - either game-ci/unity-return-license@v2 or the game-ci return-license CLI command below.

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. This is also the recovery route when the machine that activated the license is unavailable or its machine binding has changed.

Manual recovery

Both Personal and Professional/Plus licenses are returnable - Unity moved Personal onto per-organization seats, so a Personal seat left active by an interrupted or activate-only run consumes a seat just like a Professional one does, and later runs on the same account fail with "no available seats" until it's released.

If you need to return a license by hand - for example after an interrupted run left a seat active - use the game-ci CLI's return-license command:

game-ci return-license ./my-project

See Activate & Return License for the full command reference, including credentials and how the CLI picks the right return mechanism for your license type automatically.

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.

Legacy: Unity - Return license Action

Older workflows not using the game-ci CLI-backed actions may still use the standalone Unity - Return license action:

# Return License
- name: Return license
  uses: game-ci/unity-return-license@v2
  if: always()

The normal GameCI build already performs its return in the same job and container that activated the license, so 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, this is safe.