From 721912a73e027c33ce2c98a2d12c5a590ffe2417 Mon Sep 17 00:00:00 2001 From: "pre-shared-workflows-auth[bot]" <168739156+pre-shared-workflows-auth[bot]@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:37:56 +0000 Subject: [PATCH] chore: publish 5 skills (build-live-game, manage-cloud-build, new-unity-project, +2) --- skills/build-live-game/SECURITY.md | 18 +++ skills/build-live-game/SKILL.md | 18 ++- .../build-live-game/references/link-cloud.md | 11 ++ skills/manage-cloud-build/SKILL.md | 6 +- .../references/analyze-build-failure.md | 54 ++++++--- .../references/create-build-target.md | 6 +- .../references/example-report.md | 4 +- .../references/failure-knowledge.md | 4 +- .../references/source-control.md | 63 +++------- skills/new-unity-project/SECURITY.md | 2 +- skills/new-unity-project/SKILL.md | 37 +++++- skills/setup-multiplayer-services/SECURITY.md | 17 +++ skills/setup-multiplayer-services/SKILL.md | 50 +++++++- .../references/examples.md | 2 +- .../references/implementation-fit.md | 4 +- .../references/workflows-prerequisites.md | 2 + skills/unity-cli/CHANGELOG.md | 36 +++++- skills/unity-cli/SKILL.md | 40 +++--- .../references/auth-license-cloud.md | 8 +- skills/unity-cli/references/build-run-test.md | 45 +++---- .../unity-cli/references/cloud-automation.md | 114 ++++++++++++++++-- skills/unity-cli/references/collaboration.md | 43 ++++--- .../references/diagnostics-maintenance.md | 7 +- .../unity-cli/references/editors-install.md | 17 +-- .../references/integration-advanced.md | 35 ++++-- .../references/playmode-verification-loop.md | 9 ++ .../references/projects-templates.md | 70 +++++++---- .../unity-cli/references/version-control.md | 2 +- 28 files changed, 519 insertions(+), 205 deletions(-) create mode 100644 skills/build-live-game/SECURITY.md create mode 100644 skills/build-live-game/references/link-cloud.md create mode 100644 skills/setup-multiplayer-services/SECURITY.md diff --git a/skills/build-live-game/SECURITY.md b/skills/build-live-game/SECURITY.md new file mode 100644 index 0000000..8316537 --- /dev/null +++ b/skills/build-live-game/SECURITY.md @@ -0,0 +1,18 @@ +# Security notes: build-live-game + +This skill has the agent read state from the user's open Unity Editor through `unity command script eval` to read the Cloud project ID after linking and the result of a feature it changed. Automated skill scanners flag that as a powerful capability. It is intentional, and it is limited by the safeguards below. + +## Accepted risks + +| Risk | Capability | Why it is accepted | +|---|---|---| +| `SEC_POWER_CAP` | Runs C# in the user's open Editor through `unity command script eval` | It only reaches the Editor the user already has open, on their own machine, as that user, so it grants nothing they couldn't do themselves. `script eval` sits behind the Pipeline capability gate. No code fetched from a remote source is run. The skill uses it only to read state, and uses `unity command console status` for the console check. | + +## Mitigations + +- **Only the user's own Editor.** `unity command script eval` talks to the Editor open on this machine. It can't reach another machine or another user's Editor. +- **Capability gate.** `script eval` is only available when the project's Pipeline package provides it. +- **No remote code.** The agent runs C# it writes itself to read Editor state. Nothing downloaded from outside is executed. +- **Reads, not logging.** `script eval` only reads state; the skill reads results with it instead of adding logging. The one write it makes for verification is a temporary client Cloud Save call that checks an Access Control policy rejects it, removed afterwards. +- **Play mode only when needed.** The skill enters Play mode for that Access Control check and, when the user asks for proof or a fault is suspected, once to run the feature. +- **One Editor.** Every `unity command` names the project with `--project-path`, so it can't drive another project's Editor. diff --git a/skills/build-live-game/SKILL.md b/skills/build-live-game/SKILL.md index d6204f5..56ffe66 100644 --- a/skills/build-live-game/SKILL.md +++ b/skills/build-live-game/SKILL.md @@ -8,11 +8,11 @@ description: Builds and operates a live game's backend with Unity Gaming Service ## Before You Start 1. Read the Editor version from `ProjectSettings/ProjectVersion.txt` and the installed UGS package versions from `Packages/packages-lock.json`. Pick the steps below that match (for example `.ccmu` or `.ccmr` modules), because the right workflow depends on the Editor and package versions. -2. Check whether the project is linked to a Unity project ID and environment (**Edit > Project Settings > Services**), and ask the user to link it if it is not. -3. Create a restore point you can roll back to if your changes fail: commit the project in version control. If there is no version control, copy the project folder instead. +2. Create a restore point you can roll back to if your changes fail: commit the project in version control. If there is no version control, copy the project folder instead. Do this before linking or any other write. +3. If the project has no Unity Cloud link, see [Link the Project to Unity Cloud](#link-the-project-to-unity-cloud). Advice-only questions stay read-only: give the `unity projects link cloud` command. 4. Before you go forward with a workflow or diagnosis, open and read the documentation pages for the service you will use (see [Documentation Map](#documentation-map)) and the matching file under `references/`, and name the pages you read in your response. This is because your training knowledge about Unity Gaming Services might be out of date, incorrect, or for the wrong package version. 5. Do only what's asked. Don't change unrelated assets or files. Avoid long explanations. -6. When you change runtime behaviour, add `Debug.Log` lines at the points you need to verify (sign-in complete, module call returned, config fetched). You read them in Play mode during [Validation](#validation). +6. Never leave verification code in the user's script. Never build logging or detection they didn't ask for. ## Glossary @@ -25,7 +25,7 @@ description: Builds and operates a live game's backend with Unity Gaming Service | **Script** | Server-side JavaScript endpoint. Legacy: maintain existing ones, don't write new ones | | **CloudBehaviour** | Experimental Cloud Code class that generates client bindings, synchronized state and push events | | **Protected data** | Cloud Save player data that the player can read but only server code can write | -| **Custom data** | Cloud Save game-wide data, not tied to one player, written only by server code | +| **Custom data** | Cloud Save game-wide data, not tied to one player, server-written only | | **Cloud resource file** | A deployable config file (`.rc`, `.ac`, `.ccmu`, `.ccmr`, `.lb`, `.ugo`) that the Deployment Window pushes to a UGS environment | ## Documentation Map @@ -61,6 +61,7 @@ Pages to read before acting: - [Before You Start](#before-you-start) - [Glossary](#glossary) - [Documentation Map](#documentation-map) +- [Link the Project to Unity Cloud](#link-the-project-to-unity-cloud) - [Initialization Pattern](#initialization-pattern) - [Architecture — How Packages Combine](#architecture--how-packages-combine) - [Core Services — Quick Reference](#core-services--quick-reference) @@ -69,6 +70,10 @@ Pages to read before acting: - [Detailed References](#detailed-references) - [Final Report](#final-report) +## Link the Project to Unity Cloud + +Service calls need a linked Cloud project. Link only when the task needs service calls or asks to link, and only after the restore point. Follow every step in [references/link-cloud.md](references/link-cloud.md): choose backend and COPPA setting, check the Pipeline package, close the Editor, link, reopen, verify. + ## Initialization Pattern Every UGS game starts the same way. `com.unity.services.core` must initialize first, then the player signs in: @@ -225,7 +230,8 @@ After writing code for a live game feature, run these checks in order. If one fa 3. Check that sensitive writes (XP, rewards, currency) go through Cloud Code: search the client code for Cloud Save `SaveAsync` calls on those keys and move any you find into a module. Also confirm each Cloud Save read uses the access class of the bucket that was written to, because a mismatched class returns no data. 4. Deploy the cloud resource files the feature uses (`.rc`, `.ac`, `.ccmu` or `.ccmr`, `.lb`; skip the types it does not use) to the active environment with the `Deploy.cs` script in `references/deployment.md`, and read its output: every file must report `Success`. A file reported as `not a deployable item`, or with an `Error` status, has failed. If the project does not have both packages the script needs, `com.unity.pipeline` and `com.unity.services.deployment.api`, ask the user to deploy from the Deployment Window and report each file's status. 5. Check Access Control by its effect: if the feature deploys an `.ac` policy that denies direct player writes, enter Play mode, run one direct client Cloud Save write to a key the policy covers (a temporary `SaveAsync` call), and confirm it fails with a `403`. Remove the temporary call afterwards. Skip this step when the feature has no `.ac` file. -6. Enter Play mode, run the feature once, and confirm the `Debug.Log` lines from [Before You Start](#before-you-start) appear in the order you expect and the console has zero errors. +6. Check for zero console errors with `unity command console status`. Pass `--project-path ` to every `unity command` here, so it drives this project's Editor. Older Editors name it `console_status`: check with `unity commands --grep console`. +7. Stop after step 6 unless the user asked for proof or you suspect a specific fault, and report that the feature was not run. To chase that fault, enter Play mode once (`unity command editor.playmode start`), run the feature, read the result (player ID, module return value, config) through `unity command script eval`, not added logging, then repeat step 6. Remove any temporary code afterwards. Take no screenshots. ## Detailed References @@ -249,7 +255,7 @@ After writing code for a live game feature, run these checks in order. If one fa When the work is done, end your response with a short report: -1. What you created or changed: files, packages added to `Packages/manifest.json`, and cloud resource files. +1. What you created or changed: files, packages added to `Packages/manifest.json`, cloud resource files, and the Unity Cloud project you linked (its ID, and whether the link created it). 2. The checks from [Validation](#validation) that you ran and their results, including any you could not run and why. 3. Follow-ups only the user can do, for example: deploy the cloud resources to the target environment, link the project to a Unity project ID and environment, complete a stubbed integration (such as battle pass `PurchasePremium`), or restore from the restore point you created if they reject the changes. 4. Which documentation pages you read. diff --git a/skills/build-live-game/references/link-cloud.md b/skills/build-live-game/references/link-cloud.md new file mode 100644 index 0000000..b6f75a5 --- /dev/null +++ b/skills/build-live-game/references/link-cloud.md @@ -0,0 +1,11 @@ +# Link the Project to Unity Cloud + +UGS calls need a linked Unity Cloud project ID. Linking writes `ProjectSettings/ProjectSettings.asset`: do it only when the task needs service calls or asks to link, after the restore point. Pass `--project-path ` to every `unity command` below, because without it the CLI drives the Editor of the shell's current folder, which may be another project. + +1. A non-empty `cloudProjectId` in `ProjectSettings/ProjectSettings.asset` means it is linked: skip the rest. +2. Without `--cloud-project`, the CLI reuses `UNITY_CLOUD_PROJECT`, then the saved default (`defaultCloudProjectId` from `unity cloud project current --format json`), and creates a project only when both are empty. To reuse one, pass `--cloud-project `. If either is set and the user wants a new one, ask first: `unity cloud project clear-default` clears only the saved default, and the user must unset `UNITY_CLOUD_PROJECT` in their own shell. +3. Check `Packages/manifest.json` for `com.unity.pipeline`: closing gracefully, `--until-ready` and `script eval` need it. If it is missing, add it with `unity pipeline install --project-path ` (Unity 6.0+) and say so in the report. If it can't be added, ask the user to save and close the Editor themselves, and in step 5 check only the asset. +4. `unity close ` exits without saving, so ask the user to save their work first, then run it: an open Editor keeps the old link and can save it back over the new one. +5. Run `unity projects link cloud --format json`, plus `--cloud-project ` when reusing. When it will create a project, first ask whether the game is directed at children under 13 and add `--coppa compliant` if so: the default is `not_compliant`. Never pass `--coppa` with `--cloud-project` (error `COPPA_ARGS_CONFLICT`); change an existing project's COPPA setting in the Unity Cloud dashboard. +6. Verify: if `data.editor.restartRequired` is `true`, an Editor still had the project open: close it, then check the asset still holds the new ID, and if not rerun with `--cloud-project `. Reopen with `unity open --until-ready --format json` (a plain `unity open` returns before the Editor can answer commands) and check `cloudProjectId` in the asset and `CloudProjectSettings.projectId` (via `unity command script eval --project-path `) equal `data.cloudProject`'s ID. On failure, stop and report the error code. +7. Never hand-edit the asset or write an Editor-side linker: a manual edit can mismatch project and organization IDs. diff --git a/skills/manage-cloud-build/SKILL.md b/skills/manage-cloud-build/SKILL.md index 27b2c3e..ebd05f0 100644 --- a/skills/manage-cloud-build/SKILL.md +++ b/skills/manage-cloud-build/SKILL.md @@ -56,7 +56,7 @@ This is because your training knowledge about Unity Build Automation might be ou Prefer fetching a page directly (for example `WebFetch`) over searching (for example `WebSearch`), because it lands on the exact page. Only fetch what you need, and only search if you don't have the exact URL. Replace `` with the following before fetching: - **docs.unity.com (Build Automation)**: no version, because these pages carry none. -- **docs.unity3d.com**: the build's or the project's Unity version as major.minor, for example `6000.3` for a `unityVersion` of `6000_3_26f1`. +- **docs.unity3d.com**: the build's or the project's Unity version as major.minor, for example `6000.3` for a `unityVersion` of `6000_3_26f1`. For Unity 6 and later these pages redirect to `https://docs.unity.com/en-us/engine//`, so follow the redirect. The page index is in [references/topic-map.md](references/topic-map.md): Build Automation pages under `https://docs.unity.com/en-us/build-automation/`, and Unity Manual pages under `https://docs.unity3d.com//Documentation/Manual/`. @@ -65,7 +65,7 @@ The page index is in [references/topic-map.md](references/topic-map.md): Build A 1. Run the workflow's CLI check. If `unity` isn't found, tell the user to install the Unity CLI, and stop. If the check fails, tell the user to update the CLI with `unity self-update`, and stop, because older versions lack the workflow's commands. 2. Run `unity auth status`. If the user isn't signed in, ask them to run `unity auth login`, and stop. 3. Get the organization and project. If the user gave their IDs, or a Unity Cloud Dashboard link with them in the path segments after `organizations/` and `projects/`, use those. Otherwise use the IDs that `unity cloud org current` and `unity cloud project current` print. If they print none, ask the user. Below, `` stands for `--cloud-org --cloud-project `. Put it on every `unity pipeline cloud-build` command, because otherwise the CLI reads its default project, which can hold a same-named target and build. Write both options out in each command rather than in one shell variable, because zsh passes such a variable as a single argument. -4. Run `unity logs --console --level error` and note the errors it lists, so the final step can tell the project's own errors from new ones. If no Editor answers, skip this read and the final step's. +4. Run `unity command console status`. If `groundTruth.consoleErrors` is above 0, also save the errors that `unity logs --console --level error` lists, so the final step can tell the project's own errors from new ones. If no Editor answers, skip this read and the final step's. ## Step 4: Follow the workflow @@ -73,7 +73,7 @@ Follow the workflow's steps in order, including its own checks. ## Final step -1. Run `unity logs --console --level error` again to check the project has zero console errors, because neither workflow may change the project's code or assets. An error that Step 3 already listed is the project's own. If a new one appeared, tell the user what you ran. +1. Run `unity command console status` again to check the project has zero console errors other than its own, because neither workflow may change the project's code or assets. If `groundTruth.consoleErrors` is above 0, list the errors with `unity logs --console --level error` and compare them with the ones Step 3 saved, because a count alone misses one error replacing another. If any is new, tell the user what you ran. 2. Stop there unless the user asked for more proof, because each workflow already checked its own result. If a workflow's check fails, go back to the [topic map](#topic-map), reread the page that covers it, and check whether you missed something. diff --git a/skills/manage-cloud-build/references/analyze-build-failure.md b/skills/manage-cloud-build/references/analyze-build-failure.md index b61c625..250dd32 100644 --- a/skills/manage-cloud-build/references/analyze-build-failure.md +++ b/skills/manage-cloud-build/references/analyze-build-failure.md @@ -12,14 +12,15 @@ Diagnose one failed Unity Build Automation build, then tell the user what failed - Step 2: Check the status - Step 3: Read the evidence - Step 4: Decide the side -- Step 5: Check the verdict +- Step 5: Find what the user can change +- Step 6: Check the verdict - Report ## Commands - **CLI check:** `unity pipeline cloud-build builds failures --help`, because older CLI versions can't read failures, steps or logs. -- Run only these `unity` commands: `unity auth status`, `unity cloud org current`, `unity cloud project current`, `unity logs --console --level error`, `--help` on any command, and `unity pipeline cloud-build builds`, `builds get`, `failures`, `steps` and `log`, `targets get` and `targets auditlog`. Never run `builds start`, `builds cancel` or any other command that changes something, because the user decides what to change and when to rebuild. -- Run only the read-only source control commands in [references/source-control.md](source-control.md), never one that changes the checkout, because the user decides what changes in it. +- Run only these `unity` commands: `unity auth status`, `unity cloud org current`, `unity cloud project current`, `unity command console status`, `unity logs --console --level error`, `--help` on any command, and `unity pipeline cloud-build builds`, `builds get`, `failures`, `steps`, `log`, `artifacts` and `download`, `targets get` and `targets auditlog`. Never run `builds start`, `builds cancel` or any other command that changes something, because the user decides what to change and when to rebuild. +- Read the checkout only as [references/source-control.md](source-control.md) describes, never with a command that changes it, because the user decides what changes in it. - Name a side only on evidence, because a wrong side sends the user to the wrong fix. When the evidence is thin, the side is Unclear. ## Glossary @@ -38,7 +39,7 @@ Diagnose one failed Unity Build Automation build, then tell the user what failed 1. If the user gave a dashboard link, read the target from the segment after `buildtargets/` and the build number from the one after `builds/`. 2. If the user gave a target and a build number, use them. 3. If the user asked about their latest build, run `unity pipeline cloud-build builds --limit 100 --format json`, which lists builds, adding `--build-target ` if they named one, and save the output to the temporary directory. The builds are in `data.items[]`, newest first. Take the first whose `buildStatus` is `failure` if the user said it failed, and the first build otherwise. If the user said it failed and none has, read `--page 2` and on until one has, a page holds fewer than 100 builds, or you've read five pages, and then ask for the build number. -4. Run `unity pipeline cloud-build builds get --build-target --format json`, and pass its `buildtargetid` as `--build-target` on every later read, because the same value works for all of them. +4. Run `unity pipeline cloud-build builds get --build-target --format json`, save it, and read fields from the saved file, because a build with unit tests can return megabytes. Pass its `buildtargetid` as `--build-target` on every later read, because the same value works for all of them. 5. If `builds get` returns not found, run `builds --limit 100 --format json` without `--build-target`, save it, and match the user's name against `buildtargetid` and `buildTargetName`, because users often give a target's display name. If exactly one target matches, run `builds get` again with its `buildtargetid`. If none or several match, ask the user which target. 6. If items 1 to 3 gave no target and build number, ask the user for both, because every read needs both. @@ -53,7 +54,7 @@ Read `buildStatus` from `data` in the `builds get` output: - If it's `queued`, `sentToBuilder`, `started` or `restarted`, tell the user the build hasn't finished, and stop, because the evidence isn't complete yet. - Otherwise, tell the user the status isn't one you recognize, and stop. -Keep these fields from the same output for later steps: `unityVersion`, `xcodeVersion`, `androidSdkVersion`, `machineType.name`, `operatingSystemVersion`, `lastBuiltRevision`, `scmBranch`, `cleanBuild`, `canceledBy`, `credentialsOutdated`, `orgFk`, `projectGuid`, `deletedLogs`, `checkoutStartTime`, `created`, `finished` and `buildGUID`. Some can be missing; leave a missing field out rather than guess it. +Keep these fields from the same output for later steps: `unityVersion`, `xcodeVersion`, `androidSdkVersion`, `machineType.name`, `operatingSystemVersion`, `lastBuiltRevision`, `requestedRevision`, `scmBranch`, `cleanBuild`, `causedBy`, `canceledBy`, `credentialsOutdated`, `orgFk`, `projectGuid`, `deletedLogs`, `checkoutStartTime`, `created`, `finished` and `buildGUID`. Some can be missing; leave a missing field out rather than guess it. ## Step 3: Read the evidence @@ -62,8 +63,8 @@ Read the sources in this order, because each is cheaper than the next. Run each 1. **Failure categories.** Run `unity pipeline cloud-build builds failures --build-target --format json`. Each entry in `data.failures[]` has a `failureIndicatorLabel`, a `displayName`, a `stage`, a `publicMessage`, an optional `link`, the `logline` where the pattern matched, and `stageMatch`. - An empty list is normal. - If `stageMatch` is `false`, the pattern matched outside the stage it was written for, so weigh that category below what the log shows. - - Look each `failureIndicatorLabel` up in [references/failure-knowledge.md](failure-knowledge.md). -2. **Steps.** Run `unity pipeline cloud-build builds steps --build-target --format json`. `data` is an array of the build's steps in order, with `name`, `duration` in milliseconds and `messages[]`. Read any messages on the last steps. Steps are often missing. + - Look each `failureIndicatorLabel` up in [references/failure-knowledge.md](failure-knowledge.md). If it isn't there, confirm its `publicMessage` against the log around its `logline`, and decide from the log as for a build with no category, because the knowledge reference lists only the categories seen before. If the `publicMessage` or the log line already says what to change, pass that on. +2. **Steps.** Run `unity pipeline cloud-build builds steps --build-target --format json`. `data` is an array of the build's steps in order, with `name`, `duration` in milliseconds and `messages[]`. Read the messages on every step, because the step that failed can sit in the middle, and its message can hold an error the log leaves out. Steps are often missing. 3. **The log.** Save it once, masking access tokens as you save, then read slices. `cut` keeps very long lines readable: ```sh @@ -80,25 +81,34 @@ Read the sources in this order, because each is cheaper than the next. Run each - If the line count is 0, the read failed: report the error the CLI printed, because the pipe hides its exit code. - Line numbers in the saved file match each category's `logline`, so read 30 lines either side of each `logline`. - The second `grep` drops `[error]` lines that are Unity's own noise, because they appear in builds that succeed too. If more than 40 lines remain, read the first ones with `head` as well. + - Judge a line by what it says, not by its `[error]` prefix, because the prefix also marks warnings and progress lines from tools such as Xcode, fastlane and Unity, and a real error can sit on a line without it. - Find the decisive line by working back from the summary lines (`Unity player export failed`, `Scripts have compiler errors`, `Finished: FAILURE`) to the error that explains them, such as a `Player export failed. Reason:` line, an exception, or an `error CS` line. + - If the decisive line only says that something failed without naming it, such as unit tests, an Xcode archive, an upload or a validation, find what failed before you decide, because the fix depends on it. Look in the earlier section that ran it, then in `testResults` from the `builds get` output for unit tests, then in a report among the build's artifacts. Name what failed. + - `testResults` holds `unit_test_editmode` and `unit_test_playmode`, each with `passed`, `failed` and an NUnit `test-run` tree. Read only the test cases in the tree, the objects with a `methodname`, whose `result` is `Failed`, with their `fullname` and `failure.message`, because the tree can be megabytes. + - `builds artifacts --build-target --format json` lists `data[]`, each with a `key` and `files[]` that have a `filename` and a `size`. The Xcode log is under `gym_log`, and unit test results are under a `unit_tests` key. Download only such a log or report, with `builds download --build-target --output "/"`, never the build's own output, because that can be gigabytes. Read it in slices, like the build log. + - If the decisive line is a stack trace with no error message above it, read the method and file names in its top frames, and the last `INFO:` lines before it, to tell what the step was doing and what it was reading, such as a configuration file, the checked-out project or credentials. Quote the first frame. - Unity compiles more than once. Decide from the `error CS` lines just above `Scripts have compiler errors`, because errors only in an earlier pass, such as `[Script Updater]` lines, often clear before the end. - The failing section is the last section header above the decisive line. Don't take the last section in the log, because `+ Publishing` runs even after a failed build. - Read no more than ten lines past a `Player export failed` line, and keep keyword searches above it, because the build machine's environment follows it. This limit wins over the 30-line window. - If `deletedLogs` is `true` or the read returns not found, there's no log. Decide from the other evidence. - A one-line log that starts with `[error] Unity Build Automation encountered an error while validating your build` means the build never reached a build machine. The rest of the line is the reason. -4. **Neighbouring builds.** Run `unity pipeline cloud-build builds --build-target --limit 100 --format json`, save it, and read only `build`, `buildStatus`, `cleanBuild`, `lastBuiltRevision`, `scmBranch`, `unityVersion`, `androidSdkVersion`, `xcodeVersion`, `machineType.name` and `operatingSystemVersion` from `data.items[]`. Read `--page 2` and on until you have the build before this one, a page holds fewer than 100 builds, or you've read five pages. Report any neighbour you don't have, such as a later build of the newest build, and decide from the rest. +4. **Neighbouring builds.** Run `unity pipeline cloud-build builds --build-target --limit 100 --format json`, save it, and read only `build`, `buildStatus`, `causedBy`, `canceledBy`, `created`, `cleanBuild`, `lastBuiltRevision`, `scmBranch`, `unityVersion`, `androidSdkVersion`, `xcodeVersion`, `machineType.name`, `operatingSystemVersion` and `changeset` from `data.items[]`. Print only the builds around this one and those the checks below need, and give a long run of failures as its count and first build, because a listing holds up to 100 builds. Read `--page 2` and on until you have a success older than this build, a page holds fewer than 100 builds, or you've read five pages, because the checks below start from the last success before the failures. Report any neighbour you don't have, such as a later build when this one is the newest, and decide from the rest. - A later clean build (`cleanBuild` `true`) that succeeded at the same revision after non-clean failures points at the build's cached files: suggest a clean build. - A later success at the same `lastBuiltRevision`, with the same other values, means the cause was probably temporary. A later success only at other revisions shows the failure hasn't repeated, not that it was temporary, because a commit may have fixed it. - If the failures started where exactly one of those values changed, name it as the likely trigger. If several changed together, list them without picking one. -5. **Target changes.** If the neighbouring builds include a success before the failures, run `unity pipeline cloud-build targets auditlog --limit 100 --format json` and save it. Each entry in `data.items[]` has an `updated` time, a `scope` (`buildTarget`, or `project` for a setting of the whole project) and `lines[]`, each with a `field`, a `label`, and a `from` and `to` that can be missing or null. The window runs from the `created` of the success just before the failures began to the `checkoutStartTime` of the first failure, or its `created` if that's missing, because a change made while that build waited may still apply. Read the entries in the window. While every entry on a page is newer than the window and `nextPage` isn't null, read the next page, up to five pages. + - If this build and the failures just before it were started automatically, count the builds since the last success, or back to the last page you read, and note the `created` of the first, because a schedule or automatic build keeps spending build time on a target that can't succeed until the cause is fixed. `causedBy` is `scheduling` for a build schedule, `polling` for a new commit, and `autoBuildLatest` for a new Unity version. A long run of `api` builds can come from a tool outside the target, such as a CI pipeline: say so, because the user pauses it there. + - If the target failed and then succeeded before, take the last failure before each of up to three such successes, newest first. Save each one's log as in item 3 and search it for the decisive line's text with `grep -a -F`, even when it has the same category, because a summary category such as `unity_player_export_failure` covers different errors. If one holds that text, list what changed at the success that followed it, such as the branch, the Unity version or a clean build, as possible fixes. Name one as the fix only if it's the only value that changed or it relates to the decisive line, because the others may have changed for other reasons. +5. **Target changes.** Run `unity pipeline cloud-build targets auditlog --limit 100 --format json` and save it. Each entry in `data.items[]` has an `updated` time, a `scope` (`buildTarget`, or `project` for a setting of the whole project) and `lines[]`, each with a `field`, a `label`, and a `from` and `to` that can be missing or null. The window runs from the `created` of the success just before the failures began to the `checkoutStartTime` of the first failure, or its `created` if that's missing, because a change made while that build waited may still apply. If no build before this one succeeded and the last page you read held fewer than 100 builds, the target never succeeded: start the window 24 hours before its oldest build, because the settings it started with can be the cause. If you stopped at five pages instead, start the window at the oldest build you read, and say the window is cut off. Read every entry from the start of the window to now: the entries are newest first, so while every entry on a page is newer than the window's start and `nextPage` isn't null, read the next page, up to five pages. - If the CLI reports `auditlog` as an unknown command, skip this read and note it, because older CLI versions lack it. - Leave out `updatingUserEmail` if an entry has one, because it's a user's email address. - Environment variable changes aren't recorded, and a signing change shows only that the credentials changed, so an empty window doesn't rule those out. - Name a changed setting as the likely trigger only if it relates to the decisive line, such as a new Unity version and a compiler error, or a new subfolder and an unrecognized project. Otherwise list the changes without picking one. A setting that relates to the decisive line wins over item 4's list of changed values, because it explains the line. - If a later entry sets the trigger back, say so, because the fix may already be in place. + - If the same field changed three or more times since the window's start, name the values it moved between, because the user is trying settings to get past the failure, and that shows which input they suspect. + - If an entry newer than this build's `created` changed a setting, and no build in the listing was created after that entry, say so, because the user may already have tried the fix and no build has tested it yet. 6. **Code changes.** If the revision changed where the failures started, compare the last success's `lastBuiltRevision` (``) with the first failure's (``): - From the saved build listing, read `changeset[]` (`commitId`, `message`, `numAffectedFiles`) of each build after ``, up to ``. It works for every source control, but some builds have none. Leave out authors, because they're user names. - - If the project's directory is a checkout, read the changed files and their diffs with the commands for its source control in [references/source-control.md](source-control.md). Read any file the decisive line names first, then `Packages/manifest.json`, `ProjectSettings/` and editor build scripts. + - If the project's directory is a checkout, read the changed files and their diffs as [references/source-control.md](source-control.md) describes for its source control. Read any file the decisive line names first, then `Packages/manifest.json`, `ProjectSettings/` and editor build scripts. - Name a commit as the likely trigger only if it changes what the decisive line points to. Otherwise list the changed areas without picking one. If no confirmed category decided the side, read the playbook in [references/failure-knowledge.md](failure-knowledge.md) that matches the failing section, and the log signatures to look for. @@ -119,7 +129,18 @@ Then apply these checks: - Name a side in the report only if its row in the knowledge reference says the side may be named. Otherwise don't name or hint at one, even if the user asked whose fault it was. Answer with the cause, and with whether the user has anything to change. - If the cause needs a bigger machine (out of memory, out of disk, or a time limit hit during heavy work), name the issue and the build's machine (`machineType.name`), suggest a machine type with more of the resource that ran out, and link [Choose a machine specification](https://docs.unity.com/en-us/build-automation/optimize-build-speed/choose-machine-specification.md). Don't name a specific paid machine type, because the user chooses what to pay for. -## Step 5: Check the verdict +## Step 5: Find what the user can change + +Do this for every failure, whatever side you decided, because the knowledge reference covers only the failures seen before, and an Unclear side still leaves the user things to check. + +1. Say in plain words what the decisive line means: what the step was doing, what it expected, and what it found instead. +2. List the inputs that step reads and the user controls: the target's settings (run `unity pipeline cloud-build targets get --format json` and save it), the branch, the revision the build asked for (`requestedRevision`) and the repository, the connected source control account, the signing credentials, and the project's files at the built revision. +3. Keep the inputs that could produce the decisive line. For each, give one check the user can make and the change to make if the check fails. Put first an input that changed where the failures began, in the neighbouring builds or the target changes, or one the user kept changing. +4. If the decisive line says something is missing, such as a type, a file, a framework or a package, check that it exists at the built revision before you blame the code, because a file that's ignored, left out of LFS or only on the user's machine fails the same way. If the project's directory is a checkout, check it as [references/source-control.md](source-control.md) describes; otherwise give it as a check. +5. Call each input a likely cause unless the log names it, and leave out any input the evidence rules out, such as a setting that's unchanged since a passing build. +6. If you have neither a cause nor a check, investigate further before you report, because the steps above cover the common cases only. Read the rest of the log section by section, keeping Step 3's limit past `Player export failed`, then the logs of up to three earlier failures, the project's files and the doc pages that cover the failing section. Stop once you have a cause or a check, or after ten such reads, because some failures stay unexplained however much you read. Use only the commands the Commands section allows. Treat what you find as Step 3's evidence, and decide the side again as in Step 4. + +## Step 6: Check the verdict 1. Re-read each line you'll quote, by its line number in the saved log. Confirm it says what you claim, and that it supports the side you decided. If it doesn't, change the side to Unclear. 2. Confirm the failing section you report contains the decisive line. @@ -131,11 +152,14 @@ Then apply these checks: 1. **Verdict**: "Build #`` of `` failed in `
` because ``." Then your confidence in the cause, and the side if the knowledge reference lets you name it. Confidence is high when the log shows the cause and the neighbouring builds or the target changes agree with it, medium when only the log shows the cause, and low otherwise. A category doesn't add confidence, because it matched the same log. 2. **Evidence**: the category display names, if any; one to five quoted log lines with their line numbers; what the neighbouring builds, the target changes and the commits between them show; any read that failed; and the doc pages you read. -3. **Fix**: numbered steps, with a link to the doc page that covers them. +3. **Fix**: numbered steps, with a link to the doc page that covers them: the fix for the cause if you found one, then the possible fixes Step 3 found at earlier recoveries, then Step 5's checks, likely causes first. 4. **Next step**: - - Before you suggest a rebuild, run `unity pipeline cloud-build targets get --format json`. If `enabled` is `false`, say the target must be enabled first, because a disabled target doesn't build. - - If the side you decided in Step 4 is Your project or Unity Editor version, whether or not you named it: "After the fix, rebuild with `unity pipeline cloud-build builds start --build-target --cloud-org --cloud-project `." The user runs it. If the fix is in the project's files, add that their agent can apply it if they ask. If it's a target setting, say to change it in the Unity Cloud Dashboard, because this skill doesn't change targets. + - Before you suggest a rebuild, read `enabled` in the `targets get` output you saved in Step 5. If it's `false`, say the target must be enabled first, because a disabled target doesn't build. + - If Step 3 found repeated failures that the target started automatically, and no later build of the target succeeded, say how many and since when, and suggest turning that trigger off in the Unity Cloud Dashboard until the fix is in: the build schedule (`settings.buildSchedule`), building on new commits (`settings.autoBuild`) or building on a new Unity version (`settings.autoBuildLatest`). For a run of `api` builds, suggest pausing the tool that starts them. If a later build succeeded, say how many failed and when they recovered, and suggest no pause, because the trigger works again. + - If Step 3 found a setting changed after this build that no build has used yet, suggest a rebuild to test it, with the command below. + - If the side you decided in Step 4 is Your project or Unity Editor version, whether or not you named it: "After the fix, rebuild with `unity pipeline cloud-build builds start --build-target --cloud-org --cloud-project `." The user runs it. If the fix is in the project's files, add that their agent can apply it if they ask. If it's a target setting, say to change it in the Unity Cloud Dashboard, because this workflow doesn't change targets. - If the side is Third party: nothing in the project needs to change. Suggest retrying later and checking that service's status page, then rebuilding with the same command. + - If the side is Build Automation or Unclear and the Fix has checks, say to make them before the steps below, because Unclear decides who has to act, not whether the user has something to try. - If the side is Build Automation or Unclear and later builds of the target succeeded, say the failure hasn't repeated, and give the steps below for if it comes back. - If the side is Build Automation or Unclear otherwise, suggest one rebuild first, because many failures don't repeat, unless the same failure already repeated across builds. Then list: check the [Unity status page](https://status.unity.com/) for an open incident; read the [Build Automation FAQ](https://support.unity.com/hc/en-us/sections/13795481434004-Unity-Build-Automation) and the troubleshooting page you read first; ask on [Unity Discussions](https://discussions.unity.com/); and if none of those helps, [open a support ticket](https://support.unity.com/hc/en-us/requests/new?ticket_form_id=186883). Give a hand-off block to paste into the ticket: organization ID and project ID (`orgFk` and `projectGuid`), target, build number, `buildGUID`, the finish time, the category labels and the quoted lines, leaving out any value that's missing or all zeros. -5. **Side effects**: "I only read this build's record, log and build history, and the target's change history. I changed nothing." Add the project's source control history if you read it. Name every temporary file you saved, so the user can delete them. +5. **Side effects**: "I only read this build's record, log and build history, and the target's settings and change history. I changed nothing." Add the project's source control history, other builds' logs and the build's artifacts if you read them. Name every temporary file you saved, so the user can delete them. diff --git a/skills/manage-cloud-build/references/create-build-target.md b/skills/manage-cloud-build/references/create-build-target.md index 0fcf459..2bec4f4 100644 --- a/skills/manage-cloud-build/references/create-build-target.md +++ b/skills/manage-cloud-build/references/create-build-target.md @@ -22,10 +22,10 @@ Set up a Unity Build Automation build target for the local project and start its - **CLI check:** `unity pipeline cloud-build targets create --help`, because older CLI versions can't create targets. - Keep stderr out of any JSON you parse, because the CLI writes notices there. -- **Reads**, which you may run at any point: `unity auth status`, `unity cloud org current`, `unity cloud project current`, `unity logs --console --level error`, `--help` on any command, `unity vcs status` and `unity vcs doctor` (Git only), `unity vcs setup --dry-run`, and `unity pipeline cloud-build project get`, `connections`, `targets`, `targets get`, `tooling platforms`, `tooling unity`, `tooling os`, `tooling machine-types`, `org free-tier` and `scm check-url`. +- **Reads**, which you may run at any point: `unity auth status`, `unity cloud org current`, `unity cloud project current`, `unity command console status`, `unity logs --console --level error`, `--help` on any command, `unity vcs status` and `unity vcs doctor` (Git only), `unity vcs setup --dry-run`, and `unity pipeline cloud-build project get`, `connections`, `targets`, `targets get`, `tooling platforms`, `tooling unity`, `tooling os`, `tooling machine-types`, `org free-tier` and `scm check-url`. - **Writes**, which you may run only after the user approves the summary in Step 6, because each one adds something to their organization or repository: `unity vcs setup`, `connections create`, `credentials upload`, `targets create` and `builds start`. The one exception is `unity projects add`, which Step 2 runs only when the user agrees to it. Run each one once. If it fails, report its error instead of running it again, because a second run can add a duplicate. - Never run `targets update`, `builds cancel`, `unity vcs doctor --fix` or any other command that changes something that already exists, because this workflow only adds. -- Read the checkout only with read-only commands, such as those in Step 2, `git ls-files` and those in [references/source-control.md](source-control.md), because the user decides what changes in it. Never fetch, because that changes the checkout too. +- Read the checkout only with read-only commands, such as those in Step 2, `git ls-files` and the reads in [references/source-control.md](source-control.md), because the user decides what changes in it. Never fetch, because that changes the checkout too. - Never ask the user to type a password, token or key into the conversation, and never put one on a command line, because both end up in logs. Step 7 reads each one from a file the user creates. ## Glossary @@ -178,7 +178,7 @@ Then: upload the keystore, create the target, start build 1. - iOS: `unity pipeline cloud-build credentials ios upload --label