From 5feecf196c2fdc68e67a71d13f95c190a9c61700 Mon Sep 17 00:00:00 2001 From: Webber Takken Date: Wed, 25 May 2022 14:23:39 +0200 Subject: [PATCH] feat: automatically wrap prose (#291) Co-authored-by: David Finol --- .github/pull_request_template.md | 3 +- .prettierrc.json | 3 +- CODE_OF_CONDUCT.md | 64 +++--- CONTRIBUTING.md | 67 +++---- README.md | 17 +- blog/authors.yml | 8 +- docs/02-getting-started/index.mdx | 15 +- .../01-introduction.mdx | 41 ++-- .../02-game-ci-vs-cloud-runner.mdx | 30 ++- .../02-getting-started/aws.mdx | 9 +- .../02-getting-started/kubernetes.mdx | 3 +- .../03-configuration.mdx | 3 +- .../04-command-line.mdx | 18 +- .../05-advanced-topics/01-caching.md | 3 +- .../05-advanced-topics/02-performance.md | 20 +- .../05-advanced-topics/05-input-override.md | 8 +- .../06-garbage-collection.md | 14 +- .../05-advanced-topics/08-secrets.md | 9 +- docs/03-github/01-getting-started.mdx | 47 +++-- docs/03-github/02-activation.mdx | 35 ++-- docs/03-github/03-test-runner.mdx | 130 ++++++------ docs/03-github/04-builder.mdx | 186 +++++++++--------- docs/03-github/05-returning-a-license.mdx | 8 +- docs/03-github/06-deployment/android.mdx | 136 ++++++++++--- docs/03-github/06-deployment/ios.mdx | 167 ++++++++++++---- docs/03-github/06-deployment/steam.mdx | 57 ++++-- docs/05-gitlab/01-getting-started.mdx | 39 +++- docs/05-gitlab/02-activation.mdx | 53 +++-- docs/05-gitlab/03-example-project.mdx | 24 ++- docs/05-gitlab/04-custom-build-options.mdx | 13 +- docs/05-gitlab/05-tests.mdx | 3 +- docs/05-gitlab/06-deployment/android.mdx | 46 +++-- docs/05-gitlab/06-deployment/ios.mdx | 27 ++- docs/08-docker/01-docker-images.mdx | 46 +++-- docs/08-docker/02-windows-docker-images.mdx | 51 +++-- docs/08-docker/03-customize-docker-images.mdx | 20 +- docs/09-troubleshooting/common-issues.mdx | 14 +- docs/index.mdx | 8 +- lefthook.yml | 4 +- media/prettier-in-webstorm.png | Bin 0 -> 26757 bytes .../version-1/02-getting-started/index.mdx | 15 +- .../version-1/03-docker/01-docker-images.mdx | 46 +++-- .../03-docker/02-windows-docker-images.mdx | 51 +++-- .../03-docker/03-customize-docker-images.mdx | 20 +- .../04-github/01-getting-started.mdx | 38 ++-- .../version-1/04-github/02-activation.mdx | 12 +- .../version-1/04-github/03-test-runner.mdx | 52 +++-- .../version-1/04-github/04-builder.mdx | 115 +++++------ .../04-github/05-returning-a-license.mdx | 8 +- .../04-github/06-deployment/android.mdx | 16 +- .../version-1/04-github/06-deployment/ios.mdx | 40 ++-- .../05-gitlab/01-getting-started.mdx | 39 +++- .../version-1/05-gitlab/02-activation.mdx | 53 +++-- .../05-gitlab/03-example-project.mdx | 24 ++- .../05-gitlab/04-custom-build-options.mdx | 13 +- .../version-1/05-gitlab/05-tests.mdx | 6 +- .../05-gitlab/06-deployment/android.mdx | 46 +++-- .../version-1/05-gitlab/06-deployment/ios.mdx | 27 ++- .../06-troubleshooting/common-issues.mdx | 14 +- versioned_docs/version-1/index.mdx | 8 +- 60 files changed, 1310 insertions(+), 782 deletions(-) create mode 100644 media/prettier-in-webstorm.png diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 13e0b1c8..4cbb43a4 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,6 +6,7 @@ -- [ ] Read the contribution [guide](../blob/main/CONTRIBUTING.md) and accept the [code](../blob/main/CODE_OF_CONDUCT.md) of conduct +- [ ] Read the contribution [guide](../blob/main/CONTRIBUTING.md) and accept the + [code](../blob/main/CODE_OF_CONDUCT.md) of conduct - [ ] Readme (updated or not needed) - [ ] Tests (added, updated or not needed) diff --git a/.prettierrc.json b/.prettierrc.json index 47174e44..54357e67 100644 --- a/.prettierrc.json +++ b/.prettierrc.json @@ -2,5 +2,6 @@ "semi": true, "singleQuote": true, "trailingComma": "all", - "printWidth": 100 + "printWidth": 100, + "proseWrap": "always" } diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index a5bb9874..15a4913b 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -2,17 +2,15 @@ ## Our Pledge -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, sex characteristics, gender identity and expression, -level of experience, education, socio-economic status, nationality, personal +In the interest of fostering an open and welcoming environment, we as contributors and maintainers +pledge to making participation in our project and our community a harassment-free experience for +everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity +and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. ## Our Standards -Examples of behavior that contributes to creating a positive environment -include: +Examples of behavior that contributes to creating a positive environment include: - Using welcoming and inclusive language - Being respectful of differing viewpoints and experiences @@ -22,53 +20,47 @@ include: Examples of unacceptable behavior by participants include: -- The use of sexualized language or imagery and unwelcome sexual attention or - advances +- The use of sexualized language or imagery and unwelcome sexual attention or advances - Trolling, insulting/derogatory comments, and personal or political attacks - Public or private harassment -- Publishing others' private information, such as a physical or electronic - address, without explicit permission -- Other conduct which could reasonably be considered inappropriate in a - professional setting +- Publishing others' private information, such as a physical or electronic address, without explicit + permission +- Other conduct which could reasonably be considered inappropriate in a professional setting ## Our Responsibilities -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. +Project maintainers are responsible for clarifying the standards of acceptable behavior and are +expected to take appropriate and fair corrective action in response to any instances of unacceptable +behavior. -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, +code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or +to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. ## Scope -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be +This Code of Conduct applies both within project spaces and in public spaces when an individual is +representing the project or its community. Examples of representing a project or community include +using an official project e-mail address, posting via an official social media account, or acting as +an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. ## Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at webber@takken.io. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting +the project team at webber@takken.io. All complaints will be reviewed and investigated and will +result in a response that is deemed necessary and appropriate to the circumstances. The project team +is obligated to maintain confidentiality with regard to the reporter of an incident. Further details +of specific enforcement policies may be posted separately. -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. +Project maintainers who do not follow or enforce the Code of Conduct in good faith may face +temporary or permanent repercussions as determined by other members of the project's leadership. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at +https://www.contributor-covenant.org/version/1/4/code-of-conduct.html [homepage]: https://www.contributor-covenant.org diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df8ad94e..bbd574a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,63 +1,52 @@ # Contributing -## How to Contribute +## Code of Conduct -#### Code of Conduct +This repository has adopted the Contributor Covenant as it's Code of Conduct. It is expected that +participants adhere to it. -This repository has adopted the Contributor Covenant as it's -Code of Conduct. It is expected that participants adhere to it. +## Proposing a Change -#### Proposing a Change - -If you are unsure about whether or not a change is desired, -you can create an issue. This is useful because it creates -the possibility for a discussion that's visible to everyone. +If you are unsure about whether or not a change is desired, you can create an issue. This is useful +because it creates the possibility for a discussion that's visible to everyone. When fixing a bug it is fine to submit a pull request right away. -#### Sending a Pull Request - -Steps to be performed to submit a pull request: - -1. Fork the repository and create your branch from `main`. -2. Run `yarn` in the repository root. -3. If you've fixed a bug or added code that should be tested, add tests! -4. Run `yarn build` and make sure no errors are generated in the console before creating the PR. -5. Fill out the description, link any related issues and submit your pull request. +## Setup -#### Pull Request Prerequisites - -##### Tools +### Tools You need the following tools to be installed. -- [Node](https://nodejs.org/) installed at v12.X. -- [Yarn](https://yarnpkg.com/) at v1.18.0+. +- [Node](https://nodejs.org/) installed at v16.X. +- [Yarn](https://yarnpkg.com/) at v1.22.4+. -> **Tip:** _Use -> [nvm](https://github.com/nvm-sh/nvm) or -> [n](https://github.com/tj/n) or -> [nodenv](https://github.com/nodenv/nodenv) -> to manage Node.js versions on your machine._ +> **Tip:** _Use [nvm](https://github.com/nvm-sh/nvm) or [n](https://github.com/tj/n) or +> [nodenv](https://github.com/nodenv/nodenv) to manage Node.js versions on your machine._ -##### Plugins +### Plugins Install and enable plugins for your IDE: - ESLint -- Prettier - _Enable auto format on save: - ([WebStorm](https://www.jetbrains.com/help/idea/prettier.html#ws_prettier_configure), +- [Prettier](https://prettier.io/) - Enable auto format on save: + _([WebStorm](https://www.jetbrains.com/help/idea/prettier.html#ws_prettier_configure), [PhpStorm](https://www.jetbrains.com/help/idea/prettier.html#ws_prettier_configure), - [VS Code](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode#format-on-save))._ + [VS Code](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode#format-on-save))_. + +Prettier configuration -##### Knowledge +## Sending a Pull Request -Please note that commit hooks will run automatically to perform some tasks; +Steps to be performed to submit a pull request: -- format your code -- run tests -- build distributable files +1. Fork the repository and create your branch from `main`. +2. Run `yarn` in the repository root. +3. If you've fixed a bug or added code that should be tested, add tests! +4. Run `yarn build` and make sure no errors are generated in the console before creating the PR. +5. Fill out the description, link any related issues and submit your pull request. -#### License +## License -By contributing to this repository, you agree that your contributions will be licensed under its MIT license. +By contributing to this repository, you agree that your contributions will be licensed under its MIT +license. diff --git a/README.md b/README.md index fcff420a..fa62b0b1 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # GameCI -Documentation for open source GameCI projects. You can find the `.md` files inside the [docs](./docs) folder. -The live version is available on [game.ci](https://game.ci). This website is built using -[Docusaurus 2](https://docusaurus.io/), a modern static website generator. +Documentation for open source GameCI projects. You can find the `.md` files inside the +[docs](./docs) folder. The live version is available on [game.ci](https://game.ci). This website is +built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. ### Installation @@ -16,7 +16,8 @@ yarn yarn start ``` -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. +This command starts a local development server and opens up a browser window. Most changes are +reflected live without having to restart the server. ### Build @@ -24,13 +25,13 @@ This command starts a local development server and opens up a browser window. Mo yarn build ``` -This command generates static content into the `build` directory and can be served using any static contents hosting service. +This command generates static content into the `build` directory and can be served using any static +contents hosting service. ## Community -Feel free to join us on -[![Discord](assets/readme/Discord.svg)](https://game.ci/discord) -and engage with the community. +Feel free to join us on [![Discord](assets/readme/Discord.svg)](https://game.ci/discord) and engage +with the community. ## Support us diff --git a/blog/authors.yml b/blog/authors.yml index 80155f79..36dd3411 100644 --- a/blog/authors.yml +++ b/blog/authors.yml @@ -12,12 +12,16 @@ webbertakken: frostebite: name: Mark D. "Fisher" - title: Lead game developer @bossastudios, former product manager @unity3d, arma modder. Game ai, networking, terrain + title: + Lead game developer @bossastudios, former product manager @unity3d, arma modder. Game ai, + networking, terrain url: https://www.bossastudios.com/ image_url: https://images.opencollective.com/frostebite/b35bd63/avatar/256.png davidmfinol: name: David Finol - title: Lead developer @bossastudios, former product manager @unity3d, arma modder. Game ai, networking, terrain + title: + Lead developer @bossastudios, former product manager @unity3d, arma modder. Game ai, networking, + terrain url: https://github.com/davidmfinol image_url: https://github.com/davidmfinol.png diff --git a/docs/02-getting-started/index.mdx b/docs/02-getting-started/index.mdx index 90bb159f..5446a37f 100644 --- a/docs/02-getting-started/index.mdx +++ b/docs/02-getting-started/index.mdx @@ -1,6 +1,7 @@ # Getting started -The term for automatically testing, building, and deploying your project is Continuous Integration, or CI for short. +The term for automatically testing, building, and deploying your project is Continuous Integration, +or CI for short. The configuration for CI, we commonly call a CI-workflow. @@ -12,10 +13,16 @@ To get started creating your workflow, you need 3 things: ## Preparing the project -**Create a repository** on your chosen Git host and follow their instructions to commit and push your project. +**Create a repository** on your chosen Git host and follow their instructions to commit and push +your project. -Be sure to **ignore any automatically generated files**, by adding the reference [.gitignore](https://github.com/github/gitignore/blob/master/Unity.gitignore) file to the root of your project. +Be sure to **ignore any automatically generated files**, by adding the reference +[.gitignore](https://github.com/github/gitignore/blob/master/Unity.gitignore) file to the root of +your project. -To **ensure large files are handled correctly** (in [LFS](https://git-lfs.github.com/)), you can add our reference [.gitattributes](https://gist.github.com/webbertakken/ff250a0d5e59a8aae961c2e509c07fbc) file to the root of your project. +To **ensure large files are handled correctly** (in [LFS](https://git-lfs.github.com/)), you can add +our reference +[.gitattributes](https://gist.github.com/webbertakken/ff250a0d5e59a8aae961c2e509c07fbc) file to the +root of your project. You are now **ready** to create a workflow! Choose the CI system you chose in the menu on the left. diff --git a/docs/03-github-cloud-runner/01-introduction.mdx b/docs/03-github-cloud-runner/01-introduction.mdx index a8971dcc..4422be9c 100644 --- a/docs/03-github-cloud-runner/01-introduction.mdx +++ b/docs/03-github-cloud-runner/01-introduction.mdx @@ -2,18 +2,24 @@ ## Concept - What Does Cloud Runner Do -**Cloud Runner enables you to run, build and test workflows in the cloud, right from GitHub actions. Builder will automatically provision an environment at a Cloud Provider such as GCP and AWS. It will then send the project to be built and/or tested depending on your workflow configuration.** +**Cloud Runner enables you to run, build and test workflows in the cloud, right from GitHub actions. +Builder will automatically provision an environment at a Cloud Provider such as GCP and AWS. It will +then send the project to be built and/or tested depending on your workflow configuration.** -**Cloud Runner is especially useful for game development because it supports large projects. Cloud Runner provides first class support for the Unity game engine.** +**Cloud Runner is especially useful for game development because it supports large projects. Cloud +Runner provides first class support for the Unity game engine.** -Cloud Runner uses git to track and transfer your projects and uses native cloud services such as AWS Fargate and Kubernetes to run your jobs. Other version control systems are not actively supported. +Cloud Runner uses git to track and transfer your projects and uses native cloud services such as AWS +Fargate and Kubernetes to run your jobs. Other version control systems are not actively supported. ## Why cloud runner? -1. Extended options and more control over disk size, memory and CPU. You can build projects of almost any size. +1. Extended options and more control over disk size, memory and CPU. You can build projects of + almost any size. 2. Scale up to much larger numbers of builds easily and fully on demand. 3. Run custom jobs and extend the system for any workload. -4. Create resources on-demand, we have made an effort to make sure that it costs you nothing while there are no builds running (no guarantees). +4. Create resources on-demand, we have made an effort to make sure that it costs you nothing while + there are no builds running (no guarantees). ## Why not cloud runner? @@ -21,26 +27,30 @@ Cloud Runner uses git to track and transfer your projects and uses native cloud 2. You already have servers running you can use for capacity. 3. You strongly prefer to avoid the addition of time to your pipeline, slowing down results. -Although the speed of a CI pipelines is an important metric to consider, there are real challenges for game development pipelines. +Although the speed of a CI pipelines is an important metric to consider, there are real challenges +for game development pipelines. This solution prefers convenience, ease of use, scalability, throughput and flexibility. -Faster solutions exist, but would all involve self-hosted hardware with an immediate local cache of the large project files and working directory and a dedicated server. +Faster solutions exist, but would all involve self-hosted hardware with an immediate local cache of +the large project files and working directory and a dedicated server. ## Cloud Runner Release Status Cloud Runner is in "active development" ⚠️🔨 -Cloud Runner overall release status: `preview` -This means some APIs may change, features are still being added but the minimum feature set works and is stable. +Cloud Runner overall release status: `preview` This means some APIs may change, features are still +being added but the minimum feature set works and is stable. Release Stages: `experimental` ➡️ `preview` ➡️ `full release` -You must use a provider with Cloud Runner, each provider's release status is described below. This indicates the stability and support for cloud runner features and workflows. +You must use a provider with Cloud Runner, each provider's release status is described below. This +indicates the stability and support for cloud runner features and workflows. ### Development -_Cloud Runner is actively maintained and kept stable by the Game CI open source project contributors._ +_Cloud Runner is actively maintained and kept stable by the Game CI open source project +contributors._ 💬suggestions, 🐛bugs and ↕️Minor changes are tracked as GitHub issues: @@ -66,9 +76,9 @@ You can also explore the [development roadmap page](development). | Azure | ⚠ Considered | ``` -_Note for Kuberentes support:_ -_Usually the cluster needs to be up and running at all times, as starting up a cluster is slow._ -_Use Google Cloud's Kubernetes Autopilot you can scale down to the free tier automatically while not in use._ +_Note for Kuberentes support:_ _Usually the cluster needs to be up and running at all times, as +starting up a cluster is slow._ _Use Google Cloud's Kubernetes Autopilot you can scale down to the +free tier automatically while not in use._ ```md | Git Platform | Release Status | @@ -88,4 +98,5 @@ All cloud runner releases are currently packaged and released with game-ci's uni History up to latest open incoming changes for release can be found here: [Cloud Runner PRs - GitHub](https://github.com/game-ci/unity-builder/pulls?q=is%3Apr+cloud+runner) -You can see further information about configuring the release version on the [Configuration](configuration) page. +You can see further information about configuring the release version on the +[Configuration](configuration) page. diff --git a/docs/03-github-cloud-runner/02-game-ci-vs-cloud-runner.mdx b/docs/03-github-cloud-runner/02-game-ci-vs-cloud-runner.mdx index 9f66998d..cc93abef 100644 --- a/docs/03-github-cloud-runner/02-game-ci-vs-cloud-runner.mdx +++ b/docs/03-github-cloud-runner/02-game-ci-vs-cloud-runner.mdx @@ -2,25 +2,39 @@ Game CI maintains a set of docker images that can be used to run workloads in many scenarios. -Game CI also provides specific GitHub actions for running workflows on GitHub. And a similar workflow for running Game CI on GitLab and Circle CI. -_All of these options use the build server resources provided by those systems, this can be a constraint or very convenient depending on the size of your project and the workloads you need to run._ +Game CI also provides specific GitHub actions for running workflows on GitHub. And a similar +workflow for running Game CI on GitLab and Circle CI. _All of these options use the build server +resources provided by those systems, this can be a constraint or very convenient depending on the +size of your project and the workloads you need to run._ # Use Cases ## Sending Builds to the cloud -You may want to take advantage of cloud resources for lots of reasons (scale, speed, cost, flexibility) or may want to start remote builds from the command line without slowing down your development machine. Cloud Runner can help you do this. +You may want to take advantage of cloud resources for lots of reasons (scale, speed, cost, +flexibility) or may want to start remote builds from the command line without slowing down your +development machine. Cloud Runner can help you do this. -This may be a preference, more effecient or you may want to use systems that struggle to handle large game development projects (GitHub being a good example). +This may be a preference, more effecient or you may want to use systems that struggle to handle +large game development projects (GitHub being a good example). ### Large GitHub Projects -GitHub Actions by default run on [build machines provided by GitHub](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners). For Unity projects the available disk size is quite small. You may experience an error related to running out of disk space. You may also want to run the build on a server with more memory or processing resources. +GitHub Actions by default run on +[build machines provided by GitHub](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners). +For Unity projects the available disk size is quite small. You may experience an error related to +running out of disk space. You may also want to run the build on a server with more memory or +processing resources. ### GitHub Self-Hosted Runners vs Game CI Cloud Runner -_GitHub users can consider: [GitHub self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) and Cloud Runner. Both can enable you to build larger projects._ +_GitHub users can consider: +[GitHub self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) +and Cloud Runner. Both can enable you to build larger projects._ -_Cloud Runner can run itself as an ephemeral self hosted job to minimize your github actions runner usage, with the drawback of some extra startup time at the start of your workflow. Cloud Runner is better if you don't have a server setup or don't want to manage or maintain your own build server._ +_Cloud Runner can run itself as an ephemeral self hosted job to minimize your github actions runner +usage, with the drawback of some extra startup time at the start of your workflow. Cloud Runner is +better if you don't have a server setup or don't want to manage or maintain your own build server._ -_Self-hosted runners are best used when you already have a server available, running 24/7 that you can setup as a runner. And you're happy to maintain and keep that server available and running._ +_Self-hosted runners are best used when you already have a server available, running 24/7 that you +can setup as a runner. And you're happy to maintain and keep that server available and running._ diff --git a/docs/03-github-cloud-runner/02-getting-started/aws.mdx b/docs/03-github-cloud-runner/02-getting-started/aws.mdx index 2674d6a8..14e26b17 100644 --- a/docs/03-github-cloud-runner/02-getting-started/aws.mdx +++ b/docs/03-github-cloud-runner/02-getting-started/aws.mdx @@ -24,8 +24,7 @@ If you're using GitHub you can use a GitHub Action: aws-region: eu-west-2 ``` -_Note:_ -_This enables Cloud Runner access AWS._ +_Note:_ _This enables Cloud Runner access AWS._ ## Configuration For AWS Cloud Runner Jobs @@ -33,7 +32,8 @@ Refer to [Configuration page](../configuration) or the [example below](#example) ### Allowed CPU/Memory Combinations -There are some limitations to the CPU and Memory parameters. AWS will only accept the following combinations: +There are some limitations to the CPU and Memory parameters. AWS will only accept the following +combinations: [AWS Fargate Documentation, Allowed CPU and memory values (Task Definitions)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#task_size) #### Summary Of Format @@ -86,4 +86,5 @@ There are some limitations to the CPU and Memory parameters. AWS will only accep _[Custom Steps](../advanced-topics/custom-steps)_ -A full workflow example can be seen in builder's [Cloud Runner GitHub sourcecode for AWS Pipeline](https://github.com/game-ci/unity-builder/blob/main/.github/workflows/cloud-runner-aws-pipeline.yml). +A full workflow example can be seen in builder's +[Cloud Runner GitHub sourcecode for AWS Pipeline](https://github.com/game-ci/unity-builder/blob/main/.github/workflows/cloud-runner-aws-pipeline.yml). diff --git a/docs/03-github-cloud-runner/02-getting-started/kubernetes.mdx b/docs/03-github-cloud-runner/02-getting-started/kubernetes.mdx index f0fe7489..8b57df07 100644 --- a/docs/03-github-cloud-runner/02-getting-started/kubernetes.mdx +++ b/docs/03-github-cloud-runner/02-getting-started/kubernetes.mdx @@ -72,4 +72,5 @@ Do not include the vCPU or GB suffix. _[Custom Steps](../advanced-topics/custom-steps)_ -A full workflow example can be seen in builder's [Cloud Runner GitHub sourcecode for AWS Pipeline](https://github.com/game-ci/unity-builder/blob/main/.github/workflows/cloud-runner-k8s-pipeline.yml). +A full workflow example can be seen in builder's +[Cloud Runner GitHub sourcecode for AWS Pipeline](https://github.com/game-ci/unity-builder/blob/main/.github/workflows/cloud-runner-k8s-pipeline.yml). diff --git a/docs/03-github-cloud-runner/03-configuration.mdx b/docs/03-github-cloud-runner/03-configuration.mdx index eb7dbe10..2dce9221 100644 --- a/docs/03-github-cloud-runner/03-configuration.mdx +++ b/docs/03-github-cloud-runner/03-configuration.mdx @@ -12,8 +12,7 @@ Include the following variable in the `with` section of the builder step: - `githubToken` (should be a GitHub access token with permission to get repositories) -_Note:_ -_This enables us to get the repository from the AWS build machine._ +_Note:_ _This enables us to get the repository from the AWS build machine._ ### Release branch configuration diff --git a/docs/03-github-cloud-runner/04-command-line.mdx b/docs/03-github-cloud-runner/04-command-line.mdx index 9f19002f..596128b1 100644 --- a/docs/03-github-cloud-runner/04-command-line.mdx +++ b/docs/03-github-cloud-runner/04-command-line.mdx @@ -1,6 +1,8 @@ # Command Line -You can install Game CI locally and start cloud runner jobs from the command line or by integrating your own tools. All parameters in [Configuration](configuration) can be specified as command line input fields. +You can install Game CI locally and start cloud runner jobs from the command line or by integrating +your own tools. All parameters in [Configuration](configuration) can be specified as command line +input fields. # Install @@ -14,7 +16,8 @@ yarn run cli -m {mode parameter} --projectPath {Your project path} {... other co # Planned (does not work currently) -We plan to offer support for Game CI via Deno. This will enable fast, typescript native runtime and you will be able to access this via the following: +We plan to offer support for Game CI via Deno. This will enable fast, typescript native runtime and +you will be able to access this via the following: ```bash dpx game-ci build @@ -22,7 +25,8 @@ dpx game-ci build # Help -_You can run `yarn run cli -h` or `yarn run cli --help` to List all modes and paramters with descriptions_ +_You can run `yarn run cli -h` or `yarn run cli --help` to List all modes and paramters with +descriptions_ # Main Command Parameters @@ -31,9 +35,13 @@ _You can run `yarn run cli -h` or `yarn run cli --help` to List all modes and pa # Avoiding long parameters for commands -You can avoid specifying lots of command line input for credentials (e.g all unity authentication and cloud provider settings) by using environment variables or [the input override feature](advanced-topics/input-override#example) to shorten commands signficantly. +You can avoid specifying lots of command line input for credentials (e.g all unity authentication +and cloud provider settings) by using environment variables or +[the input override feature](advanced-topics/input-override#example) to shorten commands +signficantly. -This enables you to provide a command to pull input, e.g you can pull from a file or from a secret manager. +This enables you to provide a command to pull input, e.g you can pull from a file or from a secret +manager. ```bash yarn run cli --populateOverride true --readInputFromOverrideList UNITY_EMAIL,UNITY_SERIAL,UNITY_PASSWORD --readInputOverrideCommand="gcloud secrets versions access 1 --secret=\"{0}\"" diff --git a/docs/03-github-cloud-runner/05-advanced-topics/01-caching.md b/docs/03-github-cloud-runner/05-advanced-topics/01-caching.md index 9fa1a82d..48967c05 100644 --- a/docs/03-github-cloud-runner/05-advanced-topics/01-caching.md +++ b/docs/03-github-cloud-runner/05-advanced-topics/01-caching.md @@ -9,5 +9,6 @@ - Full project working directory support - Selectively skip caching when hashed cache selection doesn't change -- `tar` supports various types of compression. This will be exposed as an option in the Cloud Runner API. +- `tar` supports various types of compression. This will be exposed as an option in the Cloud Runner + API. - Branch is used as cache key, new branch always misses cache once diff --git a/docs/03-github-cloud-runner/05-advanced-topics/02-performance.md b/docs/03-github-cloud-runner/05-advanced-topics/02-performance.md index c6fa8a8a..cef21655 100644 --- a/docs/03-github-cloud-runner/05-advanced-topics/02-performance.md +++ b/docs/03-github-cloud-runner/05-advanced-topics/02-performance.md @@ -1,25 +1,33 @@ # Performance -By sending the build to a cloud resource we must accept some overhead in time to do this. Cloud Runner tries to manage and offer good solutions to cut down any overhead. As well as supporting you to use all options to speed up common workflows, such as incremental builds. +By sending the build to a cloud resource we must accept some overhead in time to do this. Cloud +Runner tries to manage and offer good solutions to cut down any overhead. As well as supporting you +to use all options to speed up common workflows, such as incremental builds. ## Warm start -⚠️Development roadmap for cloud runner feature: Will enable you to maintain a minimum number of active build resources to handle incoming jobs with shorter delay times to start a job. +⚠️Development roadmap for cloud runner feature: Will enable you to maintain a minimum number of +active build resources to handle incoming jobs with shorter delay times to start a job. ## Push Hooks -⚠️Development roadmap for cloud runner feature: Rather than starting a job from your CI process, you can initally start a Cloud Runner job from your local git push hooks, the CI process can then catch up and observe the logs as needed. +⚠️Development roadmap for cloud runner feature: Rather than starting a job from your CI process, you +can initally start a Cloud Runner job from your local git push hooks, the CI process can then catch +up and observe the logs as needed. ## Sidecar -⚠️Development roadmap for cloud runner feature: Continually stream changes to game-ci workloads without needing to push or even commit explicitly (configurable). +⚠️Development roadmap for cloud runner feature: Continually stream changes to game-ci workloads +without needing to push or even commit explicitly (configurable). ## Caching -Caching is used to speed up git clones, Unity imports and builds and can be extended for custom scenarios. +Caching is used to speed up git clones, Unity imports and builds and can be extended for custom +scenarios. See [Caching](caching). ## Provider Platform's impact -The different Cloud Runner providers all offer different guarenetees and performance for handling your workloads. +The different Cloud Runner providers all offer different guarenetees and performance for handling +your workloads. diff --git a/docs/03-github-cloud-runner/05-advanced-topics/05-input-override.md b/docs/03-github-cloud-runner/05-advanced-topics/05-input-override.md index af3c3a9e..46c2553c 100644 --- a/docs/03-github-cloud-runner/05-advanced-topics/05-input-override.md +++ b/docs/03-github-cloud-runner/05-advanced-topics/05-input-override.md @@ -1,6 +1,9 @@ # Input Override -When running any unity workload you must provide valid unity credentials. In addition to any other credentials this is already quite a lot of input. For this reason, it is common to use the command line mode with input override (link here). This enables you to provide a command to pull input, with this approach you can create a file to store credentials or pull from a secret manager. +When running any unity workload you must provide valid unity credentials. In addition to any other +credentials this is already quite a lot of input. For this reason, it is common to use the command +line mode with input override (link here). This enables you to provide a command to pull input, with +this approach you can create a file to store credentials or pull from a secret manager. ## Example @@ -12,4 +15,5 @@ game-ci -m cli --populateOverride true --readInputFromOverrideList UNITY_EMAIL,U - `populateOverride` - Must be true to run the commands. - `readInputFromOverrideList` - Comma separated list of parameters to read from override command. -- `readInputOverrideCommand` - A command line command to run (The command is formatted to replace "{0}" with the parameter parameter name). +- `readInputOverrideCommand` - A command line command to run (The command is formatted to replace + "{0}" with the parameter parameter name). diff --git a/docs/03-github-cloud-runner/05-advanced-topics/06-garbage-collection.md b/docs/03-github-cloud-runner/05-advanced-topics/06-garbage-collection.md index 9c88f603..eb767bd7 100644 --- a/docs/03-github-cloud-runner/05-advanced-topics/06-garbage-collection.md +++ b/docs/03-github-cloud-runner/05-advanced-topics/06-garbage-collection.md @@ -1,21 +1,25 @@ # Garbage Collection -Cloud Runner creates, manages and destroys cloud workloads you request. Resources have to be created. +Cloud Runner creates, manages and destroys cloud workloads you request. Resources have to be +created. -It is always possible a resource doesn't get deleted by cloud runner. Even if the chance is small, we want to consider the risk of a cloud bill growing unexpectedly seriously. +It is always possible a resource doesn't get deleted by cloud runner. Even if the chance is small, +we want to consider the risk of a cloud bill growing unexpectedly seriously. That is the only way to ensure a tool is safe and trustworthy for the broadast range of people. # Preview Release - Garbage Collection -Cloud Runner runs the workload and cleans up the resources. It does not expect to be interrupted. A failure within the cloud task will not cause a failure to collect garbage. +Cloud Runner runs the workload and cleans up the resources. It does not expect to be interrupted. A +failure within the cloud task will not cause a failure to collect garbage. If you cancel a task, the resources will not be cleaned up. # Full Release - Garbage Collection (Not available yet) -Cloud runner will collect the garbage when it next cleans up. There will be utility functions to clean up directly. -Optional via configuration: Cloud runner can schedule cron jobs to independently guarentee shutdown (already possible via custom hooks). +Cloud runner will collect the garbage when it next cleans up. There will be utility functions to +clean up directly. Optional via configuration: Cloud runner can schedule cron jobs to independently +guarentee shutdown (already possible via custom hooks). # Garbage Collection - Command Line Functions diff --git a/docs/03-github-cloud-runner/05-advanced-topics/08-secrets.md b/docs/03-github-cloud-runner/05-advanced-topics/08-secrets.md index 8fbc0198..e1dd64a9 100644 --- a/docs/03-github-cloud-runner/05-advanced-topics/08-secrets.md +++ b/docs/03-github-cloud-runner/05-advanced-topics/08-secrets.md @@ -1,11 +1,14 @@ # Secrets -Secrets are transferred to workload containers as secrets via the built-in secrets system the provider being used supports. +Secrets are transferred to workload containers as secrets via the built-in secrets system the +provider being used supports. ## Kubernetes -secrets are created as native kuberentes secret objects and mounted to job containers as env variables. +secrets are created as native kuberentes secret objects and mounted to job containers as env +variables. ## AWS -secrets are created as aws secret manager secrets and mounted to fargate tasks from secrets to env variables. +secrets are created as aws secret manager secrets and mounted to fargate tasks from secrets to env +variables. diff --git a/docs/03-github/01-getting-started.mdx b/docs/03-github/01-getting-started.mdx index 536ca79d..e4284ea9 100644 --- a/docs/03-github/01-getting-started.mdx +++ b/docs/03-github/01-getting-started.mdx @@ -2,17 +2,17 @@ import Video from '../../src/components/video/video'; # Getting started -GitHub [Actions for Unity](https://github.com/game-ci/unity-actions) provide the fastest and **easiest** way to automatically test and build any Unity project. +GitHub [Actions for Unity](https://github.com/game-ci/unity-actions) provide the fastest and +**easiest** way to automatically test and build any Unity project. -There are a few parts to setting up a workflow. Steps may slightly differ depending on each license type. +There are a few parts to setting up a workflow. Steps may slightly differ depending on each license +type. ## Mental model #### Overall steps -1. Understand how - [Github Actions](https://docs.github.com/en/actions) - work. +1. Understand how [Github Actions](https://docs.github.com/en/actions) work. 2. Configure a license for Unity. 3. Set up a workflow for your project. 4. Result: Merge pull requests with more confidence. @@ -21,16 +21,14 @@ There are a few parts to setting up a workflow. Steps may slightly differ depend Setting up a workflow is easy! -Create a file called `.github/workflows/main.yml` in your repository and configure the following steps; +Create a file called `.github/workflows/main.yml` in your repository and configure the following +steps; -1. Checkout your repository using - [Checkout](https://github.com/marketplace/actions/checkout). -2. Cache Unity Library folder using - [Cache](https://github.com/marketplace/actions/cache). +1. Checkout your repository using [Checkout](https://github.com/marketplace/actions/checkout). +2. Cache Unity Library folder using [Cache](https://github.com/marketplace/actions/cache). 3. Configure your test job using [Test Runner](https://github.com/marketplace/actions/unity-test-runner). -4. Configure your build job using - [Builder](https://github.com/marketplace/actions/unity-builder). +4. Configure your build job using [Builder](https://github.com/marketplace/actions/unity-builder). 5. Deploy your application. _**Note:** all steps will be explained in the next chapters._ @@ -46,7 +44,8 @@ Any subsequent steps assume you have read the above. ### Supported Unity versions -Unity Actions are using [game-ci/docker](https://github.com/game-ci/docker/) since `unity-builder` version 2. Any version in this list [list](/docs/docker/versions) can be used. +Unity Actions are using [game-ci/docker](https://github.com/game-ci/docker/) since `unity-builder` +version 2. Any version in this list [list](/docs/docker/versions) can be used. ## Video Tutorial @@ -56,7 +55,8 @@ Unity Actions are using [game-ci/docker](https://github.com/game-ci/docker/) sin Below are workflow examples displaying various levels of complexity. -It is **recommended** to start from the [Simple Example](/docs/github/getting-started#simple-example) and work your way down the page. +It is **recommended** to start from the +[Simple Example](/docs/github/getting-started#simple-example) and work your way down the page. ### Simple example @@ -115,7 +115,9 @@ jobs: ### Simple example with Git LFS -If you are using GitHub's git-lfs hosting service to store your large binary assets, you will want to cache them to avoid consuming massive amounts of bandwidth. The extra steps in this example try to restore your git-lfs assets from a cache before doing a git lfs pull. +If you are using GitHub's git-lfs hosting service to store your large binary assets, you will want +to cache them to avoid consuming massive amounts of bandwidth. The extra steps in this example try +to restore your git-lfs assets from a cache before doing a git lfs pull. ```yaml name: Actions 😎 @@ -189,7 +191,8 @@ to test and build for multiple versions of Unity and several target platforms in IL2CPP builds require the base operating system to match the build target. -Below is an example to build for all supported platforms with the IL2CPP scripting backend enabled in the project settings. +Below is an example to build for all supported platforms with the IL2CPP scripting backend enabled +in the project settings. > **Note: Tests are currently only compatible on Linux hosts.** @@ -223,7 +226,9 @@ jobs: - uses: actions/cache@v2 with: path: ${{ matrix.projectPath }}/Library - key: Library-${{ matrix.projectPath }}-${{ matrix.targetPlatform }}-${{ hashFiles(matrix.projectPath) }} + key: + Library-${{ matrix.projectPath }}-${{ matrix.targetPlatform }}-${{ + hashFiles(matrix.projectPath) }} restore-keys: | Library-${{ matrix.projectPath }}-${{ matrix.targetPlatform }}- Library-${{ matrix.projectPath }}- @@ -281,7 +286,9 @@ jobs: - uses: actions/cache@v2 with: path: ${{ matrix.projectPath }}/Library - key: Library-${{ matrix.projectPath }}-${{ matrix.targetPlatform }}-${{ hashFiles(matrix.projectPath) }} + key: + Library-${{ matrix.projectPath }}-${{ matrix.targetPlatform }}-${{ + hashFiles(matrix.projectPath) }} restore-keys: | Library-${{ matrix.projectPath }}-${{ matrix.targetPlatform }}- Library-${{ matrix.projectPath }}- @@ -324,7 +331,9 @@ jobs: - uses: actions/cache@v2 with: path: ${{ matrix.projectPath }}/Library - key: Library-${{ matrix.projectPath }}-${{ matrix.targetPlatform }}-${{ hashFiles(matrix.projectPath) }} + key: + Library-${{ matrix.projectPath }}-${{ matrix.targetPlatform }}-${{ + hashFiles(matrix.projectPath) }} restore-keys: | Library-${{ matrix.projectPath }}-${{ matrix.targetPlatform }}- Library-${{ matrix.projectPath }}- diff --git a/docs/03-github/02-activation.mdx b/docs/03-github/02-activation.mdx index bc8c97ec..743d1abb 100644 --- a/docs/03-github/02-activation.mdx +++ b/docs/03-github/02-activation.mdx @@ -4,7 +4,9 @@ All actions use a Unity installation, which needs to be activated. Unity differentiates their methods between `personal` and `professional` licenses. -Depending on whether you are using a free or paid version of Unity, you will need to follow the steps for either a [personal license](#personal-license) or a [professional license](#professional-license). +Depending on whether you are using a free or paid version of Unity, you will need to follow the +steps for either a [personal license](#personal-license) or a +[professional license](#professional-license). ## Personal license @@ -59,40 +61,47 @@ Commit and push your workflow definition. Follow these (one-time) steps for simple activation. -1. [Manually run](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow) the above workflow. -2. Download the manual activation file that now appeared as an artifact and extract the `Unity_v20XX.X.XXXX.alf` file from the zip. -3. Visit [license.unity3d.com](https://license.unity3d.com/manual) and upload the `Unity_v20XX.X.XXXX.alf` file. -4. You should now receive your license file (Unity_v20XX.x.ulf) as a download. It's ok if the numbers don't match your Unity version exactly. +1. [Manually run](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow) + the above workflow. +2. Download the manual activation file that now appeared as an artifact and extract the + `Unity_v20XX.X.XXXX.alf` file from the zip. +3. Visit [license.unity3d.com](https://license.unity3d.com/manual) and upload the + `Unity_v20XX.X.XXXX.alf` file. +4. You should now receive your license file (Unity_v20XX.x.ulf) as a download. It's ok if the + numbers don't match your Unity version exactly. 5. Open `Github` > `` > `Settings` > `Secrets`. 6. Create the following secrets; - `UNITY_LICENSE` - _(Copy the contents of your license file into here)_ - `UNITY_EMAIL` - _(Add the email address that you use to login to Unity)_ - `UNITY_PASSWORD` - _(Add the password that you use to login to Unity)_ -**GameCI does not acquire nor store your Unity email or password. They are required for reactivating the license during build and test steps.** +**GameCI does not acquire nor store your Unity email or password. They are required for reactivating +the license during build and test steps.** > _**Note:** When changing Unity version, you may need to repeat the same process._ ## Professional license -1. Subscribe to Unity Plus or Unity Pro, and get your Serial Key from the [Unity Subscriptions page](https://id.unity.com/en/subscriptions) +1. Subscribe to Unity Plus or Unity Pro, and get your Serial Key from the + [Unity Subscriptions page](https://id.unity.com/en/subscriptions) 2. Open `Github` > `` > `Settings` > `Secrets` 3. Create the following secrets; - - `UNITY_SERIAL` - _(Add the serial key from step 1 that looks like `XX-XXXX-XXXX-XXXX-XXXX-XXXX`)_ + - `UNITY_SERIAL` - _(Add the serial key from step 1 that looks like + `XX-XXXX-XXXX-XXXX-XXXX-XXXX`)_ - `UNITY_EMAIL` - _(Add the email address that you use to login to Unity)_ - `UNITY_PASSWORD` - _(Add the password that you use to login to Unity)_ -**GameCI does not acquire nor store your Unity email or password. They are required for reactivating the license during build and test steps.** +**GameCI does not acquire nor store your Unity email or password. They are required for reactivating +the license during build and test steps.** > _**Note:** Do NOT follow the steps for the personal license if you have a professional license._ ## Optional steps -- Verify your license using - [Activate](https://github.com/marketplace/actions/unity-activate). +- Verify your license using [Activate](https://github.com/marketplace/actions/unity-activate). - When using a pro license also use - [Return License](https://github.com/marketplace/actions/unity-return-license) - to free up the license allocation after usage. + [Return License](https://github.com/marketplace/actions/unity-return-license) to free up the + license allocation after usage. > _**Note:** Test runner and Builder already include these steps._ diff --git a/docs/03-github/03-test-runner.mdx b/docs/03-github/03-test-runner.mdx index 7959720e..ee5217a4 100644 --- a/docs/03-github/03-test-runner.mdx +++ b/docs/03-github/03-test-runner.mdx @@ -2,7 +2,8 @@ Running your test suite in an automated workflow helps increase certainty when merging. -Use [Unity - Test runner](https://github.com/marketplace/actions/unity-test-runner) to run your Unity tests. +Use [Unity - Test runner](https://github.com/marketplace/actions/unity-test-runner) to run your +Unity tests. _Optional_ to include test coverage, use [Unity - Code Coverage](https://docs.unity3d.com/Packages/com.unity.testtools.codecoverage@1.2/manual/index.html) @@ -18,8 +19,8 @@ Create or edit the file called `.github/workflows/main.yml` and add a job to it. Personal licenses require a one-time manual activation step. Make sure you -[acquire and activate](https://github.com/marketplace/actions/unity-request-activation-file) -your license file and add it as a secret. +[acquire and activate](https://github.com/marketplace/actions/unity-request-activation-file) your +license file and add it as a secret. Then, define the test step as follows: @@ -57,10 +58,13 @@ That is all you need to test your project. ## Viewing test results -The test results can be viewed from a [GitHub Status Check](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-status-checks). +The test results can be viewed from a +[GitHub Status Check](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-status-checks). -To get this functionality, simply provide the [GitHub Token](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret) -in order to view the tests results from [a check run](https://docs.github.com/en/rest/guides/getting-started-with-the-checks-api#about-check-runs). +To get this functionality, simply provide the +[GitHub Token](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret) +in order to view the tests results from +[a check run](https://docs.github.com/en/rest/guides/getting-started-with-the-checks-api#about-check-runs). ```yaml - uses: game-ci/unity-test-runner@v2 @@ -68,7 +72,8 @@ in order to view the tests results from [a check run](https://docs.github.com/en githubToken: ${{ secrets.GITHUB_TOKEN }} ``` -If you choose not to provide the `githubToken`, you may still upload the artifacts in order to access them. +If you choose not to provide the `githubToken`, you may still upload the artifacts in order to +access them. ## Storing test results @@ -91,7 +96,8 @@ Test results can now be downloaded as `Artifacts` in the `Actions` tab. #### Specifying artifacts folder -You can specify a different `artifactsPath` in the test runner and reference this path using the `id` of the test step. +You can specify a different `artifactsPath` in the test runner and reference this path using the +`id` of the test step. ```yaml - uses: game-ci/unity-test-runner@v2 @@ -108,9 +114,9 @@ You can specify a different `artifactsPath` in the test runner and reference thi ### Getting coverage results -The results for the test code coverage are stored in the folder `CodeCoverage` and the path -can be read by the step's `outputs.coveragePath`. These coverage options can be configured -as part of the test and by default will create an XML and HTML web page reports. +The results for the test code coverage are stored in the folder `CodeCoverage` and the path can be +read by the step's `outputs.coveragePath`. These coverage options can be configured as part of the +test and by default will create an XML and HTML web page reports. ```yaml - uses: actions/upload-artifact@v2 @@ -120,21 +126,19 @@ as part of the test and by default will create an XML and HTML web page reports. path: ${{ steps.myTestStep.outputs.coveragePath }} ``` -The coverage results will be generated for whatever tests were selected to run. -If both `editmode` and `playmode` are selected by using `all`, then the results -will have the combined coverage of both test modes. +The coverage results will be generated for whatever tests were selected to run. If both `editmode` +and `playmode` are selected by using `all`, then the results will have the combined coverage of both +test modes. -_Note_ Coverage results are generated with root permission so to move or edit -the output in later steps you may need to use elevated permissions such as `sudo`. +_Note_ Coverage results are generated with root permission so to move or edit the output in later +steps you may need to use elevated permissions such as `sudo`. ## Caching -In order to make test runs (and builds) faster, -you can cache Library files from previous runs. +In order to make test runs (and builds) faster, you can cache Library files from previous runs. To do so, simply add Github Actions' official -[cache action](https://github.com/marketplace/actions/cache) -before any unity steps. +[cache action](https://github.com/marketplace/actions/cache) before any unity steps. ```yaml - uses: actions/cache@v2 @@ -154,11 +158,10 @@ Below options can be specified under `with:` for the `unity-test-runner` action. #### unityVersion -Version of Unity to use for testing the project. -Use "auto" to get from your ProjectSettings/ProjectVersion.txt +Version of Unity to use for testing the project. Use "auto" to get from your +ProjectSettings/ProjectVersion.txt -_**required:** `false`_ -_**default:** `auto`_ +_**required:** `false`_ _**default:** `auto`_ #### customImage @@ -170,22 +173,22 @@ Specific docker image that should be used for testing the project. customImage: 'unityci/editor:2020.1.14f1-base-0' ``` -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### projectPath -Specify the path to your Unity project to be tested. -The path should be relative to the root of your project. +Specify the path to your Unity project to be tested. The path should be relative to the root of your +project. -_**required:** `false`_ -_**default:** ``_ +_**required:** `false`_ _**default:** ``_ #### customParameters Custom parameters to configure the test runner. -For example, you may refer to the [Unity Test Framework command line arguments](https://docs.unity3d.com/Packages/com.unity.test-framework@2.0/manual/reference-command-line.html) for options that could help with configuring your tests. +For example, you may refer to the +[Unity Test Framework command line arguments](https://docs.unity3d.com/Packages/com.unity.test-framework@2.0/manual/reference-command-line.html) +for options that could help with configuring your tests. Parameters must start with a hyphen (`-`) and may be followed by a value (without hyphen). @@ -197,8 +200,7 @@ Parameters without a value will be considered booleans (with a value of true). customParameters: -profile SomeProfile -someBoolean -someValue exampleValue ``` -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### testMode @@ -206,8 +208,7 @@ The type of tests to be run by the test runner. Options are: `All`, `PlayMode`, and `EditMode`. -_**required:** `false`_ -_**default:** `All`_ +_**required:** `false`_ _**default:** `All`_ #### artifactsPath @@ -215,29 +216,29 @@ Path where the test results should be stored. In this folder a folder will be created for every test mode. -_**required:** `false`_ -_**default:** `artifacts`_ +_**required:** `false`_ _**default:** `artifacts`_ ### coverageOptions -Options for configuring code coverage, this configures the `-coverageOptions` -parameter described unity's CodeCoverage documentation: +Options for configuring code coverage, this configures the `-coverageOptions` parameter described +unity's CodeCoverage documentation: [Using Code Coverage in batchmode](https://docs.unity3d.com/Packages/com.unity.testtools.codecoverage@1.2/manual/CoverageBatchmode.html). -By default, this parameter is configured to generate an HTML report with additional metrics. -This should be fine for most projects, but the webpage report can be quite large for projects -with hundreds or thousands of large files. +By default, this parameter is configured to generate an HTML report with additional metrics. This +should be fine for most projects, but the webpage report can be quite large for projects with +hundreds or thousands of large files. -You can add arguments for `assemblyFilters` to specify an assembly to filter files that results are generated for. -This is commonly used to ignore test files or external libraries. See the +You can add arguments for `assemblyFilters` to specify an assembly to filter files that results are +generated for. This is commonly used to ignore test files or external libraries. See the [Using Code Coverage in batchmode](https://docs.unity3d.com/Packages/com.unity.testtools.codecoverage@1.2/manual/CoverageBatchmode.html). -For example, you can add the argument `assemblyFilters:+my.assembly.*` to only include files in the assemblies that match `+my.assembly.*`, -the `*` is a wildcard. This will require making an assembly definition to manage scripts, see Unity's documentation on +For example, you can add the argument `assemblyFilters:+my.assembly.*` to only include files in the +assemblies that match `+my.assembly.*`, the `*` is a wildcard. This will require making an assembly +definition to manage scripts, see Unity's documentation on [Assembly definitions](https://docs.unity3d.com/2022.2/Documentation/Manual/ScriptCompilationAssemblyDefinitionFiles.html) for how to create and manage assembly definitions. -_**required:** `false`_ -_**default:** `generateAdditionalMetrics;generateHtmlReport;generateBadgeReport`_ +_**required:** `false`_ _**default:** +`generateAdditionalMetrics;generateHtmlReport;generateBadgeReport`_ #### useHostNetwork @@ -247,8 +248,7 @@ This is useful if Unity needs to access a local server that was started as part Options are: "true", "false" -_**required:** `false`_ -_**default:** `false`_ +_**required:** `false`_ _**default:** `false`_ #### sshAgent @@ -256,8 +256,7 @@ SSH Agent path to forward to the container. This is useful if your manifest has a dependency on a private GitHub repo. -_**required:** `false`_ -_**default:** ``_ +_**required:** `false`_ _**default:** ``_ #### gitPrivateToken @@ -265,31 +264,32 @@ GitHub Private Access Token (PAT) to pull from GitHub. This is useful if your manifest has a dependency on a private GitHub repo. -_**required:** `false`_ -_**default:** ``_ +_**required:** `false`_ _**default:** ``_ #### githubToken -Token to authorize access to the GitHub REST API. If provided, a check run will be created with the test results. +Token to authorize access to the GitHub REST API. If provided, a check run will be created with the +test results. -It is recommended to use `githubToken: ${{ secrets.GITHUB_TOKEN }}`, -but creating the check from [a fork of your repo](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token) -may require using a [Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token#creating-a-token). +It is recommended to use `githubToken: ${{ secrets.GITHUB_TOKEN }}`, but creating the check from +[a fork of your repo](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token) +may require using a +[Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token#creating-a-token). -Reference the [GitHub Checks API docs](https://docs.github.com/en/rest/reference/checks) -for details on [creating CI tests with the Checks API](https://docs.github.com/en/developers/apps/creating-ci-tests-with-the-checks-api). +Reference the [GitHub Checks API docs](https://docs.github.com/en/rest/reference/checks) for details +on +[creating CI tests with the Checks API](https://docs.github.com/en/developers/apps/creating-ci-tests-with-the-checks-api). -_**required:** `false`_ -_**default:** ``_ +_**required:** `false`_ _**default:** ``_ #### checkName Name for the check run that is created when a github token is provided. -It may be useful to customize the check name if, for example, you have a job matrix with multiple unity versions. +It may be useful to customize the check name if, for example, you have a job matrix with multiple +unity versions. -_**required:** `false`_ -_**default:** `Test Results`_ +_**required:** `false`_ _**default:** `Test Results`_ ## Complete example diff --git a/docs/03-github/04-builder.mdx b/docs/03-github/04-builder.mdx index 5985f04a..d5ecced7 100644 --- a/docs/03-github/04-builder.mdx +++ b/docs/03-github/04-builder.mdx @@ -1,9 +1,10 @@ # Builder -Building the project as part of a workflow may help to create mind-space and focus on the project itself. +Building the project as part of a workflow may help to create mind-space and focus on the project +itself. -Use [Unity - Builder](https://github.com/marketplace/actions/unity-builder) -to automatically build Unity projects for different platforms. +Use [Unity - Builder](https://github.com/marketplace/actions/unity-builder) to automatically build +Unity projects for different platforms. ## Basic setup @@ -14,10 +15,12 @@ Make sure you have set up these variables in the [activation step](/docs/github/ - `UNITY_EMAIL` (the email address for your Unity account) - `UNITY_PASSWORD` (the password that you use to login to Unity) -NOTE: Issues have been observed when using a `UNITY_PASSWORD` with special characters. -It is recommended to use a password without any special characters (mixed-case alphanumeric characters only). +NOTE: Issues have been observed when using a `UNITY_PASSWORD` with special characters. It is +recommended to use a password without any special characters (mixed-case alphanumeric characters +only). -**GameCI does not acquire nor store your Unity email or password. They are required for reactivating the license during build and test steps.** +**GameCI does not acquire nor store your Unity email or password. They are required for reactivating +the license during build and test steps.** #### Workflow file setup @@ -27,9 +30,8 @@ Create or edit the file called `.github/workflows/main.yml` and add a job to it. Personal licenses require a one-time manual activation step. -Make sure you -[acquire and activate](/docs/github/activation) -your license file and add it as a secret. +Make sure you [acquire and activate](/docs/github/activation) your license file and add it as a +secret. Then, define the build step as follows: @@ -69,11 +71,10 @@ By default, the enabled scenes from the project's settings will be built. ## Storing the build -To be able to access your built files, -they need to be uploaded as artifacts. -To do this it is recommended to use Github Actions official -[upload artifact action](https://github.com/marketplace/actions/upload-artifact) -after any build action. +To be able to access your built files, they need to be uploaded as artifacts. To do this it is +recommended to use Github Actions official +[upload artifact action](https://github.com/marketplace/actions/upload-artifact) after any build +action. By default, Builder outputs it's builds to a folder named `build`. @@ -90,9 +91,9 @@ Builds can now be downloaded as Artifacts in the Actions tab. ## Caching -In order to make builds run faster, you can cache Library files from previous -builds. To do so simply add Github Actions official -[cache action](https://github.com/marketplace/actions/cache) before any unity steps. +In order to make builds run faster, you can cache Library files from previous builds. To do so +simply add Github Actions official [cache action](https://github.com/marketplace/actions/cache) +before any unity steps. Example: @@ -116,17 +117,17 @@ Below options can be specified under `with:` for the `unity-builder` action. Platform that the build should target. -Must be one of the [allowed values](https://docs.unity3d.com/ScriptReference/BuildTarget.html) listed in the Unity scripting manual. +Must be one of the [allowed values](https://docs.unity3d.com/ScriptReference/BuildTarget.html) +listed in the Unity scripting manual. _**required:** `true`_ #### unityVersion -Version of Unity to use for building the project. -Use "auto" to get from your ProjectSettings/ProjectVersion.txt +Version of Unity to use for building the project. Use "auto" to get from your +ProjectSettings/ProjectVersion.txt -_**required:** `false`_ -_**default:** `auto`_ +_**required:** `false`_ _**default:** `auto`_ #### customImage @@ -138,23 +139,20 @@ Specific docker image that should be used for building the project. customImage: 'unityci/editor:2020.1.14f1-base-0' ``` -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### projectPath -Specify the path to your Unity project to be built. -The path should be relative to the root of your project. +Specify the path to your Unity project to be built. The path should be relative to the root of your +project. -_**required:** `false`_ -_**default:** ``_ +_**required:** `false`_ _**default:** ``_ #### buildName Name of the build. Also the folder in which the build will be stored within `buildsPath`. -_**required:** `false`_ -_**default:** ``_ +_**required:** `false`_ _**default:** ``_ #### buildsPath @@ -162,8 +160,7 @@ Path where the builds should be stored. In this folder a folder will be created for every targetPlatform. -_**required:** `false`_ -_**default:** `build`_ +_**required:** `false`_ _**default:** `build`_ #### buildMethod @@ -182,7 +179,9 @@ Example: buildMethod: EditorNamespace.BuilderClassName.StaticBuildMethod ``` -To get started with a modified version of the default Unity Builder build script, you can copy [BuildScript.cs](https://github.com/game-ci/documentation/blob/main/example/BuildScript.cs) to your `Assets/Editor/UnityBuilderAction` directory and reference it: +To get started with a modified version of the default Unity Builder build script, you can copy +[BuildScript.cs](https://github.com/game-ci/documentation/blob/main/example/BuildScript.cs) to your +`Assets/Editor/UnityBuilderAction` directory and reference it: ```yaml - uses: game-ci/unity-builder@v2 @@ -192,8 +191,7 @@ To get started with a modified version of the default Unity Builder build script If you need to pass custom parameters to this build method, see `customParameters` below. -_**required:** `false`_ -_**default:** Built-in script that will run a build out of the box._ +_**required:** `false`_ _**default:** Built-in script that will run a build out of the box._ #### customParameters @@ -212,10 +210,10 @@ Parameters without a value will be considered booleans (with a value of true). There are 2 main use cases: - To pass your own custom parameters to be used with `buildMethod` above -- To pass [Unity Build Options](https://docs.unity3d.com/ScriptReference/BuildOptions.html) (for example, `customParameters: -EnableHeadlessMode` will do server builds) +- To pass [Unity Build Options](https://docs.unity3d.com/ScriptReference/BuildOptions.html) (for + example, `customParameters: -EnableHeadlessMode` will do server builds) -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### versioning @@ -248,32 +246,32 @@ No configuration required. ##### Tag -Generates the version based on the latest git tag. For example `0.17.2` will -generate the version `0.17.2`. A leading "v" is stripped, so a version of -`v1.3.3` will generate a version of `1.3.3`. **(advanced users)** +Generates the version based on the latest git tag. For example `0.17.2` will generate the version +`0.17.2`. A leading "v" is stripped, so a version of `v1.3.3` will generate a version of `1.3.3`. +**(advanced users)** -> Compatible with **all platforms**. -> Does **not** modify your repository. +> Compatible with **all platforms**. Does **not** modify your repository. ##### Custom Allows specifying a custom version in the `version` field. **(advanced users)** -> This strategy is useful when your project or pipeline has some kind of orchestration -> that determines the versions. +> This strategy is useful when your project or pipeline has some kind of orchestration that +> determines the versions. ##### None No version will be set by Builder. **(not recommended)** -> Not recommended unless you generate a new version in a pre-commit hook. Manually -> setting versions is error-prone. +> Not recommended unless you generate a new version in a pre-commit hook. Manually setting versions +> is error-prone. #### androidVersionCode Configure the android `versionCode`. -When not specified, the version code is generated from the version using the `major * 1000000 + minor * 1000 + patch` scheme; +When not specified, the version code is generated from the version using the +`major * 1000000 + minor * 1000 + patch` scheme; #### androidAppBundle @@ -292,58 +290,55 @@ Set this flag to `true` to build '.aab' instead of '.apk'. You should also set all the Android Keystore options (see below). -_**required:** `false`_ -_**default:** `false`_ +_**required:** `false`_ _**default:** `false`_ #### androidKeystoreName Configure the android `keystoreName`. Must be provided if configuring the below keystore options. For this to take effect, you must enable `Custom Keystore` in your -[Android Player settings](https://docs.unity3d.com/Manual/class-PlayerSettingsAndroid.html). -The default build script overrides the other keystore settings with these keystore options. +[Android Player settings](https://docs.unity3d.com/Manual/class-PlayerSettingsAndroid.html). The +default build script overrides the other keystore settings with these keystore options. -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### androidKeystoreBase64 -Configure the base64 contents of the android keystore file. You should get this with `base64 $androidKeystoreName` +Configure the base64 contents of the android keystore file. You should get this with +`base64 $androidKeystoreName` -The contents will be decoded from base64 using `echo $androidKeystoreBase64 | base64 --decode > $projectPath/$androidKeystoreName` +The contents will be decoded from base64 using +`echo $androidKeystoreBase64 | base64 --decode > $projectPath/$androidKeystoreName` -It is recommended to use [GitHub Secrets](https://docs.github.com/en/actions/reference/encrypted-secrets). +It is recommended to use +[GitHub Secrets](https://docs.github.com/en/actions/reference/encrypted-secrets). -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### androidKeystorePass Configure the android `keystorePass`. Recommended to use GitHub Secrets. -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### androidKeyaliasName Configure the android `keyaliasName`. Recommended to use GitHub Secrets. -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### androidKeyaliasPass Configure the android `keyaliasPass`. Recommended to use GitHub Secrets. -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### androidTargetSdkVersion -Configure the android target API level. If used, must be one of [Unity's AndroidSdkVersions](https://docs.unity3d.com/ScriptReference/AndroidSdkVersions.html). +Configure the android target API level. If used, must be one of +[Unity's AndroidSdkVersions](https://docs.unity3d.com/ScriptReference/AndroidSdkVersions.html). -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### sshAgent @@ -351,8 +346,7 @@ SSH Agent path to forward to the container. This is useful if your manifest has a dependency on a private GitHub repo. -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### gitPrivateToken @@ -360,15 +354,14 @@ Github private token to pull from github. This is useful if your manifest has a dependency on a private GitHub repo. -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### chownFilesTo -User and optionally group (user or user:group or uid:gid) to give ownership of the resulting build artifacts. +User and optionally group (user or user:group or uid:gid) to give ownership of the resulting build +artifacts. -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### allowDirtyBuild @@ -380,21 +373,20 @@ Allows the branch of the build to be dirty, and still generate the build. allowDirtyBuild: true ``` -Note that it is generally bad practice to modify your branch -in a CI Pipeline. However there are exceptions where this might -be needed. (use with care). +Note that it is generally bad practice to modify your branch in a CI Pipeline. However there are +exceptions where this might be needed. (use with care). -_**required:** `false`_ -_**default:** `false`_ +_**required:** `false`_ _**default:** `false`_ ## Outputs -Below are outputs that can be accessed by using `${{ steps.myBuildStep.outputs.outputName }}`, where `myBuildStep` is the id -of the Builder step, and `outputName` is the name of the output. +Below are outputs that can be accessed by using `${{ steps.myBuildStep.outputs.outputName }}`, where +`myBuildStep` is the id of the Builder step, and `outputName` is the name of the output. #### buildVersion -Returns the version that was generated by Builder, following the strategy configured for `versioning`. +Returns the version that was generated by Builder, following the strategy configured for +`versioning`. ```yaml - uses: game-ci/unity-builder@v2 @@ -404,12 +396,18 @@ Returns the version that was generated by Builder, following the strategy config ## Private Github repositories -If you use private git repository in your packages/manifest.json, you need to create SSH pub/private keys for your project and then add to the `webfactory/ssh-agent` - -- Generate public,private key for github's SSH using [this instruction](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key) and make sure that you you use `git@github.com:USER/PROJECT.git` instead of email for `-C` parameter because we're going to use it as deploy key for a single project and `webfactory/ssh-agent` going to use that for checking which repository this key is related to . -- Add the public_key to Deploy settings of your private git repository ( https://github.com/USER/PROJECT/settings/keys) -- Add private_key to Github secrets of the project that you want to build (https://github.com/USER/PROJECT/settings/secrets/actions) - (key name should be SSH_PRIVATE_KEY ) +If you use private git repository in your packages/manifest.json, you need to create SSH pub/private +keys for your project and then add to the `webfactory/ssh-agent` + +- Generate public,private key for github's SSH using + [this instruction](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key) + and make sure that you you use `git@github.com:USER/PROJECT.git` instead of email for `-C` + parameter because we're going to use it as deploy key for a single project and + `webfactory/ssh-agent` going to use that for checking which repository this key is related to . +- Add the public_key to Deploy settings of your private git repository ( + https://github.com/USER/PROJECT/settings/keys) +- Add private_key to Github secrets of the project that you want to build + (https://github.com/USER/PROJECT/settings/secrets/actions) (key name should be SSH_PRIVATE_KEY ) - Finally, add `webfactory/ssh-agent` to your Github action : ```yaml @@ -427,9 +425,10 @@ steps: ## UPM authentication using .upmconfig.toml -Unity requires an .upmconfig.toml to exist in the home directory to authenticate and download packages from private UPM registries. -To create this file, first create the `/home/runner/work/_temp/_github_home` directory, and then create the .upmconfig.toml file inside that directory. -This action must be done before running the game-ci/unity-builder@v2 action. +Unity requires an .upmconfig.toml to exist in the home directory to authenticate and download +packages from private UPM registries. To create this file, first create the +`/home/runner/work/_temp/_github_home` directory, and then create the .upmconfig.toml file inside +that directory. This action must be done before running the game-ci/unity-builder@v2 action. ```yaml - name: Create .upmconfig.toml UPM authentication file @@ -488,4 +487,5 @@ jobs: ## Next steps -You can find more workflow examples in [Getting Started](/docs/github/getting-started#workflow-examples). +You can find more workflow examples in +[Getting Started](/docs/github/getting-started#workflow-examples). diff --git a/docs/03-github/05-returning-a-license.mdx b/docs/03-github/05-returning-a-license.mdx index 53770a0c..08a7b671 100644 --- a/docs/03-github/05-returning-a-license.mdx +++ b/docs/03-github/05-returning-a-license.mdx @@ -1,14 +1,14 @@ # Returning a license -Manually returning a license is **usually never necessary**, -unless when running into an _unrecoverable error_ while having a license active. +Manually returning a license is **usually never necessary**, unless when running into an +_unrecoverable error_ while having a license active. Also, Unity only allows returning professional licenses. ## 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. +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. Add this step to your workflow: diff --git a/docs/03-github/06-deployment/android.mdx b/docs/03-github/06-deployment/android.mdx index 44cf5b66..d2328d66 100644 --- a/docs/03-github/06-deployment/android.mdx +++ b/docs/03-github/06-deployment/android.mdx @@ -1,71 +1,132 @@ # Deploy to Google Play -This guide is intended to help with automating Android builds to upload to the Play Store. If you just need to produce an APK, the [unity-builder](https://game.ci/docs/github/builder) action will do that. However, if you intend to distribute your game on the Play Store, either for public distribution or a beta track, this guide is for you. +This guide is intended to help with automating Android builds to upload to the Play Store. If you +just need to produce an APK, the [unity-builder](https://game.ci/docs/github/builder) action will do +that. However, if you intend to distribute your game on the Play Store, either for public +distribution or a beta track, this guide is for you. ### 1. Install Fastlane -[Fastlane](https://docs.fastlane.tools/getting-started/ios/setup/) is a tool that can facilitate building and submitting your Android apps to Google, and is the easiest way to deploy your Unity project to Android for Play Store distribution. +[Fastlane](https://docs.fastlane.tools/getting-started/ios/setup/) is a tool that can facilitate +building and submitting your Android apps to Google, and is the easiest way to deploy your Unity +project to Android for Play Store distribution. -To configure Fastlane for your GitHub Actions workflow runners, you will need to locally set up a `Gemfile` and `Fastfile` within your project. A `Gemfile` specifies what Ruby dependencies are needed to set up and run Fastlane (which is written in Ruby), and a `Fastfile` will be how you configure your Android deployment settings. We will set up the `Gemfile` now, and the `Fastfile` in a later step. +To configure Fastlane for your GitHub Actions workflow runners, you will need to locally set up a +`Gemfile` and `Fastfile` within your project. A `Gemfile` specifies what Ruby dependencies are +needed to set up and run Fastlane (which is written in Ruby), and a `Fastfile` will be how you +configure your Android deployment settings. We will set up the `Gemfile` now, and the `Fastfile` in +a later step. -You will need your local machine to have [Ruby](https://www.ruby-lang.org/en/documentation/installation/) installed, as well as Bundler. If you have Ruby installed but are unsure if you have Bundler, you can run the following to install it: +You will need your local machine to have +[Ruby](https://www.ruby-lang.org/en/documentation/installation/) installed, as well as Bundler. If +you have Ruby installed but are unsure if you have Bundler, you can run the following to install it: ```bash gem install bundler ``` -From there, create a file called `Gemfile` in the root of your git repository with following content: +From there, create a file called `Gemfile` in the root of your git repository with following +content: ```ruby title="Gemfile" source "https://rubygems.org" gem "fastlane" ``` -Then run `bundle install`. This will create an additional `Gemfile.lock` file in the root of your project. +Then run `bundle install`. This will create an additional `Gemfile.lock` file in the root of your +project. Commit both `Gemfile` and `Gemfile.lock` to your repo. ### 2. Create a Google Play Service Account -To programmatically access the Google Play Console, you will need a dedicated Google Play service account with API access. +To programmatically access the Google Play Console, you will need a dedicated Google Play service +account with API access. -Follow the ["Setup" section of the Fastlane Supply documentation](https://docs.fastlane.tools/actions/supply/) to create a service account. +Follow the +["Setup" section of the Fastlane Supply documentation](https://docs.fastlane.tools/actions/supply/) +to create a service account. -After the last step, it will tell you to test the connection to the Google Play Store, and then add your JSON file path to your Appfile. You can do the first step if you would like (you may need to run `bundle exec fastlane` instead of just `fastlane`), but don't worry about the Appfile, as we will be be creating that in the next step. +After the last step, it will tell you to test the connection to the Google Play Store, and then add +your JSON file path to your Appfile. You can do the first step if you would like (you may need to +run `bundle exec fastlane` instead of just `fastlane`), but don't worry about the Appfile, as we +will be be creating that in the next step. -Instead, create a Repository Secret in your GitHub repository by going to Settings -> Secrets and clicking the "New repository secret" button in the top-right. It should be titled `GOOGLE_PLAY_KEY_FILE` and its value should be the plaintext contents of the downloaded JSON file. +Instead, create a Repository Secret in your GitHub repository by going to Settings -> Secrets and +clicking the "New repository secret" button in the top-right. It should be titled +`GOOGLE_PLAY_KEY_FILE` and its value should be the plaintext contents of the downloaded JSON file. ### 3. Generate an upload key and keystore -Distributing an app via the Google Play Store requires uploading an unsigned Android App Bundle (AAB) file and letting Google codesign your app for you using Play App Signing. In order to do this, you need to create an upload signing key, which you will then sign your app with. - -In Unity, while Android is your selected build platform, open Player Settings. Under "Publishing Settings", click the "Keystore Manager" button to open the keystore manager. Click the "Keystore" dropdown, and then "Create New" > "Anywhere" to create a new keystore file. You can select any file location, just note where it is. - -Fill out all the fields in this form. Both of the password and password confirmation fields (so, four password fields total) should contain the same password. Click "Add key" when you're done. In Player Settings, confirm that the "Custom Keystore" checkbox is checked, and the correct keystore path, keystore password, alias name, and alias password are set. Be sure to commit and push these changes to your git repository. - -If you would rather use Android Studio to generate an upload key and keystore, you can follow [Google's guide](https://developer.android.com/studio/publish/app-signing#generate-key) and then manually select that keystore within the Unity Player Settings. It doesn't matter as long as you end up with a valid `.keystore` file and Unity is configured to use that custom keystore. - -Be sure to keep your `.keystore` file and password handy, as we will be using them in future steps. We recommend that you **not** check your `.keystore` file into git, as this can reduce security. If your workflow requires developers to be able to manually build the project, we recommend adding the `.keystore` file to your `.gitignore` (if you want to keep it in your project directory) and finding an alternate way to transfer it between developers, such as a shared password manager that supports file uploads. +Distributing an app via the Google Play Store requires uploading an unsigned Android App Bundle +(AAB) file and letting Google codesign your app for you using Play App Signing. In order to do this, +you need to create an upload signing key, which you will then sign your app with. + +In Unity, while Android is your selected build platform, open Player Settings. Under "Publishing +Settings", click the "Keystore Manager" button to open the keystore manager. Click the "Keystore" +dropdown, and then "Create New" > "Anywhere" to create a new keystore file. You can select any file +location, just note where it is. + +Fill out all the fields in this form. Both of the password and password confirmation fields (so, +four password fields total) should contain the same password. Click "Add key" when you're done. In +Player Settings, confirm that the "Custom Keystore" checkbox is checked, and the correct keystore +path, keystore password, alias name, and alias password are set. Be sure to commit and push these +changes to your git repository. + +If you would rather use Android Studio to generate an upload key and keystore, you can follow +[Google's guide](https://developer.android.com/studio/publish/app-signing#generate-key) and then +manually select that keystore within the Unity Player Settings. It doesn't matter as long as you end +up with a valid `.keystore` file and Unity is configured to use that custom keystore. + +Be sure to keep your `.keystore` file and password handy, as we will be using them in future steps. +We recommend that you **not** check your `.keystore` file into git, as this can reduce security. If +your workflow requires developers to be able to manually build the project, we recommend adding the +`.keystore` file to your `.gitignore` (if you want to keep it in your project directory) and finding +an alternate way to transfer it between developers, such as a shared password manager that supports +file uploads. Next, you will need to add the keystore information to your GitHub repository. -Begin by base64-encoding the contents of your `.keystore` file. On a Linux or MacOS command-line prompt, you can use the `base64` command to do so: `base64 user.keystore` (assuming you're in the correct working directory and your keystore file is named `user.keystore`). In Windows PowerShell, the following command will generate the same results: `[convert]::ToBase64String((Get-Content -path "user.keystore" -Encoding byte))` +Begin by base64-encoding the contents of your `.keystore` file. On a Linux or MacOS command-line +prompt, you can use the `base64` command to do so: `base64 user.keystore` (assuming you're in the +correct working directory and your keystore file is named `user.keystore`). In Windows PowerShell, +the following command will generate the same results: +`[convert]::ToBase64String((Get-Content -path "user.keystore" -Encoding byte))` -Add four Repository Secrets in your GitHub repository by going to Settings -> Secrets and clicking the "New repository secret" button in the top-right. `ANDROID_KEYSTORE_BASE64` should contain the base64'd version of your keystore file's contents, and `ANDROID_KEYSTORE_PASS`, `ANDROID_KEYALIAS_NAME`, and `ANDROID_KEYALIAS_PASS` should contain your keystore's password, alias name, and alias password respectively. If you followed the instructions above, the keystore password and alias password will be the same. +Add four Repository Secrets in your GitHub repository by going to Settings -> Secrets and clicking +the "New repository secret" button in the top-right. `ANDROID_KEYSTORE_BASE64` should contain the +base64'd version of your keystore file's contents, and `ANDROID_KEYSTORE_PASS`, +`ANDROID_KEYALIAS_NAME`, and `ANDROID_KEYALIAS_PASS` should contain your keystore's password, alias +name, and alias password respectively. If you followed the instructions above, the keystore password +and alias password will be the same. ### 4. Manually upload a build to Google Play -In order to automate submission to the Google Play store, Google requires you to have already manually uploaded a version of your app to the Google Play Console. You also need to get your app out of the "Draft" status if you want to deploy anything but draft releases. +In order to automate submission to the Google Play store, Google requires you to have already +manually uploaded a version of your app to the Google Play Console. You also need to get your app +out of the "Draft" status if you want to deploy anything but draft releases. -To begin, build your game in Unity. Ensure that the "Build App Bundle (Google Play)" checkbox is checked in the Build Settings, and that the keystore from the previous step is selected in the Publishing Settings section of the Player Settings. If both of these are correct, your build should produce an `.aab` file that has been signed with your upload key. +To begin, build your game in Unity. Ensure that the "Build App Bundle (Google Play)" checkbox is +checked in the Build Settings, and that the keystore from the previous step is selected in the +Publishing Settings section of the Player Settings. If both of these are correct, your build should +produce an `.aab` file that has been signed with your upload key. -In the Google Play Console, select "Internal Testing" from the left-side menu (or an alternate track if you want to do a public production or beta released). Click "Create new release", and drag in an AAB you've manually built in Unity (or an existing GitHub Actions workflow). Fill out the rest of the required fields, then click Save. +In the Google Play Console, select "Internal Testing" from the left-side menu (or an alternate track +if you want to do a public production or beta released). Click "Create new release", and drag in an +AAB you've manually built in Unity (or an existing GitHub Actions workflow). Fill out the rest of +the required fields, then click Save. -Before you can programmatically deploy any release that is not a "Draft" release, you'll need to manually submit your app for review at least once to get it out of "Draft" status. Depending on where you are in the game production lifecycle, you may not want to this during initial setup, but be aware this is something you will need to do before you can use GameCI to release new live updates to a production build. +Before you can programmatically deploy any release that is not a "Draft" release, you'll need to +manually submit your app for review at least once to get it out of "Draft" status. Depending on +where you are in the game production lifecycle, you may not want to this during initial setup, but +be aware this is something you will need to do before you can use GameCI to release new live updates +to a production build. ### 5. Set up Fastlane -At this point, your Google Play Console app listing should be ready to accept programmatic uploads, but you still need to configure Fastlane. Within your project directory, create a directory called `fastlane`, and then create two files within that directory, `Appfile` and `Fastfile`. +At this point, your Google Play Console app listing should be ready to accept programmatic uploads, +but you still need to configure Fastlane. Within your project directory, create a directory called +`fastlane`, and then create two files within that directory, `Appfile` and `Fastfile`. ```ruby title="fastlane/Appfile" for_platform :android do @@ -88,11 +149,16 @@ platform :android do end ``` -If you would like to upload to other tracks (namely, `alpha` or `beta`), you can create additional lanes that look the same as the `:production` and `:internal` lanes except for the name and `track` parameter. Additionally, if you want to create draft releases (which will be necessary until you've manually pushed at least one build through the manual submission process), you will want to switch `release_status` from `completed` to `draft`. +If you would like to upload to other tracks (namely, `alpha` or `beta`), you can create additional +lanes that look the same as the `:production` and `:internal` lanes except for the name and `track` +parameter. Additionally, if you want to create draft releases (which will be necessary until you've +manually pushed at least one build through the manual submission process), you will want to switch +`release_status` from `completed` to `draft`. ### 6. Add jobs to your GitHub workflow -The following workflow establishes two jobs. The first builds your game into an AAB file, and the second uploads that generated bundle to the Play Store. +The following workflow establishes two jobs. The first builds your game into an AAB file, and the +second uploads that generated bundle to the Play Store. ```yaml title=".github/workflows/main.yml" jobs: @@ -125,7 +191,8 @@ jobs: needs: buildForAndroidPlatform env: GOOGLE_PLAY_KEY_FILE: ${{ secrets.GOOGLE_PLAY_KEY_FILE }} - GOOGLE_PLAY_KEY_FILE_PATH: ${{ format('{0}/fastlane/google-fastlane.json', github.workspace) }} + GOOGLE_PLAY_KEY_FILE_PATH: + ${{ format('{0}/fastlane/google-fastlane.json', github.workspace) }} ANDROID_BUILD_FILE_PATH: ${{ format('{0}/build/Android/Android.aab', github.workspace) }} ANDROID_PACKAGE_NAME: ${{ secrets.ANDROID_PACKAGE_NAME }} steps: @@ -156,7 +223,8 @@ jobs: ### 7. Add secrets to your Github repo -On your project's GitHub repo page, add a number of Repository Secrets by going to Settings -> Secrets and clicking the "New repository secret" button in the top-right. +On your project's GitHub repo page, add a number of Repository Secrets by going to Settings -> +Secrets and clicking the "New repository secret" button in the top-right. - **ANDROID_KEYSTORE_BASE64** : Base64 of your keystore, generated in step 3 - **ANDROID_KEYSTORE_PASS**: Password for your keystore @@ -165,13 +233,17 @@ On your project's GitHub repo page, add a number of Repository Secrets by going - **GOOGLE_PLAY_KEY_FILE**: The contents of the Google Account Service .json file from step 2 - **ANDROID_PACKAGE_NAME**: Your application package name (e.g com.company.application) -If you get build failures around the keystore being invalid, _please_ confirm that your keystore base64, alias, and two passwords are correct, as that is a common source of failure. If you want to double-check your keystore has been correctly encoded as valid base64, you can locally recreate your keystore by manually running: +If you get build failures around the keystore being invalid, _please_ confirm that your keystore +base64, alias, and two passwords are correct, as that is a common source of failure. If you want to +double-check your keystore has been correctly encoded as valid base64, you can locally recreate your +keystore by manually running: ```bash cat [keystore file] | base64 --decode > user.keystore` ``` -swapping in the name of a text file containing the base64 value. This will create a new keystore that you can attempt to manually build from in Unity. On Windows, this would be: +swapping in the name of a text file containing the base64 value. This will create a new keystore +that you can attempt to manually build from in Unity. On Windows, this would be: ```powershell [Text.Encoding]::Utf8.GetString([Convert]::FromBase64String('base 64 value')) | Out-File -FilePath .\user.keystore diff --git a/docs/03-github/06-deployment/ios.mdx b/docs/03-github/06-deployment/ios.mdx index 3722faeb..d965a496 100644 --- a/docs/03-github/06-deployment/ios.mdx +++ b/docs/03-github/06-deployment/ios.mdx @@ -1,56 +1,95 @@ # Deploy to the App Store -This guide is intended to help with automating iOS builds and uploads to the App Store. -This guide assumes that you already have experience with [using Xcode for distribution](https://developer.apple.com/documentation/xcode/preparing-your-app-for-distribution). -It is important to be familiar with the manual process, as automating this process can be complicated. +This guide is intended to help with automating iOS builds and uploads to the App Store. This guide +assumes that you already have experience with +[using Xcode for distribution](https://developer.apple.com/documentation/xcode/preparing-your-app-for-distribution). +It is important to be familiar with the manual process, as automating this process can be +complicated. > -- **Note:** Make sure you do all these steps carefully. > -> -- **Note:** You need a Mac environment for doing these steps. -> A Mac is also recommended for debugging any issues with this workflow. +> -- **Note:** You need a Mac environment for doing these steps. A Mac is also recommended for +> debugging any issues with this workflow. ### Conceptual overview -When you build your Unity project for iOS, Unity will produce an Xcode project that needs to be built using Xcode on a Mac. In order to upload your app to the App Store, TestFlight, or a third-party beta distribution service, you will first need to build it in Xcode and then code-sign it. +When you build your Unity project for iOS, Unity will produce an Xcode project that needs to be +built using Xcode on a Mac. In order to upload your app to the App Store, TestFlight, or a +third-party beta distribution service, you will first need to build it in Xcode and then code-sign +it. ### 1. Install Fastlane -[Fastlane](https://docs.fastlane.tools/getting-started/ios/setup/) is a tool that can facilitate building, codesigning, and uploading iOS apps, and is the easiest way to deploy your Unity project to iOS. +[Fastlane](https://docs.fastlane.tools/getting-started/ios/setup/) is a tool that can facilitate +building, codesigning, and uploading iOS apps, and is the easiest way to deploy your Unity project +to iOS. -To configure Fastlane for your GitHub Actions workflow runners, you will need to locally set up a `Gemfile` and `Fastfile` within your project. A `Gemfile` specifies what Ruby dependencies are needed to set up and run Fastlane (which is written in Ruby), and a `Fastfile` will be how you configure your iOS build settings. We will set up the `Gemfile` now, and the `Fastfile` in a later step. +To configure Fastlane for your GitHub Actions workflow runners, you will need to locally set up a +`Gemfile` and `Fastfile` within your project. A `Gemfile` specifies what Ruby dependencies are +needed to set up and run Fastlane (which is written in Ruby), and a `Fastfile` will be how you +configure your iOS build settings. We will set up the `Gemfile` now, and the `Fastfile` in a later +step. -You will need your local machine to have [Ruby](https://www.ruby-lang.org/en/documentation/installation/) installed, as well as Bundler. If you have Ruby installed but are unsure if you have Bundler, you can run the following to install it: +You will need your local machine to have +[Ruby](https://www.ruby-lang.org/en/documentation/installation/) installed, as well as Bundler. If +you have Ruby installed but are unsure if you have Bundler, you can run the following to install it: ```bash gem install bundler ``` -From there, create a file called `Gemfile` in the root of your git repository with following content: +From there, create a file called `Gemfile` in the root of your git repository with following +content: ```ruby title="Gemfile" source "https://rubygems.org" gem "fastlane" ``` -Then run `bundle install`. This will create an additional `Gemfile.lock` file in the root of your project. +Then run `bundle install`. This will create an additional `Gemfile.lock` file in the root of your +project. Commit both `Gemfile` and `Gemfile.lock` to your repo. ### 2. Create and store Codesigning Certificates -Codesigning your iOS app for distribution requires an Apple developer or distribution certificate. Traditionally, allowing multiple developers on a team to build the same app (or allowing builds on a cloud CI system) requires you to either manually share a `.p12` file across all machines that will build the project, or set up a different codesigning identity for each developer or shared build machine. Updating all of these identities and certificates whenever changes are necessary can be a pain point. - -Fastlane includes a tool called [Fastlane Match](https://docs.fastlane.tools/actions/match/) to simplify this process. It will store all of your codesigning identities and certificates securely on the cloud (typically in a private git repo, although you may opt to use a Google Cloud Storage or Amazon S3 bucket), and automatically download the correct certificates whenever Fastlane executes an Xcode build in any environment. Additionally, it can automatically manage your certificates and identities for you, interacting directly with Apple's APIs instead of requiring you to create and manage certificates through the developer portal. - -The Match setup described below is a common workflow that is likely to be a good fit for many GameCI users. However, there are a number of different ways you can set up Match, and we recommend reading the Match [documentation](https://docs.fastlane.tools/actions/match/) and [codesigning guide](https://codesigning.guide) in their entirety. - -If you do not already have a single shared Apple ID to be used by all developers and on all CI environments, create a new one. - -If your Apple Developer account is messy and has lots of invalid, expired, or Xcode-managed profiles and certificates, you may **optionally** want to use Match to initially clean out your old developer portal by running `bundle exec fastlane match development` and `bundle exec fastlane match production`. **This will delete Apple codesigning identities and certificates and may break any existing workflows. It is NOT recommended if your project shares an Apple Developer account with other projects or teams at your company.** +Codesigning your iOS app for distribution requires an Apple developer or distribution certificate. +Traditionally, allowing multiple developers on a team to build the same app (or allowing builds on a +cloud CI system) requires you to either manually share a `.p12` file across all machines that will +build the project, or set up a different codesigning identity for each developer or shared build +machine. Updating all of these identities and certificates whenever changes are necessary can be a +pain point. + +Fastlane includes a tool called [Fastlane Match](https://docs.fastlane.tools/actions/match/) to +simplify this process. It will store all of your codesigning identities and certificates securely on +the cloud (typically in a private git repo, although you may opt to use a Google Cloud Storage or +Amazon S3 bucket), and automatically download the correct certificates whenever Fastlane executes an +Xcode build in any environment. Additionally, it can automatically manage your certificates and +identities for you, interacting directly with Apple's APIs instead of requiring you to create and +manage certificates through the developer portal. + +The Match setup described below is a common workflow that is likely to be a good fit for many GameCI +users. However, there are a number of different ways you can set up Match, and we recommend reading +the Match [documentation](https://docs.fastlane.tools/actions/match/) and +[codesigning guide](https://codesigning.guide) in their entirety. + +If you do not already have a single shared Apple ID to be used by all developers and on all CI +environments, create a new one. + +If your Apple Developer account is messy and has lots of invalid, expired, or Xcode-managed profiles +and certificates, you may **optionally** want to use Match to initially clean out your old developer +portal by running `bundle exec fastlane match development` and +`bundle exec fastlane match production`. **This will delete Apple codesigning identities and +certificates and may break any existing workflows. It is NOT recommended if your project shares an +Apple Developer account with other projects or teams at your company.** Next, create a private git repository to store your certificates. -From the command-line on your Mac, run the following to generate new Development and Distribution certificates. It will ask you for the Apple ID and password of your new shared Apple ID, the URL of the git repository you have just created, and a password to encrypt the contents of the git repo. You will need to use this password later; it's recommended you use a team-wide password manager or similar shared secure keystore to both generate and store this password. +From the command-line on your Mac, run the following to generate new Development and Distribution +certificates. It will ask you for the Apple ID and password of your new shared Apple ID, the URL of +the git repository you have just created, and a password to encrypt the contents of the git repo. +You will need to use this password later; it's recommended you use a team-wide password manager or +similar shared secure keystore to both generate and store this password. ```bash bundle exec fastlane match development @@ -59,15 +98,26 @@ bundle exec fastlane match appstore ### 3. Generate an App Store Connect API Key -In order for Fastlane Match to fetch and validate your codesigning certificates, it needs to authenticate you with Apple. All Apple IDs now require two-factor authentication to be enabled, which means you need to manually enter a 2FA code when logging in. This is fine if you're running match locally on your own machine, but is a problem on an automated CI system. +In order for Fastlane Match to fetch and validate your codesigning certificates, it needs to +authenticate you with Apple. All Apple IDs now require two-factor authentication to be enabled, +which means you need to manually enter a 2FA code when logging in. This is fine if you're running +match locally on your own machine, but is a problem on an automated CI system. -To work around this, you will need to generate an App Store Connect API key, which match can use to authenticate you with Apple without manual 2FA input while running on CI. +To work around this, you will need to generate an App Store Connect API key, which match can use to +authenticate you with Apple without manual 2FA input while running on CI. -Go to https://appstoreconnect.apple.com/access/users and log in. Go to the "Keys" tab and click the plus sign (+) to generate a new set of keys. Enter a name and select "Developer" access. Once it's been generated, click the "Download API key" link, which will download a file. Note you can only do this once. Later on in this guide, you will need the "key ID" from the table row for your newly-generated key, the "issuer ID" displayed at the top of the page, and the downloaded .p8 file. +Go to https://appstoreconnect.apple.com/access/users and log in. Go to the "Keys" tab and click the +plus sign (+) to generate a new set of keys. Enter a name and select "Developer" access. Once it's +been generated, click the "Download API key" link, which will download a file. Note you can only do +this once. Later on in this guide, you will need the "key ID" from the table row for your +newly-generated key, the "issuer ID" displayed at the top of the page, and the downloaded .p8 file. ### 4. Configure Fastlane to build -At this point, you will have a private git repository that contains new valid codesigning identities and certificates. From here, you need to configure Fastlane to know how to build your Xcode project. Within your project directory, create a directory called `fastlane`, and then create two files within that directory, `Appfile` and `Fastfile`. +At this point, you will have a private git repository that contains new valid codesigning identities +and certificates. From here, you need to configure Fastlane to know how to build your Xcode project. +Within your project directory, create a directory called `fastlane`, and then create two files +within that directory, `Appfile` and `Fastfile`. ```ruby title="fastlane/Appfile" for_platform :ios do @@ -148,8 +198,8 @@ platform :ios do end ``` -> -- **Note:** If you add libraries that need `Podfile` (e.g. Firebase) to your project, -> add this line to the beginning of your build step (the block of code starting with `lane :build do`): +> -- **Note:** If you add libraries that need `Podfile` (e.g. Firebase) to your project, add this +> line to the beginning of your build step (the block of code starting with `lane :build do`): ```ruby cocoapods( @@ -160,7 +210,9 @@ end This will install pods and generate the `xcworkspace` for you. -Then change the [`build_app`](http://docs.fastlane.tools/actions/build_app/#build_app) (alias: [`gym`](https://docs.fastlane.tools/actions/gym/)) step at the end of this build phase to use the new `xcworkspace` instead of the old `xcodeproj`: +Then change the [`build_app`](http://docs.fastlane.tools/actions/build_app/#build_app) (alias: +[`gym`](https://docs.fastlane.tools/actions/gym/)) step at the end of this build phase to use the +new `xcworkspace` instead of the old `xcodeproj`: ```ruby build_app( #alias: gym @@ -172,11 +224,19 @@ Then change the [`build_app`](http://docs.fastlane.tools/actions/build_app/#buil ### 5. Add jobs to your GitHub Actions workflow -Building for iOS is a two-step build process. When Unity builds your project for iOS, it generates an Xcode project, which then must be built and code-signed in Xcode via Fastlane. +Building for iOS is a two-step build process. When Unity builds your project for iOS, it generates +an Xcode project, which then must be built and code-signed in Xcode via Fastlane. -This workflow builds your app and submits it to Apple for App Store release. If you want to submit your app for TestFlight distribution, you can create a job that is identical except it runs `bundle exec fastlane beta` instead of `bundle exec fastlane release` during the "Fix File Permissions and Run Fastlane" step. You can build your iOS app without uploading it (e.g. to confirm it builds successfully, or as a preparation step before uploading to an alternative distribution service) by instead running `bundle exec fastlane build`. +This workflow builds your app and submits it to Apple for App Store release. If you want to submit +your app for TestFlight distribution, you can create a job that is identical except it runs +`bundle exec fastlane beta` instead of `bundle exec fastlane release` during the "Fix File +Permissions and Run Fastlane" step. You can build your iOS app without uploading it (e.g. to confirm +it builds successfully, or as a preparation step before uploading to an alternative distribution +service) by instead running `bundle exec fastlane build`. -Please note that Apple will aggressively rate-limit you if you try to upload builds too frequently. We recommend you configure any workflow that submits to the App Store or TestFlight to be manually triggered, or otherwise make sure it won't automatically run more than a few times a day. +Please note that Apple will aggressively rate-limit you if you try to upload builds too frequently. +We recommend you configure any workflow that submits to the App Store or TestFlight to be manually +triggered, or otherwise make sure it won't automatically run more than a few times a day. ```yaml title=".github/workflows/main.yml" jobs: @@ -245,20 +305,43 @@ jobs: ### 6. Add secrets to your GitHub repo -On your project's GitHub repo page, add a number of Repository Secrets by going to Settings -> Secrets and clicking the "New repository secret" button in the top-right. +On your project's GitHub repo page, add a number of Repository Secrets by going to Settings -> +Secrets and clicking the "New repository secret" button in the top-right. -- **APPLE_CONNECT_EMAIL**: Apple Connect email (if using our recommendation to create a single shared developer Apple ID for Fastlane Match, this will be the same as `APPLE_DEVELOPER_EMAIL`) +- **APPLE_CONNECT_EMAIL**: Apple Connect email (if using our recommendation to create a single + shared developer Apple ID for Fastlane Match, this will be the same as `APPLE_DEVELOPER_EMAIL`) - **APPLE_DEVELOPER_EMAIL**: Your Apple ID -- **APPLE_TEAM_ID**: Team Id from your [Apple Developer Account - Membership Details](https://developer.apple.com/account/#/membership/) -- **MATCH_URL**: Https url for the private git repo to which `fastlane match appstore` uploaded certificates. -- **MATCH_PERSONAL_ACCESS_TOKEN**: GitHub [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with full repo access to MATCH_URL +- **APPLE_TEAM_ID**: Team Id from your + [Apple Developer Account - Membership Details](https://developer.apple.com/account/#/membership/) +- **MATCH_URL**: Https url for the private git repo to which `fastlane match appstore` uploaded + certificates. +- **MATCH_PERSONAL_ACCESS_TOKEN**: GitHub + [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) + with full repo access to MATCH_URL - **MATCH_PASSWORD**: The password you set when configuring Fastlane Match. -- **APPSTORE_KEY_ID, APPSTORE_ISSUER_ID, APPSTORE_P8**: Your App Store Connect API keys from the previous step. `APPSTORE_KEY_ID` is the "Key ID" from the table row, `APPSTORE_ISSUER_ID` is your issuer ID from the top of the page, and `APPSTORE_P8` is the entire contents of the `.p8` file you downloaded, starting with `-----BEGIN PRIVATE KEY-----` and ending with `-----END PRIVATE KEY-----`. +- **APPSTORE_KEY_ID, APPSTORE_ISSUER_ID, APPSTORE_P8**: Your App Store Connect API keys from the + previous step. `APPSTORE_KEY_ID` is the "Key ID" from the table row, `APPSTORE_ISSUER_ID` is your + issuer ID from the top of the page, and `APPSTORE_P8` is the entire contents of the `.p8` file you + downloaded, starting with `-----BEGIN PRIVATE KEY-----` and ending with + `-----END PRIVATE KEY-----`. ### 7. Confirming your Unity and App Store Connect settings -At this point, if you have previously set up your app for manual iOS builds and TestFlight/App Store distribution, your GitHub Actions workflow will likely complete successfully. If that is not the case, there are a few more steps to finish setup. - -In Unity, you will need to ensure that your [application icon(s)](https://docs.unity3d.com/Manual/class-PlayerSettingsiOS.html#icon) are set, as applications without the correct icons will generate an error while uploading to TestFlight. Additionally, set your Bundle Identifier and Signing Team ID in the [iOS Player settings - Identification settings](https://docs.unity3d.com/Manual/class-PlayerSettingsiOS.html#Identification). The bundle identifier needs to be the same as you have set for the `IOS_BUNDLE_ID` repository secret. If you don't know your Signing Team ID, you can find it by going to https://developer.apple.com/account/#!/membership while logged in, and it will be the "Team ID" listed. - -In order to upload a build to Apple, an entry for your app needs to exist in your team's [App Store Connect](https://appstoreconnect.apple.com/). From the App Store Connect homepage, select "My Apps", and create or confirm the existence of an App with the same bundle identifier you are using in your Unity build settings and the `IOS_BUNDLE_ID` GitHub repository secret. +At this point, if you have previously set up your app for manual iOS builds and TestFlight/App Store +distribution, your GitHub Actions workflow will likely complete successfully. If that is not the +case, there are a few more steps to finish setup. + +In Unity, you will need to ensure that your +[application icon(s)](https://docs.unity3d.com/Manual/class-PlayerSettingsiOS.html#icon) are set, as +applications without the correct icons will generate an error while uploading to TestFlight. +Additionally, set your Bundle Identifier and Signing Team ID in the +[iOS Player settings - Identification settings](https://docs.unity3d.com/Manual/class-PlayerSettingsiOS.html#Identification). +The bundle identifier needs to be the same as you have set for the `IOS_BUNDLE_ID` repository +secret. If you don't know your Signing Team ID, you can find it by going to +https://developer.apple.com/account/#!/membership while logged in, and it will be the "Team ID" +listed. + +In order to upload a build to Apple, an entry for your app needs to exist in your team's +[App Store Connect](https://appstoreconnect.apple.com/). From the App Store Connect homepage, select +"My Apps", and create or confirm the existence of an App with the same bundle identifier you are +using in your Unity build settings and the `IOS_BUNDLE_ID` GitHub repository secret. diff --git a/docs/03-github/06-deployment/steam.mdx b/docs/03-github/06-deployment/steam.mdx index 8adc8fcc..1ad63992 100644 --- a/docs/03-github/06-deployment/steam.mdx +++ b/docs/03-github/06-deployment/steam.mdx @@ -1,10 +1,13 @@ # Deploy to Steam -This page assumes you are registered as a [partner](https://partner.steamgames.com/) with Steam and that you are familiar with [using SteamPipe to upload your builds to Steam](https://partner.steamgames.com/doc/sdk/uploading). +This page assumes you are registered as a [partner](https://partner.steamgames.com/) with Steam and +that you are familiar with +[using SteamPipe to upload your builds to Steam](https://partner.steamgames.com/doc/sdk/uploading). ### 1. Create a Steam Build Account -Create a specialised builder account that only has access to `Edit App Metadata` and `Publish App Changes To Steam`. +Create a specialised builder account that only has access to `Edit App Metadata` and +`Publish App Changes To Steam`. See [the docs](https://partner.steamgames.com/doc/sdk/uploading#Build_Account). @@ -31,7 +34,9 @@ jobs: - uses: actions/cache@v2 with: path: Library - key: Library-${{ matrix.targetPlatform }}-${{ hashFiles('Assets/**', 'Packages/**', 'ProjectSettings/**') }} + key: + Library-${{ matrix.targetPlatform }}-${{ hashFiles('Assets/**', 'Packages/**', + 'ProjectSettings/**') }} restore-keys: | Library-${{ matrix.targetPlatform }}- Library- @@ -83,21 +88,33 @@ jobs: - **STEAM_USERNAME**: The username of the Steam Build Account that you created in step 1. - **STEAM_PASSWORD**: The password of the Steam Build Account that you created in step 1. -- **STEAM_CONFIG_VDF**, **STEAM_SSFN_FILE_NAME**, and **STEAM_SSFN_FILE_CONTENTS**: See the step "Setup Steam Authentication" below. -- **STEAM_APP_ID**: The identifier of your app on steam. You can find it on your [dashboard](https://partner.steamgames.com/dashboard). +- **STEAM_CONFIG_VDF**, **STEAM_SSFN_FILE_NAME**, and **STEAM_SSFN_FILE_CONTENTS**: See the step + "Setup Steam Authentication" below. +- **STEAM_APP_ID**: The identifier of your app on steam. You can find it on your + [dashboard](https://partner.steamgames.com/dashboard). ### 4. Setup Steam Authentication -Deploying to Steam requires using Multi-Factor Authentication (MFA) through Steam Guard. -This means that simply using username and password isn't enough to authenticate with Steam. -However, it is possible to go through the MFA process only once by setting up GitHub Secrets for configVdf, ssfnFileName, and ssfnFileContents with these steps: - -1. Install [Valve's offical steamcmd](https://partner.steamgames.com/doc/sdk/uploading#1) on your local machine. All following steps will also be done on your local machine. -1. Try to login with `steamcmd +login +quit`, which may prompt for the MFA code. If so, type in the MFA code that was emailed to your builder account's email address. -1. Validate that the MFA process is complete by running `steamcmd +login +quit` again. It should not ask for the MFA code again. -1. The folder from which you run `steamcmd` will now contain an updated `config/config.vdf` file. Use `cat config/config.vdf | base64 > config_base64.txt` to encode the file. Copy the contents of `config_base64.txt` to a GitHub Secret `STEAM_CONFIG_VDF`. -1. That folder will also contain two files whose names look like `ssfn`, **but one of them is a hidden file**. [Find the hidden one](https://support.microsoft.com/en-us/windows/view-hidden-files-and-folders-in-windows-97fbc472-c603-9d90-91d0-1166d1d9f4b5), then copy the name of that file to a GitHub Secret `STEAM_SSFN_FILE_NAME`. -1. Use `cat | base64 > ssfn_base64.txt` to encode the contents of the hidden ssfn file. Copy the contents of `ssfn_base64.txt` to a GitHub Secret `STEAM_SSFN_FILE_CONTENTS`. +Deploying to Steam requires using Multi-Factor Authentication (MFA) through Steam Guard. This means +that simply using username and password isn't enough to authenticate with Steam. However, it is +possible to go through the MFA process only once by setting up GitHub Secrets for configVdf, +ssfnFileName, and ssfnFileContents with these steps: + +1. Install [Valve's offical steamcmd](https://partner.steamgames.com/doc/sdk/uploading#1) on your + local machine. All following steps will also be done on your local machine. +1. Try to login with `steamcmd +login +quit`, which may prompt for the MFA + code. If so, type in the MFA code that was emailed to your builder account's email address. +1. Validate that the MFA process is complete by running + `steamcmd +login +quit` again. It should not ask for the MFA code again. +1. The folder from which you run `steamcmd` will now contain an updated `config/config.vdf` file. + Use `cat config/config.vdf | base64 > config_base64.txt` to encode the file. Copy the contents of + `config_base64.txt` to a GitHub Secret `STEAM_CONFIG_VDF`. +1. That folder will also contain two files whose names look like `ssfn`, **but one of them + is a hidden file**. + [Find the hidden one](https://support.microsoft.com/en-us/windows/view-hidden-files-and-folders-in-windows-97fbc472-c603-9d90-91d0-1166d1d9f4b5), + then copy the name of that file to a GitHub Secret `STEAM_SSFN_FILE_NAME`. +1. Use `cat | base64 > ssfn_base64.txt` to encode the contents of the hidden ssfn + file. Copy the contents of `ssfn_base64.txt` to a GitHub Secret `STEAM_SSFN_FILE_CONTENTS`. ### 5. Additional Configuration @@ -123,12 +140,16 @@ If your appId is 125000 then the depots 125001 ... 125009 will be assumed. #### firstDepotId -You can use this to override the ID of the first depot in case the IDs do not start as described in depot[X]Path (e.g. for DLCs). +You can use this to override the ID of the first depot in case the IDs do not start as described in +depot[X]Path (e.g. for DLCs). -If your firstDepotId is 125000 then, regardless of the used appId, the depots 125000 ... 125008 will be assumed. +If your firstDepotId is 125000 then, regardless of the used appId, the depots 125000 ... 125008 will +be assumed. #### releaseBranch The branch within steam that this build will be automatically put live on. -Note that the `default` branch [has been observed to not work](https://github.com/game-ci/steam-deploy/issues/19) as a release branch, presumably because it is potentially dangerous. +Note that the `default` branch +[has been observed to not work](https://github.com/game-ci/steam-deploy/issues/19) as a release +branch, presumably because it is potentially dangerous. diff --git a/docs/05-gitlab/01-getting-started.mdx b/docs/05-gitlab/01-getting-started.mdx index ccfb855e..1108389f 100644 --- a/docs/05-gitlab/01-getting-started.mdx +++ b/docs/05-gitlab/01-getting-started.mdx @@ -2,7 +2,8 @@ import Video from '../../src/components/video/video'; # Getting started -This guide will demonstrate how to setup build and test automation for your Unity project hosted on gitlab using gitlab-ci. +This guide will demonstrate how to setup build and test automation for your Unity project hosted on +gitlab using gitlab-ci. ## Overall steps @@ -14,15 +15,21 @@ This guide will demonstrate how to setup build and test automation for your Unit ## First time using Gitlab CI? -Read the official documentation about [Getting started with GitLab CI/CD](https://docs.gitlab.com/ce/ci/quick_start/). +Read the official documentation about +[Getting started with GitLab CI/CD](https://docs.gitlab.com/ce/ci/quick_start/). Any subsequent steps assume you have read the above. ## Supported versions -The [unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) is based on [unity3d](https://github.com/game-ci/docker/) docker images from [game-ci](https://github.com/game-ci). Any version in the [docker hub `unityci/editor` tags list](https://hub.docker.com/r/unityci/editor/tags) can be used to test and build projects. +The [unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) is +based on [unity3d](https://github.com/game-ci/docker/) docker images from +[game-ci](https://github.com/game-ci). Any version in the +[docker hub `unityci/editor` tags list](https://hub.docker.com/r/unityci/editor/tags) can be used to +test and build projects. -It's generally considered good practice to use the same Unity version for your CI/CD setup as you do to develop your project. +It's generally considered good practice to use the same Unity version for your CI/CD setup as you do +to develop your project. ## Video tutorial @@ -32,16 +39,25 @@ It's generally considered good practice to use the same Unity version for your C ### I don't have a Unity project yet -1. Fork [the unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) +1. Fork + [the unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) 1. Clone the fork you just created locally 1. Continue to activation instructions ### I already have my own Unity project -1. Clone [the unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) -1. Copy [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) to the root of your repository, [`Assets/Scripts/Editor/BuildCommand.cs`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/Assets/Scripts/Editor/BuildCommand.cs) and [`ci` folder](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/ci) to your project: +1. Clone + [the unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) +1. Copy + [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) + to the root of your repository, + [`Assets/Scripts/Editor/BuildCommand.cs`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/Assets/Scripts/Editor/BuildCommand.cs) + and [`ci` folder](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/ci) to your + project: -Assuming you've cloned the example project in the parent folder of your project, and your Unity project is at the root of your repository, execute these commands from the root folder of your project: +Assuming you've cloned the example project in the parent folder of your project, and your Unity +project is at the root of your repository, execute these commands from the root folder of your +project: ```bash mkdir -p Assets/Scripts/Editor/ @@ -50,6 +66,11 @@ cp -r ../unity3d-gitlab-ci-example/ci ./ cp ../unity3d-gitlab-ci-example/Assets/Scripts/Editor/BuildCommand.cs ./Assets/Scripts/Editor/ ``` -1. Open and edit the [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) you copied to your project and update [the variables](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml#L7-13) with the versions you need. Your Unity project version can be found in `ProjectSettings/ProjectVersion.txt`. +1. Open and edit the + [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) + you copied to your project and update + [the variables](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml#L7-13) + with the versions you need. Your Unity project version can be found in + `ProjectSettings/ProjectVersion.txt`. 1. If your Unity project is not at the root of your repository, also update UNITY_DIR variable. 1. Continue to activation instructions diff --git a/docs/05-gitlab/02-activation.mdx b/docs/05-gitlab/02-activation.mdx index 7ae2da08..ba4cb71b 100644 --- a/docs/05-gitlab/02-activation.mdx +++ b/docs/05-gitlab/02-activation.mdx @@ -1,16 +1,21 @@ # Activation -There are a few methods available, if you're using gitlab-ci, the easiest method in the current documentation is using gitlab-ci. +There are a few methods available, if you're using gitlab-ci, the easiest method in the current +documentation is using gitlab-ci. ## Unity Personal ### a. Using gitlab-ci -Once you've added all required files to your project (mainly [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml)), there should be a manual step that can be triggered for activation. +Once you've added all required files to your project (mainly +[`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml)), +there should be a manual step that can be triggered for activation. -1. Visit your project's settings > CI/CD > Variables and add `UNITY_USERNAME` and `UNITY_PASSWORD` with your credentials. Make sure to use your Unity3d _email address_ for `UNITY_USERNAME`. +1. Visit your project's settings > CI/CD > Variables and add `UNITY_USERNAME` and `UNITY_PASSWORD` + with your credentials. Make sure to use your Unity3d _email address_ for `UNITY_USERNAME`. 1. Push your first commit to your project and visit CI/CD Pipelines. -1. Locate your latest job, there should be a `play` button, click on it and click `get-activation-file` +1. Locate your latest job, there should be a `play` button, click on it and click + `get-activation-file` 1. Wait for the job to run and follow instructions in the console ### b. Locally @@ -20,7 +25,9 @@ All you need is [docker](https://www.docker.com/) installed on your machine. 1. Clone this project 2. Pull the docker image and run bash inside, passing Unity username and password to env - _hint: you should write this to a shell script and execute the shell script so you don't have your credentials stored in your bash history_. Also make sure you use your Unity3d _email address_ for `UNITY_USERNAME` env var. + _hint: you should write this to a shell script and execute the shell script so you don't have + your credentials stored in your bash history_. Also make sure you use your Unity3d _email + address_ for `UNITY_USERNAME` env var. ```bash UNITY_VERSION=2020.1.11f1 @@ -67,22 +74,33 @@ All you need is [docker](https://www.docker.com/) installed on your machine. > Can't activate Unity: No sufficient permissions while processing request HTTP error code 401 - Make sure your credentials are valid. You may try to disable 2FA in your account and try again. Once done, you should enable 2FA again for security reasons. See [#11](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/11) for more details. + Make sure your credentials are valid. You may try to disable 2FA in your account and try again. + Once done, you should enable 2FA again for security reasons. See + [#11](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/11) for more details. 5. Copy xml content and save as `unity3d.alf` 6. Open https://license.unity3d.com/manual and answer questions 7. Upload `unity3d.alf` for manual activation 8. Download `Unity_v2018.x.ulf` (`Unity_v2019.x.ulf` for 2019 versions) -9. Copy the content of `Unity_v2018.x.ulf` license file to your CI's environment variable `UNITY_LICENSE`. - _Note: if you are doing this on Windows, chances are the [line endings will be wrong as explained here](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/5#note_95831816). Luckily for you, [`.gitlab-ci.yml`](https://github.com/game-ci/unity3d-ci-example/blob/main/.gitlab-ci.yml) of the example project solves this by removing `\r` character from the ENV variable so you'll be alright_ - [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) will then place the `UNITY_LICENSE` to the right place before running tests or creating the builds. +9. Copy the content of `Unity_v2018.x.ulf` license file to your CI's environment variable + `UNITY_LICENSE`. _Note: if you are doing this on Windows, chances are the + [line endings will be wrong as explained here](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/5#note_95831816). + Luckily for you, + [`.gitlab-ci.yml`](https://github.com/game-ci/unity3d-ci-example/blob/main/.gitlab-ci.yml) of the + example project solves this by removing `\r` character from the ENV variable so you'll be + alright_ + [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) + will then place the `UNITY_LICENSE` to the right place before running tests or creating the + builds. ## Unity Plus/Pro 1. Clone this project 2. Pull the docker image and run bash inside, passing Unity username and password to env - _hint: you should write this to a shell script and execute the shell script so you don't have your credentials stored in your bash history_. Also make sure you use your Unity3d _email address_ for `UNITY_USERNAME` env var. + _hint: you should write this to a shell script and execute the shell script so you don't have + your credentials stored in your bash history_. Also make sure you use your Unity3d _email + address_ for `UNITY_USERNAME` env var. ```bash UNITY_VERSION=2020.1.11f1 @@ -113,7 +131,14 @@ All you need is [docker](https://www.docker.com/) installed on your machine. ``` 4. Wait for the command to finish without errors -5. Obtain the contents of the license file by running `cat /root/.local/share/unity3d/Unity/Unity_lic.ulf` -6. Copy the content to your CI's environment variable `UNITY_LICENSE`. - _Note: if you are doing this on windows, chances are the [line endings will be wrong as explained here](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/5#note_95831816). Luckily for you, [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) solves this by removing `\r` character from the env variable so you'll be alright_ - [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) will then place the `UNITY_LICENSE` to the right place before running tests or creating the builds. +5. Obtain the contents of the license file by running + `cat /root/.local/share/unity3d/Unity/Unity_lic.ulf` +6. Copy the content to your CI's environment variable `UNITY_LICENSE`. _Note: if you are doing this + on windows, chances are the + [line endings will be wrong as explained here](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/5#note_95831816). + Luckily for you, + [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) + solves this by removing `\r` character from the env variable so you'll be alright_ + [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) + will then place the `UNITY_LICENSE` to the right place before running tests or creating the + builds. diff --git a/docs/05-gitlab/03-example-project.mdx b/docs/05-gitlab/03-example-project.mdx index 10c567e0..3b7c3db5 100644 --- a/docs/05-gitlab/03-example-project.mdx +++ b/docs/05-gitlab/03-example-project.mdx @@ -2,20 +2,34 @@ ## About -[The `unity3d-gitlab-ci-example` project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) uses an updated version of the [Unity's Creator Kit: RPG free asset](https://assetstore.unity.com/packages/templates/tutorials/creator-kit-rpg-149309) which is not affiliated with this project at all. Feel free to explore it, dialogs are a bit different ;) - -The example project is a Proof of Concept to **run unity3d tests and builds inside a CI** using **[game-ci/docker unity editor docker images](https://github.com/game-ci/docker)**. It currently creates builds for Windows, Linux, macOS, webgl, Linux IL2cpp, Android and iOS Xcode project. The webgl build is published by the CI to [gitlab-pages](https://about.gitlab.com/features/pages/). **You can try the built project on [the published gitlab-pages](https://game-ci.gitlab.io/unity3d-gitlab-ci-example/)**. +[The `unity3d-gitlab-ci-example` project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) +uses an updated version of the +[Unity's Creator Kit: RPG free asset](https://assetstore.unity.com/packages/templates/tutorials/creator-kit-rpg-149309) +which is not affiliated with this project at all. Feel free to explore it, dialogs are a bit +different ;) + +The example project is a Proof of Concept to **run unity3d tests and builds inside a CI** using +**[game-ci/docker unity editor docker images](https://github.com/game-ci/docker)**. It currently +creates builds for Windows, Linux, macOS, webgl, Linux IL2cpp, Android and iOS Xcode project. The +webgl build is published by the CI to [gitlab-pages](https://about.gitlab.com/features/pages/). +**You can try the built project on +[the published gitlab-pages](https://game-ci.gitlab.io/unity3d-gitlab-ci-example/)**. ## Git remotes -[The `unity3d-gitlab-ci-example` project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) is hosted on multiple remotes to provide examples for [Gitlab-CI](https://about.gitlab.com/product/continuous-integration/), [Travis CI](https://travis-ci.org/) and [CircleCI](https://circleci.com/) +[The `unity3d-gitlab-ci-example` project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) is +hosted on multiple remotes to provide examples for +[Gitlab-CI](https://about.gitlab.com/product/continuous-integration/), +[Travis CI](https://travis-ci.org/) and [CircleCI](https://circleci.com/) - [github](https://github.com/game-ci/unity3d-ci-example) - [gitlab](https://gitlab.com/game-ci/unity3d-gitlab-ci-example) ## How to run scripts locally -You can execute the local scripts and specify the path of your Unity executable using `UNITY_EXECUTABLE`. You may try this in your project before you setup the whole CI, so you confirm it works with your current unity version 👍. +You can execute the local scripts and specify the path of your Unity executable using +`UNITY_EXECUTABLE`. You may try this in your project before you setup the whole CI, so you confirm +it works with your current unity version 👍. ## Test diff --git a/docs/05-gitlab/04-custom-build-options.mdx b/docs/05-gitlab/04-custom-build-options.mdx index f5615234..82e66314 100644 --- a/docs/05-gitlab/04-custom-build-options.mdx +++ b/docs/05-gitlab/04-custom-build-options.mdx @@ -4,9 +4,12 @@ First, you need to understand how build options are passed to the build. ## Build command -See [Assets/Scripts/Editor/BuildCommand.cs](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/Assets/Scripts/Editor/BuildCommand.cs). +See +[Assets/Scripts/Editor/BuildCommand.cs](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/Assets/Scripts/Editor/BuildCommand.cs). -This is the script used during `Unity` command line execution. It is passed to the [`-executeMethod ` command line parameter](https://docs.unity3d.com/Manual/CommandLineArguments.html) like this: +This is the script used during `Unity` command line execution. It is passed to the +[`-executeMethod ` command line parameter](https://docs.unity3d.com/Manual/CommandLineArguments.html) +like this: ```bash unity-editor \ @@ -19,7 +22,8 @@ You need to have this file in your project in order to build your project in the ### Workflow file -See [.gitlab-ci.yml](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml). +See +[.gitlab-ci.yml](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml). You can add `BuildOptions` per target by adding environment variable `BuildOptions`. @@ -38,4 +42,5 @@ If you would like to use several `BuildOptions`, you have to separate all values BuildOptions: AcceptExternalModificationsToPlayer,CompressTextures,ConnectToHost ``` -See [Unity3d `BuildOptions` reference](https://docs.unity3d.com/ScriptReference/BuildOptions.html) for allowed values. +See [Unity3d `BuildOptions` reference](https://docs.unity3d.com/ScriptReference/BuildOptions.html) +for allowed values. diff --git a/docs/05-gitlab/05-tests.mdx b/docs/05-gitlab/05-tests.mdx index 40427b82..849e9769 100644 --- a/docs/05-gitlab/05-tests.mdx +++ b/docs/05-gitlab/05-tests.mdx @@ -2,7 +2,8 @@ ## Unity Tests -Unity supports two kinds of tests (`editmode` and `playmode`). The example project supports both. More information and documentation concerning Unity tests can be found here: +Unity supports two kinds of tests (`editmode` and `playmode`). The example project supports both. +More information and documentation concerning Unity tests can be found here: [Unity Test Framework](https://docs.unity3d.com/Packages/com.unity.test-framework@1.1/manual/index.html) ## Example Project Test files diff --git a/docs/05-gitlab/06-deployment/android.mdx b/docs/05-gitlab/06-deployment/android.mdx index d3c05c96..7c697057 100644 --- a/docs/05-gitlab/06-deployment/android.mdx +++ b/docs/05-gitlab/06-deployment/android.mdx @@ -1,9 +1,13 @@ # Android -Before `2018.4.8f1` for 2018 versions and before `2019.2.4f1` for 2019 versions, you will need a specific Unity license (because that is not the same docker image). Add the content of your specific Unity license in your CI's environment variable : `UNITY_LICENSE_CONTENT_ANDROID`. _This is not required anymore now that images share a base image [See related change](https://gitlab.com/game-ci/unity3d/merge_requests/63)_ +Before `2018.4.8f1` for 2018 versions and before `2019.2.4f1` for 2019 versions, you will need a +specific Unity license (because that is not the same docker image). Add the content of your specific +Unity license in your CI's environment variable : `UNITY_LICENSE_CONTENT_ANDROID`. _This is not +required anymore now that images share a base image +[See related change](https://gitlab.com/game-ci/unity3d/merge_requests/63)_ -By default the apk is not signed and the build will use the Unity's default debug key. -For _security reasons_, **you should not add your keystore to git**. +By default the apk is not signed and the build will use the Unity's default debug key. For _security +reasons_, **you should not add your keystore to git**. ## Encode your keystore @@ -18,14 +22,17 @@ Copy the result to your CI's environment variable `ANDROID_KEYSTORE_BASE64` Add following environment variables: - `KEYSTORE_PASS`: Keystore pass -- `KEY_ALIAS_NAME`: Keystore alias name to use (if not set, the program will use the alias name set in Project's PlayerSettings) +- `KEY_ALIAS_NAME`: Keystore alias name to use (if not set, the program will use the alias name set + in Project's PlayerSettings) - `KEY_ALIAS_PASS`: Keystore alias pass to use -Note about _keystore security_, if you would like to use another solution for storage, see [Where to Store Android KeyStore File in CI/CD Cycle?](https://android.jlelse.eu/where-to-store-android-keystore-file-in-ci-cd-cycle-2365f4e02e57). +Note about _keystore security_, if you would like to use another solution for storage, see +[Where to Store Android KeyStore File in CI/CD Cycle?](https://android.jlelse.eu/where-to-store-android-keystore-file-in-ci-cd-cycle-2365f4e02e57). ### Android app bundle -`BUILD_APP_BUNDLE` env var is defined in `gitlab-ci.yml`. Set it to `true` to build an `.aab` file. Note: to build an android app bundle, you need an image with **Android NDK**. +`BUILD_APP_BUNDLE` env var is defined in `gitlab-ci.yml`. Set it to `true` to build an `.aab` file. +Note: to build an android app bundle, you need an image with **Android NDK**. See [related issue gableroux/unity3d#61](https://gitlab.com/game-ci/unity3d/issues/61) @@ -35,20 +42,26 @@ The bundle version code must be increment for each deployed build. To simplify the process, the `BUNDLE_VERSION_CODE` env var is used and set as bundle version code. -Currently, for gitlab, `BUNDLE_VERSION_CODE = $CI_PIPELINE_IID`. [Documentation](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) +Currently, for gitlab, `BUNDLE_VERSION_CODE = $CI_PIPELINE_IID`. +[Documentation](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) If you use another CI solution, set a CI env var incrementing for each pipeline. ### Fastlane supply (deployement) -Follow [setup instructions](https://docs.fastlane.tools/actions/supply/) to get a google play console token, then, add the content to env var `GPC_TOKEN`. +Follow [setup instructions](https://docs.fastlane.tools/actions/supply/) to get a google play +console token, then, add the content to env var `GPC_TOKEN`. -Uncomment the `#deploy-android` job in gitlab-ci.yml and replace `com.youcompany.yourgame` by your package name. +Uncomment the `#deploy-android` job in gitlab-ci.yml and replace `com.youcompany.yourgame` by your +package name. -You can change the track `internal` to `alpha`, `beta` or `production` (Note: if you are using the `internal` track you will also have to mark your release as a draft in the `fastlane supply` command using `--release_status draft`). +You can change the track `internal` to `alpha`, `beta` or `production` (Note: if you are using the +`internal` track you will also have to mark your release as a draft in the `fastlane supply` command +using `--release_status draft`). **Gemfile** -You will also need to add a Gemfile to your project to install the `fastlane` gem. Something like the following: +You will also need to add a Gemfile to your project to install the `fastlane` gem. Something like +the following: ``` source "https://rubygems.org" @@ -56,9 +69,12 @@ source "https://rubygems.org" gem "fastlane" ``` -and then copy the file to the current directory prior to installing the gem. eg `cp $CI_PROJECT_DIR/Gemfile .`. +and then copy the file to the current directory prior to installing the gem. eg +`cp $CI_PROJECT_DIR/Gemfile .`. -That is the simplest way with command line but you can also make `fastlane/Fastfile` and `fastlane/Appfile`, with the following command after building a temporary gradle project (export gradle project option in Unity build settings): +That is the simplest way with command line but you can also make `fastlane/Fastfile` and +`fastlane/Appfile`, with the following command after building a temporary gradle project (export +gradle project option in Unity build settings): ```bash fastlane init @@ -70,4 +86,6 @@ Then run the following command: fastlane supply init ``` -and update all metadata, images, changelogs, etc... These will be uploaded to the store everytime. Refer to [fastlane supply documentation](https://docs.fastlane.tools/actions/supply/) for more details. +and update all metadata, images, changelogs, etc... These will be uploaded to the store everytime. +Refer to [fastlane supply documentation](https://docs.fastlane.tools/actions/supply/) for more +details. diff --git a/docs/05-gitlab/06-deployment/ios.mdx b/docs/05-gitlab/06-deployment/ios.mdx index 0f11c842..41154bc0 100644 --- a/docs/05-gitlab/06-deployment/ios.mdx +++ b/docs/05-gitlab/06-deployment/ios.mdx @@ -25,26 +25,31 @@ brew install fastlane 1. Fill the field `Signing Team ID` 1. Ensure `Automatically Sign` is unchecked 1. iOS Provisioning Profile - 1. `ProfileID`: `match AppStore your_bundle_identifier` _Replace `your_bundle_identifier` by yours_ + 1. `ProfileID`: `match AppStore your_bundle_identifier` _Replace `your_bundle_identifier` by + yours_ 1. `ProfileType`: `Distribution` ## XCode project Make a first iOS build using your mac from Unity, that will create an xcode project. Ensure you target the same path as the CI. -Ex: if you let `BUILD_NAME: ExampleProjectName` in `.gitlab-ci.yml`, your xcode project must be at the root of the following path: `.\Builds\iOS\ExampleProjectName\` +Ex: if you let `BUILD_NAME: ExampleProjectName` in `.gitlab-ci.yml`, your xcode project must be at +the root of the following path: `.\Builds\iOS\ExampleProjectName\` ## App on portal -Make sure that you have setup your app on the Apple Developer Portal and the App Store Connect or use [fastlane produce](https://docs.fastlane.tools/actions/produce/) to create it. +Make sure that you have setup your app on the Apple Developer Portal and the App Store Connect or +use [fastlane produce](https://docs.fastlane.tools/actions/produce/) to create it. ## Fastlane initialization -Open the terminal at the same path then run `fastlane init`, follow instructions to generate Appfile and default Fastfile. +Open the terminal at the same path then run `fastlane init`, follow instructions to generate Appfile +and default Fastfile. ## Provisioning profile -Run `fastlane match init`, follow instructions, select `appstore` provisioning profile type. ([Documentation](https://docs.fastlane.tools/actions/match/)) +Run `fastlane match init`, follow instructions, select `appstore` provisioning profile type. +([Documentation](https://docs.fastlane.tools/actions/match/)) ## Make lane @@ -66,7 +71,8 @@ platform :ios do end ``` -Note about `upload_to_testflight`: Change "Team" to your internal tester or remove `(groups:["Team"])` if you want set manually who can test the build +Note about `upload_to_testflight`: Change "Team" to your internal tester or remove +`(groups:["Team"])` if you want set manually who can test the build ### Related documentation @@ -114,9 +120,11 @@ sudo chmod +x /usr/local/bin/gitlab-runner - [Source (if you would like to check)](https://docs.gitlab.com/runner/install/osx.html) -Go to your project gitlab page, then go to `settings` -> `CI/CD` -> `Runners` -> `Specitic Runners` -> `Set up a specific Runner manually` -> take note of the token +Go to your project gitlab page, then go to `settings` -> `CI/CD` -> `Runners` -> `Specitic Runners` +-> `Set up a specific Runner manually` -> take note of the token -[Follow these instructions](https://docs.gitlab.com/runner/register/index.html) to register your mac as a gitlab-runner for your specific project. +[Follow these instructions](https://docs.gitlab.com/runner/register/index.html) to register your mac +as a gitlab-runner for your specific project. Follow **macOS** instructions **without** sudo command for registration. - Tags: set `mac,ios` @@ -132,4 +140,5 @@ gitlab-runner start Runner is installed and will be run after a system reboot. -Now, you can uncomment the job `build-and-deploy-ios` in `.gitlab-ci.yml` to make the app build and deployement work. +Now, you can uncomment the job `build-and-deploy-ios` in `.gitlab-ci.yml` to make the app build and +deployement work. diff --git a/docs/08-docker/01-docker-images.mdx b/docs/08-docker/01-docker-images.mdx index e9d42e71..fb0718d2 100644 --- a/docs/08-docker/01-docker-images.mdx +++ b/docs/08-docker/01-docker-images.mdx @@ -1,20 +1,18 @@ # GameCI Docker images for Unity -All projects for Unity in GameCI use -[`game-ci/docker`](https://github.com/game-ci/docker/) -docker images which are specialised for CI and command-line use. These images are published on +All projects for Unity in GameCI use [`game-ci/docker`](https://github.com/game-ci/docker/) docker +images which are specialised for CI and command-line use. These images are published on [docker hub as `unityci/editor`](https://hub.docker.com/r/unityci/editor/tags?page=1&ordering=last_updated). They are established empirically by the community and come forth from the -[`gableroux/unity3d`](https://gitlab.com/game-ci/unity3d/) -project. It was previously published on -[docker hub as `gableroux/unity3d`](https://hub.docker.com/r/gableroux/unity3d/). -**There won't be any new versions releases for `gableroux/unity3d` as it is now deprecated in favor of +[`gableroux/unity3d`](https://gitlab.com/game-ci/unity3d/) project. It was previously published on +[docker hub as `gableroux/unity3d`](https://hub.docker.com/r/gableroux/unity3d/). **There won't be +any new versions releases for `gableroux/unity3d` as it is now deprecated in favor of [`game-ci/docker`](https://github.com/game-ci/docker/).** Images for newly released Unity editor versions are added almost immediately to -[`game-ci/docker`](https://github.com/game-ci/docker/) -. This process is automated, please allow a few hours. +[`game-ci/docker`](https://github.com/game-ci/docker/) . This process is automated, please allow a +few hours. ## Features @@ -29,11 +27,13 @@ Images for newly released Unity editor versions are added almost immediately to There will be limited support for older versions of Unity. -This is because for older versions, many factors regarding the preparation of stable docker images can not be determined programmatically. +This is because for older versions, many factors regarding the preparation of stable docker images +can not be determined programmatically. Due to that: -- Android builds for 2019.2 or lower will require you to roll your own images. This process will require you to manually specify NDK/SDK locations. +- Android builds for 2019.2 or lower will require you to roll your own images. This process will + require you to manually specify NDK/SDK locations. #### Limited IL2CPP support @@ -45,15 +45,21 @@ That's why: - IL2CPP for MacOS is not supported -We are looking to include MacOS as a base image "in the future", which is mostly dependent on contributions from the community. +We are looking to include MacOS as a base image "in the future", which is mostly dependent on +contributions from the community. -If you are looking to generate IL2CPP builds for MacOS, you can do so via [Github Actions](/docs/github/getting-started#il2cpp-example) without a docker container. +If you are looking to generate IL2CPP builds for MacOS, you can do so via +[Github Actions](/docs/github/getting-started#il2cpp-example) without a docker container. #### Concurrent builds on Windows and MacOS -Windows and MacOS will each consume an additional license seat if they are needed for a target platform. This is not an issue for free licenses, but for paid licenses, you will need to be mindful of starting too many parallel jobs as activation will fail. Below are some examples of number of consumed seats for a build: +Windows and MacOS will each consume an additional license seat if they are needed for a target +platform. This is not an issue for free licenses, but for paid licenses, you will need to be mindful +of starting too many parallel jobs as activation will fail. Below are some examples of number of +consumed seats for a build: -You are building for 1 target on a Linux based platform, 1 target for a Windows based platform, and 1 target for a MacOS based platform: +You are building for 1 target on a Linux based platform, 1 target for a Windows based platform, and +1 target for a MacOS based platform: - Number of seats consumed for the Linux build instances: 1 - Number of seats consumed for the Windows build instances: 1 @@ -61,7 +67,8 @@ You are building for 1 target on a Linux based platform, 1 target for a Windows Total concurrently consumed seats: **3** -You are building for 3 targets on a Linux based platform, 3 targets for a Windows based platform, and 1 target for a MacOS based platform: +You are building for 3 targets on a Linux based platform, 3 targets for a Windows based platform, +and 1 target for a MacOS based platform: - Number of seats consumed for the Linux build instances: 1 - Number of seats consumed for the Windows build instances: 1 @@ -69,4 +76,9 @@ You are building for 3 targets on a Linux based platform, 3 targets for a Window Total concurrently consumed seats: **3** -Notice it doesn't matter how many targets you build on each platform, the cost is always one concurrent license seat. This does not preclude you from doing builds sequentially, for example if you only have 1 seat available for your CI pipeline, you could build all Linux targets first, then build all Windows targets, and finally build the 1 MacOS target after that. More license seats would allow you to parallelize more platforms. In this example, having 3 seats means being able to build all targets simultaneously. +Notice it doesn't matter how many targets you build on each platform, the cost is always one +concurrent license seat. This does not preclude you from doing builds sequentially, for example if +you only have 1 seat available for your CI pipeline, you could build all Linux targets first, then +build all Windows targets, and finally build the 1 MacOS target after that. More license seats would +allow you to parallelize more platforms. In this example, having 3 seats means being able to build +all targets simultaneously. diff --git a/docs/08-docker/02-windows-docker-images.mdx b/docs/08-docker/02-windows-docker-images.mdx index b729c54a..ce4d5961 100644 --- a/docs/08-docker/02-windows-docker-images.mdx +++ b/docs/08-docker/02-windows-docker-images.mdx @@ -1,8 +1,12 @@ # Windows docker images -Windows images are used for some features available only in windows. The main reason is usually building an IL2CPP version of the application. +Windows images are used for some features available only in windows. The main reason is usually +building an IL2CPP version of the application. -To build applications effectively in terms of build time, the very base image is a .NET framework 4.8. It's cached on GitHub actions runners and we truly need .NET. The base Windows image can be found in [https://github.com/game-ci/docker](https://github.com/game-ci/docker/blob/main/images/windows/base/Dockerfile) +To build applications effectively in terms of build time, the very base image is a .NET framework +4.8. It's cached on GitHub actions runners and we truly need .NET. The base Windows image can be +found in +[https://github.com/game-ci/docker](https://github.com/game-ci/docker/blob/main/images/windows/base/Dockerfile) ## Features @@ -13,10 +17,16 @@ To build applications effectively in terms of build time, the very base image is ### Microsoft does not allow redistribution of Visual Studio build tools -Microsoft doesn't permit publishing images with VS Build tools [`discussion`](https://github.com/microsoft/Windows-Containers/issues/102#issuecomment-827170844) so aren't we allowed to do that. Building windows IL2CPP project in pure editor images leads to exceptions claiming that "C++ code builder" nor "Windows 10 SDK" are installed. There are two options to avoid this obstacle +Microsoft doesn't permit publishing images with VS Build tools +[`discussion`](https://github.com/microsoft/Windows-Containers/issues/102#issuecomment-827170844) so +aren't we allowed to do that. Building windows IL2CPP project in pure editor images leads to +exceptions claiming that "C++ code builder" nor "Windows 10 SDK" are installed. There are two +options to avoid this obstacle -1. Inject/mount Microsoft Visual Studio with VC++ and Windows 10 SDK from the host system into the container during runtime. -2. Installs vctools, e.g. `choco install visualstudio2017-workload-vctools --no-progress -y` and push it to a private docker registry +1. Inject/mount Microsoft Visual Studio with VC++ and Windows 10 SDK from the host system into the + container during runtime. +2. Installs vctools, e.g. `choco install visualstudio2017-workload-vctools --no-progress -y` and + push it to a private docker registry ### Injecting VC++ into the image @@ -64,13 +74,19 @@ volumes = [ ### Licenses are not valid between containers runs -This behaviour is different to Ubuntu containers where it's possible to use a single licence for even a few different runners. +This behaviour is different to Ubuntu containers where it's possible to use a single licence for +even a few different runners. -In Windows, it's necessary to acquire a license every time and return it after a building process. License files for every run are identical apart from the last four symbols of the machine hash code. This restriction has not been solved yet +In Windows, it's necessary to acquire a license every time and return it after a building process. +License files for every run are identical apart from the last four symbols of the machine hash code. +This restriction has not been solved yet -The simplest way is to write a couple of scripts (copied from [`Unity3d docs`](https://docs.unity3d.com/Manual/ManagingYourUnityLicense.html)) and wrap it to the try-finally block +The simplest way is to write a couple of scripts (copied from +[`Unity3d docs`](https://docs.unity3d.com/Manual/ManagingYourUnityLicense.html)) and wrap it to the +try-finally block -**Note**: Path to Unity3d is `C:\Program Files\Unity\Hub\Editor\{UNITY_EDITOR_VERSION}\Editor\Unity.exe` +**Note**: Path to Unity3d is +`C:\Program Files\Unity\Hub\Editor\{UNITY_EDITOR_VERSION}\Editor\Unity.exe` ```powershell try { @@ -84,9 +100,12 @@ try { ### Gitlab doesn't have (or has few) shared docker-windows runners -There is no other option right now, but [use a private runner](https://docs.gitlab.com/runner/install/). Please, set the `docker-windows` type of the runner +There is no other option right now, but +[use a private runner](https://docs.gitlab.com/runner/install/). Please, set the `docker-windows` +type of the runner -Default docker-for-windows settings are very resource-mean. It uses a single core and 1Gb of RAM. That's why the custom configuration is highly recommended +Default docker-for-windows settings are very resource-mean. It uses a single core and 1Gb of RAM. +That's why the custom configuration is highly recommended **config.toml** @@ -99,7 +118,8 @@ Default docker-for-windows settings are very resource-mean. It uses a single cor #... ``` -**Note:** `hostname` doesn't influence the performance, but one day can help with license association to a machine +**Note:** `hostname` doesn't influence the performance, but one day can help with license +association to a machine ### Default shell for Gitlab-runner is PowerShell Core @@ -127,7 +147,9 @@ Then push it to a docker registry. Installing `pwsh` during a pipeline doesn't h ### Git-ssh dependency package checkout fails -The base image `windowsservercore` is too old and has some outdated packages. One of them, `OpenSSH` has [a bug](https://github.com/PowerShell/Win32-OpenSSH/issues/1263) that breaks the remote repository signature check. +The base image `windowsservercore` is too old and has some outdated packages. One of them, `OpenSSH` +has [a bug](https://github.com/PowerShell/Win32-OpenSSH/issues/1263) that breaks the remote +repository signature check. The best option here is to replace it with something more recent @@ -138,4 +160,5 @@ choco install openssh -params '"/SSHAgentFeature"' --no-progress -y $env:GIT_SSH="C:\Program Files\OpenSSH-Win64\ssh.exe" ``` -**Note:** `ssh-add` must be used from a different location, `C:\Program Files\OpenSSH-Win64\ssh-add.exe` +**Note:** `ssh-add` must be used from a different location, +`C:\Program Files\OpenSSH-Win64\ssh-add.exe` diff --git a/docs/08-docker/03-customize-docker-images.mdx b/docs/08-docker/03-customize-docker-images.mdx index 2e333ca9..36e161bf 100644 --- a/docs/08-docker/03-customize-docker-images.mdx +++ b/docs/08-docker/03-customize-docker-images.mdx @@ -1,10 +1,15 @@ # Customize GameCI Unity Docker images -Sometimes, you will want to add tools to the existing unity docker images for specific needs. For example, in some projects, you might need Blender installed for unity to allow building a project with blender assets. Sometimes, you'll need some specific command lines or runtime that are used by unity in a _postprocess_ step. This documentation will guide you into building your own images on top of the existing ones to add your desired tools. +Sometimes, you will want to add tools to the existing unity docker images for specific needs. For +example, in some projects, you might need Blender installed for unity to allow building a project +with blender assets. Sometimes, you'll need some specific command lines or runtime that are used by +unity in a _postprocess_ step. This documentation will guide you into building your own images on +top of the existing ones to add your desired tools. ## Example: Add Ruby to existing images -In the following example, we will be adding `Ruby` on top of the existing docker images (all unity components) for the `2021.1.16f1` unity version and GameCI's `0.15.0` version and publish them. +In the following example, we will be adding `Ruby` on top of the existing docker images (all unity +components) for the `2021.1.16f1` unity version and GameCI's `0.15.0` version and publish them. ### Build script @@ -90,13 +95,18 @@ chmod +x build.sh ./build.sh ``` -As a result, you will now have your own docker image with desired tools available during build time. To confirm `ruby` is correctly installed, we can invoke the command within the image we just built: +As a result, you will now have your own docker image with desired tools available during build time. +To confirm `ruby` is correctly installed, we can invoke the command within the image we just built: ```bash docker run --rm -it gableroux/editor:ubuntu-2021.1.16f1-android-0.15.0 ruby --version ruby 2.6.0p0 (2018-12-25 revision 66547) [x86_64-linux] ``` -If you are using [github-actions unity-builder](https://github.com/marketplace/actions/unity-builder) you can then customize the docker image used during build using [the customimage parameter](https://game.ci/docs/github/builder#customimage) +If you are using +[github-actions unity-builder](https://github.com/marketplace/actions/unity-builder) you can then +customize the docker image used during build using +[the customimage parameter](https://game.ci/docs/github/builder#customimage) -For more information on how to publish to docker hub, you may refer to [docker's documentation](https://docs.docker.com/docker-hub/repos/) +For more information on how to publish to docker hub, you may refer to +[docker's documentation](https://docs.docker.com/docker-hub/repos/) diff --git a/docs/09-troubleshooting/common-issues.mdx b/docs/09-troubleshooting/common-issues.mdx index 0f661592..0db6a41b 100644 --- a/docs/09-troubleshooting/common-issues.mdx +++ b/docs/09-troubleshooting/common-issues.mdx @@ -27,7 +27,8 @@ Make sure your branch is clean and all files are indeed present: - All packages listed; - No pre-build steps that change your project differently from how that happens locally; -A good way to verify this, is to (locally) clone the Unity project in a new folder and run the build from there. +A good way to verify this, is to (locally) clone the Unity project in a new folder and run the build +from there. ### Gradle error @@ -48,13 +49,16 @@ There are 2 possible solutions: ### 'Non-whitespace before first tag. Line: 0 Column: 1 Char: 㼼' during manual activation -When activating a license on [license.unity3d.com](https://license.unity3d.com/), you may encounter the following error message: +When activating a license on [license.unity3d.com](https://license.unity3d.com/), you may encounter +the following error message: > Non-whitespace before first tag. Line: 0 Column: 1 Char: 㼼 Here's Unity's workaround: -> Unfortunately, this is a known issue our end. The relevant team are in the process of working on a fix as we speak, in the meantime there is a workaround. Try renaming the `alf` file with a command to convert characters on it with a `iconv` command. +> Unfortunately, this is a known issue our end. The relevant team are in the process of working on a +> fix as we speak, in the meantime there is a workaround. Try renaming the `alf` file with a command +> to convert characters on it with a `iconv` command. #### Solution @@ -65,6 +69,8 @@ iconv -f UTF-8 -t utf-16BE Unity_${version}.alf > Unity_${version}.utf16be.alf ### I use my google account to login to Unity, how do I get my username and password? -If you are using google account you can have some issue with activating unity. You just need to go on the unity website, settings, security and change your password. Then use your google email and your new password and it will work just fine ;) +If you are using google account you can have some issue with activating unity. You just need to go +on the unity website, settings, security and change your password. Then use your google email and +your new password and it will work just fine ;) [Source](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/issues/149) diff --git a/docs/index.mdx b/docs/index.mdx index 6e0306c8..03ac8283 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -4,10 +4,12 @@ sidebar_position: 1 # Introduction -This site hosts all documentation for GameCI, and will help you setup Continuous Integration for your game projects. +This site hosts all documentation for GameCI, and will help you setup Continuous Integration for +your game projects. -Continuous Integration is a widely-used practice where automated pipelines check the -latest code changes actually work, before merging them into the main branch. This helps developers stay in the flow and release faster and (ultimately) with more confidence. +Continuous Integration is a widely-used practice where automated pipelines check the latest code +changes actually work, before merging them into the main branch. This helps developers stay in the +flow and release faster and (ultimately) with more confidence. Follow the development on [GitHub](https://github.com/game-ci/documentation). diff --git a/lefthook.yml b/lefthook.yml index 63f723e9..1e144851 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -27,7 +27,9 @@ pre-commit: format code: glob: '*.{js,jsx,ts,tsx}' exclude: '.docusaurus/|build/' - run: yarn prettier --write {staged_files} && yarn eslint --stdin-filename {staged_files} && git add {staged_files} + run: + yarn prettier --write {staged_files} && yarn eslint --stdin-filename {staged_files} && git + add {staged_files} type check: glob: '*.{ts,tsx}' exclude: '.docusaurus/|build/' diff --git a/media/prettier-in-webstorm.png b/media/prettier-in-webstorm.png new file mode 100644 index 0000000000000000000000000000000000000000..1cda357f9e25c7963d65f203170294ff750929f2 GIT binary patch literal 26757 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 Dsn@BJ literal 0 HcmV?d00001 diff --git a/versioned_docs/version-1/02-getting-started/index.mdx b/versioned_docs/version-1/02-getting-started/index.mdx index 90bb159f..5446a37f 100644 --- a/versioned_docs/version-1/02-getting-started/index.mdx +++ b/versioned_docs/version-1/02-getting-started/index.mdx @@ -1,6 +1,7 @@ # Getting started -The term for automatically testing, building, and deploying your project is Continuous Integration, or CI for short. +The term for automatically testing, building, and deploying your project is Continuous Integration, +or CI for short. The configuration for CI, we commonly call a CI-workflow. @@ -12,10 +13,16 @@ To get started creating your workflow, you need 3 things: ## Preparing the project -**Create a repository** on your chosen Git host and follow their instructions to commit and push your project. +**Create a repository** on your chosen Git host and follow their instructions to commit and push +your project. -Be sure to **ignore any automatically generated files**, by adding the reference [.gitignore](https://github.com/github/gitignore/blob/master/Unity.gitignore) file to the root of your project. +Be sure to **ignore any automatically generated files**, by adding the reference +[.gitignore](https://github.com/github/gitignore/blob/master/Unity.gitignore) file to the root of +your project. -To **ensure large files are handled correctly** (in [LFS](https://git-lfs.github.com/)), you can add our reference [.gitattributes](https://gist.github.com/webbertakken/ff250a0d5e59a8aae961c2e509c07fbc) file to the root of your project. +To **ensure large files are handled correctly** (in [LFS](https://git-lfs.github.com/)), you can add +our reference +[.gitattributes](https://gist.github.com/webbertakken/ff250a0d5e59a8aae961c2e509c07fbc) file to the +root of your project. You are now **ready** to create a workflow! Choose the CI system you chose in the menu on the left. diff --git a/versioned_docs/version-1/03-docker/01-docker-images.mdx b/versioned_docs/version-1/03-docker/01-docker-images.mdx index e9d42e71..fb0718d2 100644 --- a/versioned_docs/version-1/03-docker/01-docker-images.mdx +++ b/versioned_docs/version-1/03-docker/01-docker-images.mdx @@ -1,20 +1,18 @@ # GameCI Docker images for Unity -All projects for Unity in GameCI use -[`game-ci/docker`](https://github.com/game-ci/docker/) -docker images which are specialised for CI and command-line use. These images are published on +All projects for Unity in GameCI use [`game-ci/docker`](https://github.com/game-ci/docker/) docker +images which are specialised for CI and command-line use. These images are published on [docker hub as `unityci/editor`](https://hub.docker.com/r/unityci/editor/tags?page=1&ordering=last_updated). They are established empirically by the community and come forth from the -[`gableroux/unity3d`](https://gitlab.com/game-ci/unity3d/) -project. It was previously published on -[docker hub as `gableroux/unity3d`](https://hub.docker.com/r/gableroux/unity3d/). -**There won't be any new versions releases for `gableroux/unity3d` as it is now deprecated in favor of +[`gableroux/unity3d`](https://gitlab.com/game-ci/unity3d/) project. It was previously published on +[docker hub as `gableroux/unity3d`](https://hub.docker.com/r/gableroux/unity3d/). **There won't be +any new versions releases for `gableroux/unity3d` as it is now deprecated in favor of [`game-ci/docker`](https://github.com/game-ci/docker/).** Images for newly released Unity editor versions are added almost immediately to -[`game-ci/docker`](https://github.com/game-ci/docker/) -. This process is automated, please allow a few hours. +[`game-ci/docker`](https://github.com/game-ci/docker/) . This process is automated, please allow a +few hours. ## Features @@ -29,11 +27,13 @@ Images for newly released Unity editor versions are added almost immediately to There will be limited support for older versions of Unity. -This is because for older versions, many factors regarding the preparation of stable docker images can not be determined programmatically. +This is because for older versions, many factors regarding the preparation of stable docker images +can not be determined programmatically. Due to that: -- Android builds for 2019.2 or lower will require you to roll your own images. This process will require you to manually specify NDK/SDK locations. +- Android builds for 2019.2 or lower will require you to roll your own images. This process will + require you to manually specify NDK/SDK locations. #### Limited IL2CPP support @@ -45,15 +45,21 @@ That's why: - IL2CPP for MacOS is not supported -We are looking to include MacOS as a base image "in the future", which is mostly dependent on contributions from the community. +We are looking to include MacOS as a base image "in the future", which is mostly dependent on +contributions from the community. -If you are looking to generate IL2CPP builds for MacOS, you can do so via [Github Actions](/docs/github/getting-started#il2cpp-example) without a docker container. +If you are looking to generate IL2CPP builds for MacOS, you can do so via +[Github Actions](/docs/github/getting-started#il2cpp-example) without a docker container. #### Concurrent builds on Windows and MacOS -Windows and MacOS will each consume an additional license seat if they are needed for a target platform. This is not an issue for free licenses, but for paid licenses, you will need to be mindful of starting too many parallel jobs as activation will fail. Below are some examples of number of consumed seats for a build: +Windows and MacOS will each consume an additional license seat if they are needed for a target +platform. This is not an issue for free licenses, but for paid licenses, you will need to be mindful +of starting too many parallel jobs as activation will fail. Below are some examples of number of +consumed seats for a build: -You are building for 1 target on a Linux based platform, 1 target for a Windows based platform, and 1 target for a MacOS based platform: +You are building for 1 target on a Linux based platform, 1 target for a Windows based platform, and +1 target for a MacOS based platform: - Number of seats consumed for the Linux build instances: 1 - Number of seats consumed for the Windows build instances: 1 @@ -61,7 +67,8 @@ You are building for 1 target on a Linux based platform, 1 target for a Windows Total concurrently consumed seats: **3** -You are building for 3 targets on a Linux based platform, 3 targets for a Windows based platform, and 1 target for a MacOS based platform: +You are building for 3 targets on a Linux based platform, 3 targets for a Windows based platform, +and 1 target for a MacOS based platform: - Number of seats consumed for the Linux build instances: 1 - Number of seats consumed for the Windows build instances: 1 @@ -69,4 +76,9 @@ You are building for 3 targets on a Linux based platform, 3 targets for a Window Total concurrently consumed seats: **3** -Notice it doesn't matter how many targets you build on each platform, the cost is always one concurrent license seat. This does not preclude you from doing builds sequentially, for example if you only have 1 seat available for your CI pipeline, you could build all Linux targets first, then build all Windows targets, and finally build the 1 MacOS target after that. More license seats would allow you to parallelize more platforms. In this example, having 3 seats means being able to build all targets simultaneously. +Notice it doesn't matter how many targets you build on each platform, the cost is always one +concurrent license seat. This does not preclude you from doing builds sequentially, for example if +you only have 1 seat available for your CI pipeline, you could build all Linux targets first, then +build all Windows targets, and finally build the 1 MacOS target after that. More license seats would +allow you to parallelize more platforms. In this example, having 3 seats means being able to build +all targets simultaneously. diff --git a/versioned_docs/version-1/03-docker/02-windows-docker-images.mdx b/versioned_docs/version-1/03-docker/02-windows-docker-images.mdx index b729c54a..ce4d5961 100644 --- a/versioned_docs/version-1/03-docker/02-windows-docker-images.mdx +++ b/versioned_docs/version-1/03-docker/02-windows-docker-images.mdx @@ -1,8 +1,12 @@ # Windows docker images -Windows images are used for some features available only in windows. The main reason is usually building an IL2CPP version of the application. +Windows images are used for some features available only in windows. The main reason is usually +building an IL2CPP version of the application. -To build applications effectively in terms of build time, the very base image is a .NET framework 4.8. It's cached on GitHub actions runners and we truly need .NET. The base Windows image can be found in [https://github.com/game-ci/docker](https://github.com/game-ci/docker/blob/main/images/windows/base/Dockerfile) +To build applications effectively in terms of build time, the very base image is a .NET framework +4.8. It's cached on GitHub actions runners and we truly need .NET. The base Windows image can be +found in +[https://github.com/game-ci/docker](https://github.com/game-ci/docker/blob/main/images/windows/base/Dockerfile) ## Features @@ -13,10 +17,16 @@ To build applications effectively in terms of build time, the very base image is ### Microsoft does not allow redistribution of Visual Studio build tools -Microsoft doesn't permit publishing images with VS Build tools [`discussion`](https://github.com/microsoft/Windows-Containers/issues/102#issuecomment-827170844) so aren't we allowed to do that. Building windows IL2CPP project in pure editor images leads to exceptions claiming that "C++ code builder" nor "Windows 10 SDK" are installed. There are two options to avoid this obstacle +Microsoft doesn't permit publishing images with VS Build tools +[`discussion`](https://github.com/microsoft/Windows-Containers/issues/102#issuecomment-827170844) so +aren't we allowed to do that. Building windows IL2CPP project in pure editor images leads to +exceptions claiming that "C++ code builder" nor "Windows 10 SDK" are installed. There are two +options to avoid this obstacle -1. Inject/mount Microsoft Visual Studio with VC++ and Windows 10 SDK from the host system into the container during runtime. -2. Installs vctools, e.g. `choco install visualstudio2017-workload-vctools --no-progress -y` and push it to a private docker registry +1. Inject/mount Microsoft Visual Studio with VC++ and Windows 10 SDK from the host system into the + container during runtime. +2. Installs vctools, e.g. `choco install visualstudio2017-workload-vctools --no-progress -y` and + push it to a private docker registry ### Injecting VC++ into the image @@ -64,13 +74,19 @@ volumes = [ ### Licenses are not valid between containers runs -This behaviour is different to Ubuntu containers where it's possible to use a single licence for even a few different runners. +This behaviour is different to Ubuntu containers where it's possible to use a single licence for +even a few different runners. -In Windows, it's necessary to acquire a license every time and return it after a building process. License files for every run are identical apart from the last four symbols of the machine hash code. This restriction has not been solved yet +In Windows, it's necessary to acquire a license every time and return it after a building process. +License files for every run are identical apart from the last four symbols of the machine hash code. +This restriction has not been solved yet -The simplest way is to write a couple of scripts (copied from [`Unity3d docs`](https://docs.unity3d.com/Manual/ManagingYourUnityLicense.html)) and wrap it to the try-finally block +The simplest way is to write a couple of scripts (copied from +[`Unity3d docs`](https://docs.unity3d.com/Manual/ManagingYourUnityLicense.html)) and wrap it to the +try-finally block -**Note**: Path to Unity3d is `C:\Program Files\Unity\Hub\Editor\{UNITY_EDITOR_VERSION}\Editor\Unity.exe` +**Note**: Path to Unity3d is +`C:\Program Files\Unity\Hub\Editor\{UNITY_EDITOR_VERSION}\Editor\Unity.exe` ```powershell try { @@ -84,9 +100,12 @@ try { ### Gitlab doesn't have (or has few) shared docker-windows runners -There is no other option right now, but [use a private runner](https://docs.gitlab.com/runner/install/). Please, set the `docker-windows` type of the runner +There is no other option right now, but +[use a private runner](https://docs.gitlab.com/runner/install/). Please, set the `docker-windows` +type of the runner -Default docker-for-windows settings are very resource-mean. It uses a single core and 1Gb of RAM. That's why the custom configuration is highly recommended +Default docker-for-windows settings are very resource-mean. It uses a single core and 1Gb of RAM. +That's why the custom configuration is highly recommended **config.toml** @@ -99,7 +118,8 @@ Default docker-for-windows settings are very resource-mean. It uses a single cor #... ``` -**Note:** `hostname` doesn't influence the performance, but one day can help with license association to a machine +**Note:** `hostname` doesn't influence the performance, but one day can help with license +association to a machine ### Default shell for Gitlab-runner is PowerShell Core @@ -127,7 +147,9 @@ Then push it to a docker registry. Installing `pwsh` during a pipeline doesn't h ### Git-ssh dependency package checkout fails -The base image `windowsservercore` is too old and has some outdated packages. One of them, `OpenSSH` has [a bug](https://github.com/PowerShell/Win32-OpenSSH/issues/1263) that breaks the remote repository signature check. +The base image `windowsservercore` is too old and has some outdated packages. One of them, `OpenSSH` +has [a bug](https://github.com/PowerShell/Win32-OpenSSH/issues/1263) that breaks the remote +repository signature check. The best option here is to replace it with something more recent @@ -138,4 +160,5 @@ choco install openssh -params '"/SSHAgentFeature"' --no-progress -y $env:GIT_SSH="C:\Program Files\OpenSSH-Win64\ssh.exe" ``` -**Note:** `ssh-add` must be used from a different location, `C:\Program Files\OpenSSH-Win64\ssh-add.exe` +**Note:** `ssh-add` must be used from a different location, +`C:\Program Files\OpenSSH-Win64\ssh-add.exe` diff --git a/versioned_docs/version-1/03-docker/03-customize-docker-images.mdx b/versioned_docs/version-1/03-docker/03-customize-docker-images.mdx index 2e333ca9..36e161bf 100644 --- a/versioned_docs/version-1/03-docker/03-customize-docker-images.mdx +++ b/versioned_docs/version-1/03-docker/03-customize-docker-images.mdx @@ -1,10 +1,15 @@ # Customize GameCI Unity Docker images -Sometimes, you will want to add tools to the existing unity docker images for specific needs. For example, in some projects, you might need Blender installed for unity to allow building a project with blender assets. Sometimes, you'll need some specific command lines or runtime that are used by unity in a _postprocess_ step. This documentation will guide you into building your own images on top of the existing ones to add your desired tools. +Sometimes, you will want to add tools to the existing unity docker images for specific needs. For +example, in some projects, you might need Blender installed for unity to allow building a project +with blender assets. Sometimes, you'll need some specific command lines or runtime that are used by +unity in a _postprocess_ step. This documentation will guide you into building your own images on +top of the existing ones to add your desired tools. ## Example: Add Ruby to existing images -In the following example, we will be adding `Ruby` on top of the existing docker images (all unity components) for the `2021.1.16f1` unity version and GameCI's `0.15.0` version and publish them. +In the following example, we will be adding `Ruby` on top of the existing docker images (all unity +components) for the `2021.1.16f1` unity version and GameCI's `0.15.0` version and publish them. ### Build script @@ -90,13 +95,18 @@ chmod +x build.sh ./build.sh ``` -As a result, you will now have your own docker image with desired tools available during build time. To confirm `ruby` is correctly installed, we can invoke the command within the image we just built: +As a result, you will now have your own docker image with desired tools available during build time. +To confirm `ruby` is correctly installed, we can invoke the command within the image we just built: ```bash docker run --rm -it gableroux/editor:ubuntu-2021.1.16f1-android-0.15.0 ruby --version ruby 2.6.0p0 (2018-12-25 revision 66547) [x86_64-linux] ``` -If you are using [github-actions unity-builder](https://github.com/marketplace/actions/unity-builder) you can then customize the docker image used during build using [the customimage parameter](https://game.ci/docs/github/builder#customimage) +If you are using +[github-actions unity-builder](https://github.com/marketplace/actions/unity-builder) you can then +customize the docker image used during build using +[the customimage parameter](https://game.ci/docs/github/builder#customimage) -For more information on how to publish to docker hub, you may refer to [docker's documentation](https://docs.docker.com/docker-hub/repos/) +For more information on how to publish to docker hub, you may refer to +[docker's documentation](https://docs.docker.com/docker-hub/repos/) diff --git a/versioned_docs/version-1/04-github/01-getting-started.mdx b/versioned_docs/version-1/04-github/01-getting-started.mdx index fc4095c4..5daeae8b 100644 --- a/versioned_docs/version-1/04-github/01-getting-started.mdx +++ b/versioned_docs/version-1/04-github/01-getting-started.mdx @@ -1,16 +1,16 @@ # Getting started -Unity Actions provide the fastest and **easiest** way to automatically test and build any Unity project. +Unity Actions provide the fastest and **easiest** way to automatically test and build any Unity +project. -There are a few parts to setting up a workflow. Steps may slightly differ depending on each license type. +There are a few parts to setting up a workflow. Steps may slightly differ depending on each license +type. ## Mental model #### Overall steps -1. Understand how - [Github Actions](https://docs.github.com/en/actions) - work. +1. Understand how [Github Actions](https://docs.github.com/en/actions) work. 2. Configure a license for Unity. 3. Set up a workflow for your project. 4. Result: Merge pull requests with more confidence. @@ -19,16 +19,14 @@ There are a few parts to setting up a workflow. Steps may slightly differ depend Setting up a workflow is easy! -Create a file called `.github/workflows/main.yml` in your repository and configure the following steps; +Create a file called `.github/workflows/main.yml` in your repository and configure the following +steps; -1. Checkout your repository using - [Checkout](https://github.com/marketplace/actions/checkout). -2. Cache Unity Library folder using - [Cache](https://github.com/marketplace/actions/cache). +1. Checkout your repository using [Checkout](https://github.com/marketplace/actions/checkout). +2. Cache Unity Library folder using [Cache](https://github.com/marketplace/actions/cache). 3. Configure your test job using [Test Runner](https://github.com/marketplace/actions/unity-test-runner). -4. Configure your build job using - [Builder](https://github.com/marketplace/actions/unity-builder). +4. Configure your build job using [Builder](https://github.com/marketplace/actions/unity-builder). 5. Deploy your application. _**Note:** all steps will be explained in the next chapters._ @@ -44,15 +42,12 @@ Any subsequent steps assume you have read the above. #### Supported versions -Unity Actions are based on the -[unity3d](https://gitlab.com/game-ci/unity3d) -images from -[GabLeRoux](https://github.com/GabLeRoux). -Any version in the -[list](https://hub.docker.com/r/gableroux/unity3d/tags) -can be used to test and build projects. +Unity Actions are based on the [unity3d](https://gitlab.com/game-ci/unity3d) images from +[GabLeRoux](https://github.com/GabLeRoux). Any version in the +[list](https://hub.docker.com/r/gableroux/unity3d/tags) can be used to test and build projects. -It's generally considered good practice to use the same Unity version for Unity Actions as you do to develop your project. +It's generally considered good practice to use the same Unity version for Unity Actions as you do to +develop your project. ## Simple example @@ -111,8 +106,7 @@ jobs: ## Advanced example -To get an idea of how to create a more advanced workflows, -have a look at the example below. +To get an idea of how to create a more advanced workflows, have a look at the example below. > _Note: this repository tests this workflow_ diff --git a/versioned_docs/version-1/04-github/02-activation.mdx b/versioned_docs/version-1/04-github/02-activation.mdx index 22f31484..28535b11 100644 --- a/versioned_docs/version-1/04-github/02-activation.mdx +++ b/versioned_docs/version-1/04-github/02-activation.mdx @@ -18,9 +18,8 @@ You may use the [Unity - Request Activation File](https://github.com/marketplace/actions/unity-request-activation-file) action using below instructions. -The activation file uses machine identifiers and the Unity version number. -All github virtual machines emit the same hardware ID. -You cannot perform this step locally. +The activation file uses machine identifiers and the Unity version number. All github virtual +machines emit the same hardware ID. You cannot perform this step locally. Let's go! @@ -84,11 +83,10 @@ Follow these (one-time) steps for simple activation. ## Optional steps -- Verify your license using - [Activate](https://github.com/marketplace/actions/unity-activate). +- Verify your license using [Activate](https://github.com/marketplace/actions/unity-activate). - When using a pro license also use - [Return License](https://github.com/marketplace/actions/unity-return-license) - to free up the license allocation after usage. + [Return License](https://github.com/marketplace/actions/unity-return-license) to free up the + license allocation after usage. > _**Note:** Test runner and Builder already include these steps._ diff --git a/versioned_docs/version-1/04-github/03-test-runner.mdx b/versioned_docs/version-1/04-github/03-test-runner.mdx index faec8136..648bcd57 100644 --- a/versioned_docs/version-1/04-github/03-test-runner.mdx +++ b/versioned_docs/version-1/04-github/03-test-runner.mdx @@ -2,7 +2,8 @@ Running your test suite in an automated workflow helps increase certainty when merging. -Use [Unity - Test runner](https://github.com/marketplace/actions/unity-test-runner) to run your Unity tests. +Use [Unity - Test runner](https://github.com/marketplace/actions/unity-test-runner) to run your +Unity tests. ## Basic setup @@ -15,8 +16,8 @@ Create or edit the file called `.github/workflows/main.yml` and add a job to it. Personal licenses require a one-time manual activation step (per unity version). Make sure you -[acquire and activate](https://github.com/marketplace/actions/unity-request-activation-file) -your license file and add it as a secret. +[acquire and activate](https://github.com/marketplace/actions/unity-request-activation-file) your +license file and add it as a secret. Then, define the test step as follows: @@ -54,12 +55,11 @@ That is all you need to test your project. ## Storing test results -To be able to access the test results, -they need to be uploaded as artifacts. +To be able to access the test results, they need to be uploaded as artifacts. To do this it is recommended to use Github Actions official -[upload artifact action](https://github.com/marketplace/actions/upload-artifact) -after any test action. +[upload artifact action](https://github.com/marketplace/actions/upload-artifact) after any test +action. By default, Test Runner outputs its results to a folder named `artifacts`. @@ -74,7 +74,8 @@ Test results can now be downloaded as `Artifacts` in the `Actions` tab. #### Specifying artifacts folder -You can specify a different `artifactsPath` in the test runner and reference this path using the `id` of the test step. +You can specify a different `artifactsPath` in the test runner and reference this path using the +`id` of the test step. ```yaml - uses: webbertakken/unity-test-runner@v1.7 @@ -90,12 +91,10 @@ You can specify a different `artifactsPath` in the test runner and reference thi ## Caching -In order to make test runs (and builds) faster, -you can cache Library files from previous runs. +In order to make test runs (and builds) faster, you can cache Library files from previous runs. To do so, simply add Github Actions' official -[cache action](https://github.com/marketplace/actions/cache) -before any unity steps. +[cache action](https://github.com/marketplace/actions/cache) before any unity steps. ```yaml - uses: actions/cache@v1.1.0 @@ -115,19 +114,17 @@ Below options can be specified under `with:` for the `unity-test-runner` action. #### projectPath -Specify the path to your Unity project to be tested. -The path should be relative to the root of your project. +Specify the path to your Unity project to be tested. The path should be relative to the root of your +project. -_**required:** `false`_ -_**default:** ``_ +_**required:** `false`_ _**default:** ``_ #### unityVersion -Version of Unity to use for testing the project. -Use "auto" to get from your ProjectSettings/ProjectVersion.txt +Version of Unity to use for testing the project. Use "auto" to get from your +ProjectSettings/ProjectVersion.txt -_**required:** `false`_ -_**default:** `auto`_ +_**required:** `false`_ _**default:** `auto`_ #### testMode @@ -135,8 +132,7 @@ The type of tests to be run by the test runner. Options are: "all", "playmode", "editmode" -_**required:** `false`_ -_**default:** `all`_ +_**required:** `false`_ _**default:** `all`_ #### artifactsPath @@ -144,8 +140,7 @@ Path where the test results should be stored. In this folder a folder will be created for every test mode. -_**required:** `false`_ -_**default:** `artifacts`_ +_**required:** `false`_ _**default:** `artifacts`_ #### useHostNetwork @@ -155,8 +150,7 @@ This is useful if Unity needs to access a local server that was started as part Options are: "true", "false" -_**required:** `false`_ -_**default:** `false`_ +_**required:** `false`_ _**default:** `false`_ #### customParameters @@ -172,8 +166,7 @@ Parameters without a value will be considered booleans (with a value of true). customParameters: -profile SomeProfile -someBoolean -someValue exampleValue ``` -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### customImage @@ -185,8 +178,7 @@ Specific docker image that should be used for testing the project. customImage: 'unityci/editor:2020.1.14f1-base-0' ``` -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ ## Complete example diff --git a/versioned_docs/version-1/04-github/04-builder.mdx b/versioned_docs/version-1/04-github/04-builder.mdx index 08b80c6d..d28721a8 100644 --- a/versioned_docs/version-1/04-github/04-builder.mdx +++ b/versioned_docs/version-1/04-github/04-builder.mdx @@ -1,9 +1,10 @@ # Builder -Building the project as part of a workflow may help to create mind-space and focus on the project itself. +Building the project as part of a workflow may help to create mind-space and focus on the project +itself. -Use [Unity - Builder ](https://github.com/marketplace/actions/unity-builder) -to automatically build Unity projects for different platforms. +Use [Unity - Builder ](https://github.com/marketplace/actions/unity-builder) to automatically build +Unity projects for different platforms. ## Basic setup @@ -16,8 +17,8 @@ Create or edit the file called `.github/workflows/main.yml` and add a job to it. Personal licenses require a one-time manual activation step (per unity version). Make sure you -[acquire and activate](https://github.com/marketplace/actions/unity-request-activation-file) -your license file and add it as a secret. +[acquire and activate](https://github.com/marketplace/actions/unity-request-activation-file) your +license file and add it as a secret. Then, define the build step as follows: @@ -57,11 +58,10 @@ That is all you need to build your project. ## Storing the build -To be able to access your built files, -they need to be uploaded as artifacts. -To do this it is recommended to use Github Actions official -[upload artifact action](https://github.com/marketplace/actions/upload-artifact) -after any build action. +To be able to access your built files, they need to be uploaded as artifacts. To do this it is +recommended to use Github Actions official +[upload artifact action](https://github.com/marketplace/actions/upload-artifact) after any build +action. By default, Builder outputs it's builds to a folder named `build`. @@ -78,9 +78,9 @@ Builds can now be downloaded as Artifacts in the Actions tab. ## Caching -In order to make builds run faster, you can cache Library files from previous -builds. To do so simply add Github Actions official -[cache action](https://github.com/marketplace/actions/cache) before any unity steps. +In order to make builds run faster, you can cache Library files from previous builds. To do so +simply add Github Actions official [cache action](https://github.com/marketplace/actions/cache) +before any unity steps. Example: @@ -102,25 +102,24 @@ Below options can be specified under `with:` for the `unity-builder` action. #### projectPath -Specify the path to your Unity project to be built. -The path should be relative to the root of your project. +Specify the path to your Unity project to be built. The path should be relative to the root of your +project. -_**required:** `false`_ -_**default:** ``_ +_**required:** `false`_ _**default:** ``_ #### unityVersion -Version of Unity to use for building the project. -Use "auto" to get from your ProjectSettings/ProjectVersion.txt +Version of Unity to use for building the project. Use "auto" to get from your +ProjectSettings/ProjectVersion.txt -_**required:** `false`_ -_**default:** `auto`_ +_**required:** `false`_ _**default:** `auto`_ #### targetPlatform Platform that the build should target. -Must be one of the [allowed values](https://docs.unity3d.com/ScriptReference/BuildTarget.html) listed in the Unity scripting manual. +Must be one of the [allowed values](https://docs.unity3d.com/ScriptReference/BuildTarget.html) +listed in the Unity scripting manual. _**required:** `true`_ @@ -128,8 +127,7 @@ _**required:** `true`_ Name of the build. Also the folder in which the build will be stored within `buildsPath`. -_**required:** `false`_ -_**default:** ``_ +_**required:** `false`_ _**default:** ``_ #### buildsPath @@ -137,8 +135,7 @@ Path where the builds should be stored. In this folder a folder will be created for every targetPlatform. -_**required:** `false`_ -_**default:** `build`_ +_**required:** `false`_ _**default:** `build`_ #### buildMethod @@ -157,8 +154,7 @@ _**example:**_ buildMethod: EditorNamespace.BuilderClassName.StaticBulidMethod ``` -_**required:** `false`_ -_**default:** Built-in script that will run a build out of the box._ +_**required:** `false`_ _**default:** Built-in script that will run a build out of the box._ #### versioning @@ -193,21 +189,22 @@ No configuration required. Allows specifying a custom version in the `version` field. **(advanced users)** -> This strategy is useful when your project or pipeline has some kind of orchestration -> that determines the versions. +> This strategy is useful when your project or pipeline has some kind of orchestration that +> determines the versions. ##### None No version will be set by Builder. **(not recommended)** -> Not recommended unless you generate a new version in a pre-commit hook. Manually -> setting versions is error-prone. +> Not recommended unless you generate a new version in a pre-commit hook. Manually setting versions +> is error-prone. #### androidVersionCode Configure the android `versionCode`. -When not specified, the version code is generated from the version using the `major * 1000000 + minor * 1000 + patch` scheme; +When not specified, the version code is generated from the version using the +`major * 1000000 + minor * 1000 + patch` scheme; #### androidAppBundle @@ -226,51 +223,48 @@ Set this flag to `true` to build '.aab' instead of '.apk'. You should also set all the Android Keystore options (see below). -_**required:** `false`_ -_**default:** `false`_ +_**required:** `false`_ _**default:** `false`_ #### androidKeystoreName Configure the android `keystoreName`. Must be provided if configuring the below keystore options. For this to take effect, you must enable `Custom Keystore` in your -[Android Player settings](https://docs.unity3d.com/Manual/class-PlayerSettingsAndroid.html). -The default build script overrides the other keystore settings with these keystore options. +[Android Player settings](https://docs.unity3d.com/Manual/class-PlayerSettingsAndroid.html). The +default build script overrides the other keystore settings with these keystore options. -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### androidKeystoreBase64 -Configure the base64 contents of the android keystore file. You should get this with `base64 $androidKeystoreName` +Configure the base64 contents of the android keystore file. You should get this with +`base64 $androidKeystoreName` -The contents will be decoded from base64 using `echo $androidKeystoreBase64 | base64 --decode > $projectPath/$androidKeystoreName` +The contents will be decoded from base64 using +`echo $androidKeystoreBase64 | base64 --decode > $projectPath/$androidKeystoreName` -It is recommended to use [GitHub Secrets](https://docs.github.com/en/actions/reference/encrypted-secrets). +It is recommended to use +[GitHub Secrets](https://docs.github.com/en/actions/reference/encrypted-secrets). -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### androidKeystorePass Configure the android `keystorePass`. Recommended to use GitHub Secrets. -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### androidKeyaliasName Configure the android `keyaliasName`. Recommended to use GitHub Secrets. -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### androidKeyaliasPass Configure the android `keyaliasPass`. Recommended to use GitHub Secrets. -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### allowDirtyBuild @@ -282,12 +276,10 @@ Allows the branch of the build to be dirty, and still generate the build. allowDirtyBuild: true ``` -Note that it is generally bad practice to modify your branch -in a CI Pipeline. However there are exceptions where this might -be needed. (use with care). +Note that it is generally bad practice to modify your branch in a CI Pipeline. However there are +exceptions where this might be needed. (use with care). -_**required:** `false`_ -_**default:** `false`_ +_**required:** `false`_ _**default:** `false`_ #### customParameters @@ -303,8 +295,7 @@ Parameters without a value will be considered booleans (with a value of true). customParameters: -profile SomeProfile -someBoolean -someValue exampleValue ``` -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ #### customImage @@ -316,17 +307,17 @@ Specific docker image that should be used for building the project. customImage: 'unityci/editor:2020.1.14f1-base-0' ``` -_**required:** `false`_ -_**default:** `""`_ +_**required:** `false`_ _**default:** `""`_ ## Outputs -Below are outputs that can be accessed by using `${{ steps.myBuildStep.outputs.outputName }}`, where `myBuildStep` is the id -of the Builder step, and `outputName` is the name of the output. +Below are outputs that can be accessed by using `${{ steps.myBuildStep.outputs.outputName }}`, where +`myBuildStep` is the id of the Builder step, and `outputName` is the name of the output. #### buildVersion -Returns the version that was generated by Builder, following the strategy configured for `versioning`. +Returns the version that was generated by Builder, following the strategy configured for +`versioning`. ```yaml - uses: webbertakken/unity-builder@1.5 diff --git a/versioned_docs/version-1/04-github/05-returning-a-license.mdx b/versioned_docs/version-1/04-github/05-returning-a-license.mdx index 7ea2ea48..b6e460d0 100644 --- a/versioned_docs/version-1/04-github/05-returning-a-license.mdx +++ b/versioned_docs/version-1/04-github/05-returning-a-license.mdx @@ -1,14 +1,14 @@ # Returning a license -Manually returning a license is **usually never necessary**, -unless when running into an _unrecoverable error_ while having a license active. +Manually returning a license is **usually never necessary**, unless when running into an +_unrecoverable error_ while having a license active. Also, Unity only allows returning professional licenses. ## 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. +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. Add this step to your workflow: diff --git a/versioned_docs/version-1/04-github/06-deployment/android.mdx b/versioned_docs/version-1/04-github/06-deployment/android.mdx index ef43083f..9d824a4b 100644 --- a/versioned_docs/version-1/04-github/06-deployment/android.mdx +++ b/versioned_docs/version-1/04-github/06-deployment/android.mdx @@ -2,8 +2,8 @@ ### 1- Install [fastlane](https://docs.fastlane.tools/getting-started/android/setup/) -There are different ways of installing fastlane, -but the recommended approach is to make a Gemfile with following content : +There are different ways of installing fastlane, but the recommended approach is to make a Gemfile +with following content : ```bash # fastlane/Gemfile @@ -20,11 +20,14 @@ This will create a `Gemfile.lock`, upload both `Gemfile` and `Gemfile.lock` to y - You need to manually upload your **first** version of application to google play The output should be signed using a signing key , this can be done by creating signing key from -[Unity/Player Settings/Publishing Settings](https://docs.unity3d.com/2017.3/Documentation/Manual/class-PlayerSettingsAndroid.html) . +[Unity/Player Settings/Publishing Settings](https://docs.unity3d.com/2017.3/Documentation/Manual/class-PlayerSettingsAndroid.html) +. -- Follow the setup steps from [this link](https://docs.fastlane.tools/actions/supply/) to create a service account +- Follow the setup steps from [this link](https://docs.fastlane.tools/actions/supply/) to create a + service account -> -- **Note:** Keep your keystore and service_account.json file somewhere safe , you will need it later to upload new releases +> -- **Note:** Keep your keystore and service_account.json file somewhere safe , you will need it +> later to upload new releases ### 3- Add following fastlane files to your Fastlane folder @@ -118,7 +121,8 @@ ReleaseToGooglePlay: ### 5- Add secrets to your Github repo -- **ANDROID_KEYSTORE_BASE64** : Base64 of your keystore in step 1 (You can use an online base64 encoder for this) +- **ANDROID_KEYSTORE_BASE64** : Base64 of your keystore in step 1 (You can use an online base64 + encoder for this) - **ANDROID_KEYSTORE_PASS**: Password of your keystore - **ANDROID_KEYALIAS_NAME**: Alias name of your keystore - **ANDROID_KEYALIAS_PASS**: Password for your alias name in key store diff --git a/versioned_docs/version-1/04-github/06-deployment/ios.mdx b/versioned_docs/version-1/04-github/06-deployment/ios.mdx index 476eccce..24a62fa7 100644 --- a/versioned_docs/version-1/04-github/06-deployment/ios.mdx +++ b/versioned_docs/version-1/04-github/06-deployment/ios.mdx @@ -1,13 +1,14 @@ # Publish to AppStore -Uploading to AppStore is a little tricky to handle certificates, Make sure you do all these steps carefully +Uploading to AppStore is a little tricky to handle certificates, Make sure you do all these steps +carefully > -- **Note:** You need a Mac environment for doing these steps . ### 1- Install [fastlane](https://docs.fastlane.tools/getting-started/ios/setup/) -There are different ways of installing fastlane, -but the recommended approach is to make a Gemfile with following content : +There are different ways of installing fastlane, but the recommended approach is to make a Gemfile +with following content : ```bash # fastlane/Gemfile @@ -21,21 +22,21 @@ This will create a `Gemfile.lock`, upload both `Gemfile` and `Gemfile.lock` to y ### 2- Create storage for Apple certifications -Fastlane has a nice implementation of [codesigning.guide concept](https://codesigning.guide/) -called match. It basically uploads all necessary keys and certificated in a storage of your -choice(Private Git repo,Amazon S3,..) and then share it between your different development envs. +Fastlane has a nice implementation of [codesigning.guide concept](https://codesigning.guide/) called +match. It basically uploads all necessary keys and certificated in a storage of your choice(Private +Git repo,Amazon S3,..) and then share it between your different development envs. For using match : - Create a private git repository -- Run following command : `fastlane match appstore` this will ask for your github repository - and AppleId, and then upload your certificates to the private git repository. +- Run following command : `fastlane match appstore` this will ask for your github repository and + AppleId, and then upload your certificates to the private git repository. -> -- **Note:** Make sure your AppleId have two-step Authentication and have enough -> access . +> -- **Note:** Make sure your AppleId have two-step Authentication and have enough access . > -> -- **Note:** If possible,It's also better to remove(after making a backup) all your certificates before doing it. Some times Match mess things up. +> -- **Note:** If possible,It's also better to remove(after making a backup) all your certificates +> before doing it. Some times Match mess things up. ### 3- Add following fastlane files to your Fastlane folder @@ -158,8 +159,8 @@ end ``` -> -- **Note:** If you add libraries that need Podfile (e,g Firebase) to your project, -> Add this line in the beginning of build step : +> -- **Note:** If you add libraries that need Podfile (e,g Firebase) to your project, Add this line +> in the beginning of build step : ``` cocoapods( @@ -266,16 +267,19 @@ BuildForiOSPlatform: - **APPLE_DEVELOPER_EMAIL**: Your AppleId - **APPLE_TEAM_ID**: Team Id From developer.apple.com/MemberShip - **APPLE_TEAM_NAME**: Team Name From developer.apple.com/MemberShip -- **MATCH_URL**: Address of private repository that you made in previous steps for storing certificates. +- **MATCH_URL**: Address of private repository that you made in previous steps for storing + certificates. - **GIT_TOKEN**: Base64 of user@MATCH_URL e,g user@https://github.com/game-ci/documentation.git . You can use some online base64 encoder for this step - **MATCH_PASSWORD**: The password you set when you use `fastlane match appstore` - **APPSTORE_KEY_ID ,APPSTORE_ISSUER_ID,APPSTORE_P8**: Because of limitation in using Apple accounts - with 2fa ( 2-factor authentication ) in CI environments, you have to - make special key for accessing appstore . Follow [fastlane official guide](https://docs.fastlane.tools/app-store-connect-api/) - to generate these values. + with 2fa ( 2-factor authentication ) in CI environments, you have to make special key for + accessing appstore . Follow + [fastlane official guide](https://docs.fastlane.tools/app-store-connect-api/) to generate these + values. ### 6- Unity Settings - Set Signing Team Id and Bundle identifier in iOS player setting -- Add your application icon (Application with no icon generate error during uploading to test flight) +- Add your application icon (Application with no icon generate error during uploading to test + flight) diff --git a/versioned_docs/version-1/05-gitlab/01-getting-started.mdx b/versioned_docs/version-1/05-gitlab/01-getting-started.mdx index 64b93be5..e00f1cbe 100644 --- a/versioned_docs/version-1/05-gitlab/01-getting-started.mdx +++ b/versioned_docs/version-1/05-gitlab/01-getting-started.mdx @@ -1,6 +1,7 @@ # Getting started -This guide will demonstrate how to setup build and test automation for your Unity project hosted on gitlab using gitlab-ci. +This guide will demonstrate how to setup build and test automation for your Unity project hosted on +gitlab using gitlab-ci. ## Overall steps @@ -12,15 +13,21 @@ This guide will demonstrate how to setup build and test automation for your Unit ## First time using Gitlab CI? -Read the official documentation about [Getting started with GitLab CI/CD](https://docs.gitlab.com/ce/ci/quick_start/). +Read the official documentation about +[Getting started with GitLab CI/CD](https://docs.gitlab.com/ce/ci/quick_start/). Any subsequent steps assume you have read the above. ## Supported versions -The [unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) is based on [unity3d](https://github.com/game-ci/docker/) docker images from [game-ci](https://github.com/game-ci). Any version in the [docker hub `unityci/editor` tags list](https://hub.docker.com/r/unityci/editor/tags) can be used to test and build projects. +The [unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) is +based on [unity3d](https://github.com/game-ci/docker/) docker images from +[game-ci](https://github.com/game-ci). Any version in the +[docker hub `unityci/editor` tags list](https://hub.docker.com/r/unityci/editor/tags) can be used to +test and build projects. -It's generally considered good practice to use the same Unity version for your CI/CD setup as you do to develop your project. +It's generally considered good practice to use the same Unity version for your CI/CD setup as you do +to develop your project. ## Video tutorial @@ -36,16 +43,25 @@ It's generally considered good practice to use the same Unity version for your C ### I don't have a Unity project yet -1. Fork [the unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) +1. Fork + [the unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) 1. Clone the fork you just created locally 1. Continue to activation instructions ### I already have my own Unity project -1. Clone [the unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) -1. Copy [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) to the root of your repository, [`Assets/Scripts/Editor/BuildCommand.cs`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/Assets/Scripts/Editor/BuildCommand.cs) and [`ci` folder](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/ci) to your project: +1. Clone + [the unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) +1. Copy + [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) + to the root of your repository, + [`Assets/Scripts/Editor/BuildCommand.cs`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/Assets/Scripts/Editor/BuildCommand.cs) + and [`ci` folder](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/ci) to your + project: - Assuming you've cloned the example project in the parent folder of your project, and your Unity project is at the root of your repository, execute these commands from the root folder of your project: + Assuming you've cloned the example project in the parent folder of your project, and your Unity + project is at the root of your repository, execute these commands from the root folder of your + project: ```bash mkdir -p Assets/Scripts/Editor/ @@ -54,6 +70,11 @@ It's generally considered good practice to use the same Unity version for your C cp ../unity3d-gitlab-ci-example/Assets/Scripts/Editor/BuildCommand.cs ./Assets/Scripts/Editor/ ``` -1. Open and edit the [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) you copied to your project and update [the variables](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml#L7-13) with the versions you need. Your Unity project version can be found in `ProjectSettings/ProjectVersion.txt`. +1. Open and edit the + [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) + you copied to your project and update + [the variables](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml#L7-13) + with the versions you need. Your Unity project version can be found in + `ProjectSettings/ProjectVersion.txt`. 1. If your Unity project is not at the root of your repository, also update UNITY_DIR variable. 1. Continue to activation instructions diff --git a/versioned_docs/version-1/05-gitlab/02-activation.mdx b/versioned_docs/version-1/05-gitlab/02-activation.mdx index 7ae2da08..ba4cb71b 100644 --- a/versioned_docs/version-1/05-gitlab/02-activation.mdx +++ b/versioned_docs/version-1/05-gitlab/02-activation.mdx @@ -1,16 +1,21 @@ # Activation -There are a few methods available, if you're using gitlab-ci, the easiest method in the current documentation is using gitlab-ci. +There are a few methods available, if you're using gitlab-ci, the easiest method in the current +documentation is using gitlab-ci. ## Unity Personal ### a. Using gitlab-ci -Once you've added all required files to your project (mainly [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml)), there should be a manual step that can be triggered for activation. +Once you've added all required files to your project (mainly +[`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml)), +there should be a manual step that can be triggered for activation. -1. Visit your project's settings > CI/CD > Variables and add `UNITY_USERNAME` and `UNITY_PASSWORD` with your credentials. Make sure to use your Unity3d _email address_ for `UNITY_USERNAME`. +1. Visit your project's settings > CI/CD > Variables and add `UNITY_USERNAME` and `UNITY_PASSWORD` + with your credentials. Make sure to use your Unity3d _email address_ for `UNITY_USERNAME`. 1. Push your first commit to your project and visit CI/CD Pipelines. -1. Locate your latest job, there should be a `play` button, click on it and click `get-activation-file` +1. Locate your latest job, there should be a `play` button, click on it and click + `get-activation-file` 1. Wait for the job to run and follow instructions in the console ### b. Locally @@ -20,7 +25,9 @@ All you need is [docker](https://www.docker.com/) installed on your machine. 1. Clone this project 2. Pull the docker image and run bash inside, passing Unity username and password to env - _hint: you should write this to a shell script and execute the shell script so you don't have your credentials stored in your bash history_. Also make sure you use your Unity3d _email address_ for `UNITY_USERNAME` env var. + _hint: you should write this to a shell script and execute the shell script so you don't have + your credentials stored in your bash history_. Also make sure you use your Unity3d _email + address_ for `UNITY_USERNAME` env var. ```bash UNITY_VERSION=2020.1.11f1 @@ -67,22 +74,33 @@ All you need is [docker](https://www.docker.com/) installed on your machine. > Can't activate Unity: No sufficient permissions while processing request HTTP error code 401 - Make sure your credentials are valid. You may try to disable 2FA in your account and try again. Once done, you should enable 2FA again for security reasons. See [#11](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/11) for more details. + Make sure your credentials are valid. You may try to disable 2FA in your account and try again. + Once done, you should enable 2FA again for security reasons. See + [#11](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/11) for more details. 5. Copy xml content and save as `unity3d.alf` 6. Open https://license.unity3d.com/manual and answer questions 7. Upload `unity3d.alf` for manual activation 8. Download `Unity_v2018.x.ulf` (`Unity_v2019.x.ulf` for 2019 versions) -9. Copy the content of `Unity_v2018.x.ulf` license file to your CI's environment variable `UNITY_LICENSE`. - _Note: if you are doing this on Windows, chances are the [line endings will be wrong as explained here](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/5#note_95831816). Luckily for you, [`.gitlab-ci.yml`](https://github.com/game-ci/unity3d-ci-example/blob/main/.gitlab-ci.yml) of the example project solves this by removing `\r` character from the ENV variable so you'll be alright_ - [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) will then place the `UNITY_LICENSE` to the right place before running tests or creating the builds. +9. Copy the content of `Unity_v2018.x.ulf` license file to your CI's environment variable + `UNITY_LICENSE`. _Note: if you are doing this on Windows, chances are the + [line endings will be wrong as explained here](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/5#note_95831816). + Luckily for you, + [`.gitlab-ci.yml`](https://github.com/game-ci/unity3d-ci-example/blob/main/.gitlab-ci.yml) of the + example project solves this by removing `\r` character from the ENV variable so you'll be + alright_ + [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) + will then place the `UNITY_LICENSE` to the right place before running tests or creating the + builds. ## Unity Plus/Pro 1. Clone this project 2. Pull the docker image and run bash inside, passing Unity username and password to env - _hint: you should write this to a shell script and execute the shell script so you don't have your credentials stored in your bash history_. Also make sure you use your Unity3d _email address_ for `UNITY_USERNAME` env var. + _hint: you should write this to a shell script and execute the shell script so you don't have + your credentials stored in your bash history_. Also make sure you use your Unity3d _email + address_ for `UNITY_USERNAME` env var. ```bash UNITY_VERSION=2020.1.11f1 @@ -113,7 +131,14 @@ All you need is [docker](https://www.docker.com/) installed on your machine. ``` 4. Wait for the command to finish without errors -5. Obtain the contents of the license file by running `cat /root/.local/share/unity3d/Unity/Unity_lic.ulf` -6. Copy the content to your CI's environment variable `UNITY_LICENSE`. - _Note: if you are doing this on windows, chances are the [line endings will be wrong as explained here](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/5#note_95831816). Luckily for you, [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) solves this by removing `\r` character from the env variable so you'll be alright_ - [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) will then place the `UNITY_LICENSE` to the right place before running tests or creating the builds. +5. Obtain the contents of the license file by running + `cat /root/.local/share/unity3d/Unity/Unity_lic.ulf` +6. Copy the content to your CI's environment variable `UNITY_LICENSE`. _Note: if you are doing this + on windows, chances are the + [line endings will be wrong as explained here](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/5#note_95831816). + Luckily for you, + [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) + solves this by removing `\r` character from the env variable so you'll be alright_ + [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml) + will then place the `UNITY_LICENSE` to the right place before running tests or creating the + builds. diff --git a/versioned_docs/version-1/05-gitlab/03-example-project.mdx b/versioned_docs/version-1/05-gitlab/03-example-project.mdx index 10c567e0..3b7c3db5 100644 --- a/versioned_docs/version-1/05-gitlab/03-example-project.mdx +++ b/versioned_docs/version-1/05-gitlab/03-example-project.mdx @@ -2,20 +2,34 @@ ## About -[The `unity3d-gitlab-ci-example` project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) uses an updated version of the [Unity's Creator Kit: RPG free asset](https://assetstore.unity.com/packages/templates/tutorials/creator-kit-rpg-149309) which is not affiliated with this project at all. Feel free to explore it, dialogs are a bit different ;) - -The example project is a Proof of Concept to **run unity3d tests and builds inside a CI** using **[game-ci/docker unity editor docker images](https://github.com/game-ci/docker)**. It currently creates builds for Windows, Linux, macOS, webgl, Linux IL2cpp, Android and iOS Xcode project. The webgl build is published by the CI to [gitlab-pages](https://about.gitlab.com/features/pages/). **You can try the built project on [the published gitlab-pages](https://game-ci.gitlab.io/unity3d-gitlab-ci-example/)**. +[The `unity3d-gitlab-ci-example` project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) +uses an updated version of the +[Unity's Creator Kit: RPG free asset](https://assetstore.unity.com/packages/templates/tutorials/creator-kit-rpg-149309) +which is not affiliated with this project at all. Feel free to explore it, dialogs are a bit +different ;) + +The example project is a Proof of Concept to **run unity3d tests and builds inside a CI** using +**[game-ci/docker unity editor docker images](https://github.com/game-ci/docker)**. It currently +creates builds for Windows, Linux, macOS, webgl, Linux IL2cpp, Android and iOS Xcode project. The +webgl build is published by the CI to [gitlab-pages](https://about.gitlab.com/features/pages/). +**You can try the built project on +[the published gitlab-pages](https://game-ci.gitlab.io/unity3d-gitlab-ci-example/)**. ## Git remotes -[The `unity3d-gitlab-ci-example` project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) is hosted on multiple remotes to provide examples for [Gitlab-CI](https://about.gitlab.com/product/continuous-integration/), [Travis CI](https://travis-ci.org/) and [CircleCI](https://circleci.com/) +[The `unity3d-gitlab-ci-example` project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) is +hosted on multiple remotes to provide examples for +[Gitlab-CI](https://about.gitlab.com/product/continuous-integration/), +[Travis CI](https://travis-ci.org/) and [CircleCI](https://circleci.com/) - [github](https://github.com/game-ci/unity3d-ci-example) - [gitlab](https://gitlab.com/game-ci/unity3d-gitlab-ci-example) ## How to run scripts locally -You can execute the local scripts and specify the path of your Unity executable using `UNITY_EXECUTABLE`. You may try this in your project before you setup the whole CI, so you confirm it works with your current unity version 👍. +You can execute the local scripts and specify the path of your Unity executable using +`UNITY_EXECUTABLE`. You may try this in your project before you setup the whole CI, so you confirm +it works with your current unity version 👍. ## Test diff --git a/versioned_docs/version-1/05-gitlab/04-custom-build-options.mdx b/versioned_docs/version-1/05-gitlab/04-custom-build-options.mdx index f5615234..82e66314 100644 --- a/versioned_docs/version-1/05-gitlab/04-custom-build-options.mdx +++ b/versioned_docs/version-1/05-gitlab/04-custom-build-options.mdx @@ -4,9 +4,12 @@ First, you need to understand how build options are passed to the build. ## Build command -See [Assets/Scripts/Editor/BuildCommand.cs](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/Assets/Scripts/Editor/BuildCommand.cs). +See +[Assets/Scripts/Editor/BuildCommand.cs](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/Assets/Scripts/Editor/BuildCommand.cs). -This is the script used during `Unity` command line execution. It is passed to the [`-executeMethod ` command line parameter](https://docs.unity3d.com/Manual/CommandLineArguments.html) like this: +This is the script used during `Unity` command line execution. It is passed to the +[`-executeMethod ` command line parameter](https://docs.unity3d.com/Manual/CommandLineArguments.html) +like this: ```bash unity-editor \ @@ -19,7 +22,8 @@ You need to have this file in your project in order to build your project in the ### Workflow file -See [.gitlab-ci.yml](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml). +See +[.gitlab-ci.yml](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml). You can add `BuildOptions` per target by adding environment variable `BuildOptions`. @@ -38,4 +42,5 @@ If you would like to use several `BuildOptions`, you have to separate all values BuildOptions: AcceptExternalModificationsToPlayer,CompressTextures,ConnectToHost ``` -See [Unity3d `BuildOptions` reference](https://docs.unity3d.com/ScriptReference/BuildOptions.html) for allowed values. +See [Unity3d `BuildOptions` reference](https://docs.unity3d.com/ScriptReference/BuildOptions.html) +for allowed values. diff --git a/versioned_docs/version-1/05-gitlab/05-tests.mdx b/versioned_docs/version-1/05-gitlab/05-tests.mdx index 7aa8fb52..d8ecba9c 100644 --- a/versioned_docs/version-1/05-gitlab/05-tests.mdx +++ b/versioned_docs/version-1/05-gitlab/05-tests.mdx @@ -2,7 +2,8 @@ ## Unity Tests -Unity supports two kinds of tests (`editmode` and `playmode`). The example project supports both. More information and documentation concerning Unity tests can be found here: +Unity supports two kinds of tests (`editmode` and `playmode`). The example project supports both. +More information and documentation concerning Unity tests can be found here: [Unity Test Framework](https://docs.unity3d.com/Packages/com.unity.test-framework@1.1/manual/index.html) ## Example Project Test files @@ -14,4 +15,5 @@ Tests can be found here: ## Code coverage support -**TODO**, but we have support for this in example project. Let's not forget to update this section accordingly :) +**TODO**, but we have support for this in example project. Let's not forget to update this section +accordingly :) diff --git a/versioned_docs/version-1/05-gitlab/06-deployment/android.mdx b/versioned_docs/version-1/05-gitlab/06-deployment/android.mdx index d3c05c96..7c697057 100644 --- a/versioned_docs/version-1/05-gitlab/06-deployment/android.mdx +++ b/versioned_docs/version-1/05-gitlab/06-deployment/android.mdx @@ -1,9 +1,13 @@ # Android -Before `2018.4.8f1` for 2018 versions and before `2019.2.4f1` for 2019 versions, you will need a specific Unity license (because that is not the same docker image). Add the content of your specific Unity license in your CI's environment variable : `UNITY_LICENSE_CONTENT_ANDROID`. _This is not required anymore now that images share a base image [See related change](https://gitlab.com/game-ci/unity3d/merge_requests/63)_ +Before `2018.4.8f1` for 2018 versions and before `2019.2.4f1` for 2019 versions, you will need a +specific Unity license (because that is not the same docker image). Add the content of your specific +Unity license in your CI's environment variable : `UNITY_LICENSE_CONTENT_ANDROID`. _This is not +required anymore now that images share a base image +[See related change](https://gitlab.com/game-ci/unity3d/merge_requests/63)_ -By default the apk is not signed and the build will use the Unity's default debug key. -For _security reasons_, **you should not add your keystore to git**. +By default the apk is not signed and the build will use the Unity's default debug key. For _security +reasons_, **you should not add your keystore to git**. ## Encode your keystore @@ -18,14 +22,17 @@ Copy the result to your CI's environment variable `ANDROID_KEYSTORE_BASE64` Add following environment variables: - `KEYSTORE_PASS`: Keystore pass -- `KEY_ALIAS_NAME`: Keystore alias name to use (if not set, the program will use the alias name set in Project's PlayerSettings) +- `KEY_ALIAS_NAME`: Keystore alias name to use (if not set, the program will use the alias name set + in Project's PlayerSettings) - `KEY_ALIAS_PASS`: Keystore alias pass to use -Note about _keystore security_, if you would like to use another solution for storage, see [Where to Store Android KeyStore File in CI/CD Cycle?](https://android.jlelse.eu/where-to-store-android-keystore-file-in-ci-cd-cycle-2365f4e02e57). +Note about _keystore security_, if you would like to use another solution for storage, see +[Where to Store Android KeyStore File in CI/CD Cycle?](https://android.jlelse.eu/where-to-store-android-keystore-file-in-ci-cd-cycle-2365f4e02e57). ### Android app bundle -`BUILD_APP_BUNDLE` env var is defined in `gitlab-ci.yml`. Set it to `true` to build an `.aab` file. Note: to build an android app bundle, you need an image with **Android NDK**. +`BUILD_APP_BUNDLE` env var is defined in `gitlab-ci.yml`. Set it to `true` to build an `.aab` file. +Note: to build an android app bundle, you need an image with **Android NDK**. See [related issue gableroux/unity3d#61](https://gitlab.com/game-ci/unity3d/issues/61) @@ -35,20 +42,26 @@ The bundle version code must be increment for each deployed build. To simplify the process, the `BUNDLE_VERSION_CODE` env var is used and set as bundle version code. -Currently, for gitlab, `BUNDLE_VERSION_CODE = $CI_PIPELINE_IID`. [Documentation](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) +Currently, for gitlab, `BUNDLE_VERSION_CODE = $CI_PIPELINE_IID`. +[Documentation](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) If you use another CI solution, set a CI env var incrementing for each pipeline. ### Fastlane supply (deployement) -Follow [setup instructions](https://docs.fastlane.tools/actions/supply/) to get a google play console token, then, add the content to env var `GPC_TOKEN`. +Follow [setup instructions](https://docs.fastlane.tools/actions/supply/) to get a google play +console token, then, add the content to env var `GPC_TOKEN`. -Uncomment the `#deploy-android` job in gitlab-ci.yml and replace `com.youcompany.yourgame` by your package name. +Uncomment the `#deploy-android` job in gitlab-ci.yml and replace `com.youcompany.yourgame` by your +package name. -You can change the track `internal` to `alpha`, `beta` or `production` (Note: if you are using the `internal` track you will also have to mark your release as a draft in the `fastlane supply` command using `--release_status draft`). +You can change the track `internal` to `alpha`, `beta` or `production` (Note: if you are using the +`internal` track you will also have to mark your release as a draft in the `fastlane supply` command +using `--release_status draft`). **Gemfile** -You will also need to add a Gemfile to your project to install the `fastlane` gem. Something like the following: +You will also need to add a Gemfile to your project to install the `fastlane` gem. Something like +the following: ``` source "https://rubygems.org" @@ -56,9 +69,12 @@ source "https://rubygems.org" gem "fastlane" ``` -and then copy the file to the current directory prior to installing the gem. eg `cp $CI_PROJECT_DIR/Gemfile .`. +and then copy the file to the current directory prior to installing the gem. eg +`cp $CI_PROJECT_DIR/Gemfile .`. -That is the simplest way with command line but you can also make `fastlane/Fastfile` and `fastlane/Appfile`, with the following command after building a temporary gradle project (export gradle project option in Unity build settings): +That is the simplest way with command line but you can also make `fastlane/Fastfile` and +`fastlane/Appfile`, with the following command after building a temporary gradle project (export +gradle project option in Unity build settings): ```bash fastlane init @@ -70,4 +86,6 @@ Then run the following command: fastlane supply init ``` -and update all metadata, images, changelogs, etc... These will be uploaded to the store everytime. Refer to [fastlane supply documentation](https://docs.fastlane.tools/actions/supply/) for more details. +and update all metadata, images, changelogs, etc... These will be uploaded to the store everytime. +Refer to [fastlane supply documentation](https://docs.fastlane.tools/actions/supply/) for more +details. diff --git a/versioned_docs/version-1/05-gitlab/06-deployment/ios.mdx b/versioned_docs/version-1/05-gitlab/06-deployment/ios.mdx index 0f11c842..41154bc0 100644 --- a/versioned_docs/version-1/05-gitlab/06-deployment/ios.mdx +++ b/versioned_docs/version-1/05-gitlab/06-deployment/ios.mdx @@ -25,26 +25,31 @@ brew install fastlane 1. Fill the field `Signing Team ID` 1. Ensure `Automatically Sign` is unchecked 1. iOS Provisioning Profile - 1. `ProfileID`: `match AppStore your_bundle_identifier` _Replace `your_bundle_identifier` by yours_ + 1. `ProfileID`: `match AppStore your_bundle_identifier` _Replace `your_bundle_identifier` by + yours_ 1. `ProfileType`: `Distribution` ## XCode project Make a first iOS build using your mac from Unity, that will create an xcode project. Ensure you target the same path as the CI. -Ex: if you let `BUILD_NAME: ExampleProjectName` in `.gitlab-ci.yml`, your xcode project must be at the root of the following path: `.\Builds\iOS\ExampleProjectName\` +Ex: if you let `BUILD_NAME: ExampleProjectName` in `.gitlab-ci.yml`, your xcode project must be at +the root of the following path: `.\Builds\iOS\ExampleProjectName\` ## App on portal -Make sure that you have setup your app on the Apple Developer Portal and the App Store Connect or use [fastlane produce](https://docs.fastlane.tools/actions/produce/) to create it. +Make sure that you have setup your app on the Apple Developer Portal and the App Store Connect or +use [fastlane produce](https://docs.fastlane.tools/actions/produce/) to create it. ## Fastlane initialization -Open the terminal at the same path then run `fastlane init`, follow instructions to generate Appfile and default Fastfile. +Open the terminal at the same path then run `fastlane init`, follow instructions to generate Appfile +and default Fastfile. ## Provisioning profile -Run `fastlane match init`, follow instructions, select `appstore` provisioning profile type. ([Documentation](https://docs.fastlane.tools/actions/match/)) +Run `fastlane match init`, follow instructions, select `appstore` provisioning profile type. +([Documentation](https://docs.fastlane.tools/actions/match/)) ## Make lane @@ -66,7 +71,8 @@ platform :ios do end ``` -Note about `upload_to_testflight`: Change "Team" to your internal tester or remove `(groups:["Team"])` if you want set manually who can test the build +Note about `upload_to_testflight`: Change "Team" to your internal tester or remove +`(groups:["Team"])` if you want set manually who can test the build ### Related documentation @@ -114,9 +120,11 @@ sudo chmod +x /usr/local/bin/gitlab-runner - [Source (if you would like to check)](https://docs.gitlab.com/runner/install/osx.html) -Go to your project gitlab page, then go to `settings` -> `CI/CD` -> `Runners` -> `Specitic Runners` -> `Set up a specific Runner manually` -> take note of the token +Go to your project gitlab page, then go to `settings` -> `CI/CD` -> `Runners` -> `Specitic Runners` +-> `Set up a specific Runner manually` -> take note of the token -[Follow these instructions](https://docs.gitlab.com/runner/register/index.html) to register your mac as a gitlab-runner for your specific project. +[Follow these instructions](https://docs.gitlab.com/runner/register/index.html) to register your mac +as a gitlab-runner for your specific project. Follow **macOS** instructions **without** sudo command for registration. - Tags: set `mac,ios` @@ -132,4 +140,5 @@ gitlab-runner start Runner is installed and will be run after a system reboot. -Now, you can uncomment the job `build-and-deploy-ios` in `.gitlab-ci.yml` to make the app build and deployement work. +Now, you can uncomment the job `build-and-deploy-ios` in `.gitlab-ci.yml` to make the app build and +deployement work. diff --git a/versioned_docs/version-1/06-troubleshooting/common-issues.mdx b/versioned_docs/version-1/06-troubleshooting/common-issues.mdx index 0f661592..0db6a41b 100644 --- a/versioned_docs/version-1/06-troubleshooting/common-issues.mdx +++ b/versioned_docs/version-1/06-troubleshooting/common-issues.mdx @@ -27,7 +27,8 @@ Make sure your branch is clean and all files are indeed present: - All packages listed; - No pre-build steps that change your project differently from how that happens locally; -A good way to verify this, is to (locally) clone the Unity project in a new folder and run the build from there. +A good way to verify this, is to (locally) clone the Unity project in a new folder and run the build +from there. ### Gradle error @@ -48,13 +49,16 @@ There are 2 possible solutions: ### 'Non-whitespace before first tag. Line: 0 Column: 1 Char: 㼼' during manual activation -When activating a license on [license.unity3d.com](https://license.unity3d.com/), you may encounter the following error message: +When activating a license on [license.unity3d.com](https://license.unity3d.com/), you may encounter +the following error message: > Non-whitespace before first tag. Line: 0 Column: 1 Char: 㼼 Here's Unity's workaround: -> Unfortunately, this is a known issue our end. The relevant team are in the process of working on a fix as we speak, in the meantime there is a workaround. Try renaming the `alf` file with a command to convert characters on it with a `iconv` command. +> Unfortunately, this is a known issue our end. The relevant team are in the process of working on a +> fix as we speak, in the meantime there is a workaround. Try renaming the `alf` file with a command +> to convert characters on it with a `iconv` command. #### Solution @@ -65,6 +69,8 @@ iconv -f UTF-8 -t utf-16BE Unity_${version}.alf > Unity_${version}.utf16be.alf ### I use my google account to login to Unity, how do I get my username and password? -If you are using google account you can have some issue with activating unity. You just need to go on the unity website, settings, security and change your password. Then use your google email and your new password and it will work just fine ;) +If you are using google account you can have some issue with activating unity. You just need to go +on the unity website, settings, security and change your password. Then use your google email and +your new password and it will work just fine ;) [Source](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/issues/149) diff --git a/versioned_docs/version-1/index.mdx b/versioned_docs/version-1/index.mdx index 6e0306c8..03ac8283 100644 --- a/versioned_docs/version-1/index.mdx +++ b/versioned_docs/version-1/index.mdx @@ -4,10 +4,12 @@ sidebar_position: 1 # Introduction -This site hosts all documentation for GameCI, and will help you setup Continuous Integration for your game projects. +This site hosts all documentation for GameCI, and will help you setup Continuous Integration for +your game projects. -Continuous Integration is a widely-used practice where automated pipelines check the -latest code changes actually work, before merging them into the main branch. This helps developers stay in the flow and release faster and (ultimately) with more confidence. +Continuous Integration is a widely-used practice where automated pipelines check the latest code +changes actually work, before merging them into the main branch. This helps developers stay in the +flow and release faster and (ultimately) with more confidence. Follow the development on [GitHub](https://github.com/game-ci/documentation).