game-ci · AndrewKahr · Mar 29, 2023 · webbertakken · Mar 29, 2023 · webbertakken
diff --git a/docs/03-github/04-builder.mdx b/docs/03-github/04-builder.mdx
@@ -315,25 +315,7 @@ _**required:** `false`_ _**default:** `androidPackage`_
 
 #### androidAppBundle
 
-**[Deprecated] Please use androidExportType instead.**
-
-Set this flag to `true` to build '.aab' instead of '.apk'.
-
-```yaml
-- uses: game-ci/unity-builder@v2
-  with:
-    androidAppBundle: true
-    androidKeystoreName: user.keystore
-    androidKeystoreBase64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
-    androidKeystorePass: ${{ secrets.ANDROID_KEYSTORE_PASS }}
-    androidKeyaliasName: ${{ secrets.ANDROID_KEYALIAS_NAME }}
-    androidKeyaliasPass: ${{ secrets.ANDROID_KEYALIAS_PASS }}
-```
-
-You should also set all the Android Keystore options (see below). Refer to (this
-section)[/docs/github/deployment/android#3-generate-an-upload-key-and-keystore] for keystore setup.
-
-_**required:** `false`_ _**default:** `false`_
+**[Removed in V3] Please use androidExportType instead.**
 
 #### androidKeystoreName
 
@@ -447,6 +429,20 @@ ie `3.4.0`. An empty string represents the latest available version on homebrew.
 
 _**required:** `false`_ _**default:** `""`_
 
+#### dockerWorkspacePath
+
+Allows customizing the build path within the container in case there are hardcoded paths generated
+during the build. For example building an IOS XCode project on Linux and moving to a new path on
+MacOS occasionally leads to broken paths requiring this override to ensure the paths match.
+
+Paths should be of format `/path/to/build`, ie `/build`. On Windows, leave off the drive letter
+specification. For example `C:\build` becomes `/build`. There should be no trailing slash in the
+path and the path should be absolute. The path will automatically be created within the container if
+it does not exist. It is recommended to use a path that doesn't already exist within the container
+to avoid any conflicts.
+
+_**required:** `false`_ _**default:** `"/github/workspace"`_
+
 ## Outputs
 
 Below are outputs that can be accessed by using `${{ steps.myBuildStep.outputs.outputName }}`, where

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -49,11 +49,14 @@ const config = {
           lastVersion: 'current',
           versions: {
             current: {
-              label: 'v2 (current)',
+              label: 'v3 (current)',
             },
             1: {
               label: 'v1',
             },
+            2: {
+              label: 'v2',
+            },
           },
           sidebarPath: require.resolve('./sidebars.js'),
           // Please change this to your repo.

diff --git a/versioned_docs/version-2/02-getting-started/index.mdx b/versioned_docs/version-2/02-getting-started/index.mdx
@@ -0,0 +1,39 @@
+# Getting started
+
+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.
+
+To get started creating your workflow, you need 3 things:
+
+- A Unity project
+- A Git host (GitHub, GitLab, your private server, etc.)
+- A CI system (GitHub Actions, GitLab pipelines, CircleCI, TravisCI, Jenkins, etc.)
+
+## Preparing the 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. Please note that you may have to extend this file to ignore the temporary files
+created by the runners, as the creation of these temporary files may cause a runners' local branch
+to become dirty (more info [here](/docs/troubleshooting/common-issues#branch-is-dirty])):
+
+Two common temporary folders that are created by GameCI are `artifacts` and `CodeCoverage`. You can
+ignore them by adding the following lines to your `.gitignore`:
+
+```
+# Ignore temporaries from GameCI
+/[Aa]rtifacts/
+/[Cc]odeCoverage/
+```
+
+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-2/03-github-cloud-runner/01-introduction.mdx b/versioned_docs/version-2/03-github-cloud-runner/01-introduction.mdx
@@ -0,0 +1,104 @@
+# Introduction
+
+## Concept - What Does Cloud Runner Do
+
+**Cloud Runner enables you to run, build and test (Unity) projects in the cloud. You can start jobs
+from the command line, the "Workbench" GUI in the Unity Editor or from GitHub Actions.**
+
+**Cloud Runner 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 uses git to track and syncronize 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. **Cloud runner is flexible and elastic**
+   1. _You can balance your use of high-performance and cost saving modes._ Configurable cost/speed
+      effeciency
+   2. _Works great for projects of almost any size, from AAA projects and assets to micro projects_
+   3. _Extended configuration options._ More control over disk size, memory and CPU
+   4. _Easily scale all job resources as your project grows_ e.g storage, CPU and memory
+2. **Scale fully on demand from zero (not in use) to many concurrent jobs.** Benefits from
+   "pay-for-what-you-use" cloud billing models. We have made an effort to make sure that it costs
+   you nothing (aside from artifact and cache storage) while there are no builds running (no
+   guarantees)
+3. **Easy setup and configuration**
+4. **Run custom jobs** and extend the system for any workload
+
+## Why not cloud runner?
+
+1. Your project is small in size. Below 5GB Cloud Runner should not be needed.
+2. You already have dedicated servers running you can use.
+
+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.
+
+# 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.
+
+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.
+
+### Supported Cloud Runner Platforms
+
+```md
+| Cloud Provider Platform | Release Status     |
+| ----------------------- | ------------------ |
+| Kubernetes              | ✔️ preview release |
+| AWS                     | ✔️ full release    |
+| GCP                     | ⚠ Considered       |
+| 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._ _Kubernetes support currently requires cloud storage,
+only S3 support is built-in._
+
+```md
+| Git Platform          | Release Status     |
+| --------------------- | ------------------ |
+| GitHub                | ✔️ full release    |
+| GitLab                | ✔️ preview release |
+| Command Line          | ✔️ preview release |
+| Any Git repository    | ✔️ preview release |
+| Any Git automation/Ci | ✔️ preview release |
+```
+
+## External Links
+
+### Cloud Runner Releases
+
+[Game CI Releases - GitHub](https://github.com/game-ci/unity-builder/releases) _Packaged and
+released with game-ci's unity-builder module._
+
+### Open Incoming Pull Requests
+
+[Cloud Runner PRs - GitHub](https://github.com/game-ci/unity-builder/pulls?q=is%3Apr+cloud+runner)
+
+### 💬Suggestions and 🐛Bugs (GitHub Issues):
+
+[Game CI Issues - GitHub](https://github.com/game-ci/unity-builder/labels/cloud-runner)
+
+### Community
+
+**Share your feedback with us!**
+
+- [**Discord Channel**](https://discord.com/channels/710946343828455455/789631903157583923)
+- [**Feedback Form**](https://forms.gle/3Wg1gGf9FnZ72RiJ9)
diff --git a/versioned_docs/version-2/03-github-cloud-runner/02-game-ci-vs-cloud-runner.mdx b/versioned_docs/version-2/03-github-cloud-runner/02-game-ci-vs-cloud-runner.mdx
@@ -0,0 +1,42 @@
+# Game-CI vs Cloud Runner
+
+# Standard Game-CI (Use Cases)
+
+The Game CI core is a maintained 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._
+
+# Cloud Runner (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.
+
+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 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._
+
+_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._
diff --git a/...ed_docs/version-2/03-github-cloud-runner/03-getting-started/01-command-line.mdx b/...ed_docs/version-2/03-github-cloud-runner/03-getting-started/01-command-line.mdx
@@ -0,0 +1,47 @@
+# Command Line (Preview)
+
+You can install Game CI locally and start cloud runner jobs from the command line or by integrating
+your own tools. All parameters in [API Reference](../api-reference) can be specified as command line
+input fields.
+
+# Install
+
+Currently (development)
+
+```bash
+git clone https://github.com/game-ci/unity-builder.git
+yarn install
+yarn run cli -m {mode parameter} --projectPath {Your project path} {... other command line parameters}
+```
+
+# 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:
+
+```bash
+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_
+
+# Main Command Parameters
+
+- Default: `cli` (runs a standard build workflow)
+- See API Reference "Modes"
+
+# Keeping command line parameters short
+
+You can avoid specifying long command line input for credentials by using environment variables or
+[the input override feature](../advanced-topics/configuration-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.
+
+```bash
+yarn run cli --populateOverride true --readInputFromOverrideList UNITY_EMAIL,UNITY_SERIAL,UNITY_PASSWORD --readInputOverrideCommand="gcloud secrets versions access 1 --secret=\"{0}\""
+```
diff --git a/versioned_docs/version-2/03-github-cloud-runner/03-getting-started/02-aws.mdx b/versioned_docs/version-2/03-github-cloud-runner/03-getting-started/02-aws.mdx
@@ -0,0 +1,90 @@
+# GitHub Actions - AWS
+
+## Requirements
+
+- You must have an AWS account setup and ready to create resources.
+- Create a service account and generate an AWS access key and key id.
+
+## AWS Credentials
+
+Setup the following as `env` variables for cloud runner to use:
+
+- `AWS_ACCESS_KEY_ID`
+- `AWS_SECRET_ACCESS_KEY`
+- `AWS_DEFAULT_REGION` (should be the same AWS region as the base stack e.g `eu-west-2`)
+
+If you're using GitHub you can use a GitHub Action:
+
+```yaml
+- name: Configure AWS Credentials
+  uses: aws-actions/configure-aws-credentials@v1
+  with:
+    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+    aws-region: eu-west-2
+```
+
+_Note:_ _This enables Cloud Runner access AWS._
+
+## Configuration For AWS Cloud Runner Jobs
+
+Refer to [Configuration page](../api-reference) 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:
+[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
+
+- Values are represented as 1024:1 GB or CPU.
+- Do not include the vCPU or GB suffix.
+- 1 CPU can go to a max of 6 GB of memory. 2 CPU's are required to go higher.
+
+#### Valid CPU and Memory Values
+
+```yaml
+- cloudRunnerMemory: 4096
+- cloudRunnerCpu: 1024
+```
+
+## Example
+
+```yaml
+- uses: game-ci/unity-builder@cloud-runner-develop
+  id: aws-fargate-unity-build
+  timeout-minutes: 25
+  with:
+    cloudRunnerCluster: aws
+    versioning: None
+    projectPath: ${{ matrix.projectPath }}
+    unityVersion: ${{ matrix.unityVersion }}
+    targetPlatform: ${{ matrix.targetPlatform }}
+    gitPrivateToken: ${{ secrets.GITHUB_TOKEN }}
+    # You may want to export your builds somewhere external so you can access them outside of Cloud Runner jobs via the postBuildSteps:
+    postBuildSteps: |
+      - name: upload
+        image: amazon/aws-cli
+        commands: |
+          aws configure set aws_access_key_id $AWS_ACCESS_KEY_ID --profile default
+          aws configure set aws_secret_access_key $AWS_SECRET_ACCESS_KEY --profile default
+          aws configure set region $AWS_DEFAULT_REGION --profile default
+          aws s3 ls
+          aws s3 ls game-ci-test-storage
+          ls /data/cache/$CACHE_KEY
+          ls /data/cache/$CACHE_KEY/build
+          aws s3 cp /data/cache/$CACHE_KEY/build/build-$BUILD_GUID.zip s3://game-ci-test-storage/$CACHE_KEY/build-$BUILD_GUID.zip
+        secrets:
+        - name: awsAccessKeyId
+          value: ${{ secrets.AWS_ACCESS_KEY_ID }}
+        - name: awsSecretAccessKey
+          value: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+        - name: awsDefaultRegion
+          value: eu-west-2
+```
+
+_[Custom Steps](../advanced-topics/custom-jobs/custom-steps)_
+
+A full workflow example can be seen in builder's
+[Cloud Runner GitHub sourcecode for GitHub Pipeline](https://github.com/game-ci/unity-builder/blob/309d668d637ae3e7ffe90d61612968db92e1e376/.github/workflows/cloud-runner-pipeline.yml#L109).