From 2a1805e57ab33a4f22d9d4b4d4ed7a220e6e2548 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:33:58 +0000 Subject: [PATCH] chore: publish 3 skills (manage-cloud-build, new-unity-project, unity-cli) --- 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/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 +- 20 files changed, 406 insertions(+), 196 deletions(-) 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