Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions skills/manage-cloud-build/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<VERSION>` 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/<VERSION>/`, 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/<VERSION>/Documentation/Manual/`.

Expand All @@ -65,15 +65,15 @@ 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, `<scope>` stands for `--cloud-org <org> --cloud-project <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

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.
Expand Down
54 changes: 39 additions & 15 deletions skills/manage-cloud-build/references/analyze-build-failure.md

Large diffs are not rendered by default.

6 changes: 3 additions & 3 deletions skills/manage-cloud-build/references/create-build-target.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <platform> 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
Expand Down Expand Up @@ -178,7 +178,7 @@ Then: upload the keystore, create the target, start build 1.
- iOS: `unity pipeline cloud-build credentials ios upload --label <label> --certificate '<p12>' --provisioning-profile '<profile>' --certificate-password-from-stdin <scope> --format json < '<certificate-password-file>'`. Then compare `data.provisioningProfile.bundleId` with the bundle ID. If they differ, and the profile's ID isn't a `*` wildcard that covers it, stop, because the signed app wouldn't install.
- Keep `data.credentialid`, and tell the user to delete the password files.
5. Run `unity pipeline cloud-build targets create <options> <scope> --format json`, and keep `data.buildtargetid`. If it fails, report its `errors[].message`, which carries the service's reason, and stop.
6. Run `unity pipeline cloud-build targets get <buildtargetid> <scope> --format json`, and compare each setting in the summary with the one stored. Tell the user about any that differ. `targets get` shows neither the development-build setting nor the signing credential, so those can't be compared, and settings the service adds on its own, such as `xcodeVersion`, aren't differences.
6. Run `unity pipeline cloud-build targets get <buildtargetid> <scope> --format json`, and compare each setting in the summary with the one stored. Tell the user about any that differ. `targets get` doesn't show the signing credential, so it can't be compared, and settings the service adds on its own, such as `xcodeVersion`, aren't differences.

## Step 8: Start the first build

Expand Down
4 changes: 2 additions & 2 deletions skills/manage-cloud-build/references/example-report.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,13 @@ Build 56 succeeded on Unity `2022_3_62f1`, and build 57, at the same revision, i
```text
Build #57 of android-release failed in "Building Unity player (android)" because Assets/Scripts/Rendering/OutlineFeature.cs doesn't compile against Unity 6000.3. Confidence: high.

Evidence: Missing Reference Error, Script Compiler Error. Line 8389: OutlineFeature.cs uses RenderTargetHandle, which no longer compiles from Unity 2023.1. Build 56 succeeded on 2022.3 at the same revision, so the upgrade started the failure. The steps read returned not found. Docs read: Troubleshoot common issues.
Evidence: Missing Reference Error, Script Compiler Error. Line 8389: "OutlineFeature.cs(22,17): error CS0619: 'RenderTargetHandle' is obsolete: 'Deprecated in favor of RTHandle. #from(2022.1) #breakingFrom(2023.1)'". Build 56 succeeded on 2022.3 at the same revision, and the target's change history shows the Unity version set to 6000.3 just before build 57, so the upgrade started the failure. The steps read returned not found. Docs read: Troubleshoot common issues.

Fix:
1. Move OutlineFeature.cs to the current render pass API (RTHandle), or build with Unity 2022.3 until it's ported.
2. Confirm locally in batch mode before you rebuild (Troubleshoot common issues, "Run locally in batch mode").

Next step: after the fix, rebuild with `unity pipeline cloud-build builds start --build-target android-release --cloud-org my-studio --cloud-project my-game`. Your agent can apply the fix if you ask.

Side effects: I only read this build's record, log and history. I saved the log to /tmp/build-57.log and the build list to /tmp/builds-android-release.json. I changed nothing.
Side effects: I only read this build's record, log and build history, and the target's settings and change history. I saved the log to /tmp/build-57.log and the build list to /tmp/builds-android-release.json. I changed nothing.
```
4 changes: 2 additions & 2 deletions skills/manage-cloud-build/references/failure-knowledge.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,11 +89,11 @@ Lines between the pre-build or post-build script's start and its exit code come

### Xcode build

`** ARCHIVE FAILED **` is a summary line. Find the first `error:` line above it, then apply the signing playbook or the `invalid_ios_dependency` row. `Platform Not Installed` is Build Automation.
`** ARCHIVE FAILED **` is a summary line. Find the first `error:` line above it, or in the Xcode log artifact (`gym_log`) if the build log has none, then apply the signing playbook or the `invalid_ios_dependency` row. `Platform Not Installed` is Build Automation.

### Unit tests

Failed tests are Your project. Read `reference/unit-tests.md`.
Failed tests are Your project. Name them from `testResults` in the `builds get` output, because the log often doesn't. Read `reference/unit-tests.md`.

### Publishing: `+ Publishing`

Expand Down
63 changes: 18 additions & 45 deletions skills/manage-cloud-build/references/source-control.md
Original file line number Diff line number Diff line change
@@ -1,38 +1,32 @@
# Source control commands
# Source control reads

Read-only commands that compare the last successful revision (`<good>`) with the first failed one (`<bad>`) in the project's local checkout. `<path>` is a file's path as the command that lists the changed files prints it.
Read-only reads that compare the last successful revision (`<good>`) with the first failed one (`<bad>`) in the project's local checkout, and that check whether a file exists at the built revision (`<rev>`, the build's `lastBuiltRevision`). Use the project's own source control. For Unity Version Control, use the commands under [Unity Version Control](#unity-version-control).

- Run them from the project's directory.
- Never run a command that changes the checkout, such as `fetch`, `pull`, `checkout`, `update`, `switch`, `sync` or `submit`, because the user decides what changes in their checkout.
- If the checkout lacks either revision, ask the user to bring it up to date, and skip the local read.
- Never run a command that changes the checkout, such as a fetch, a pull, an update or a branch switch, because the user decides what changes in their checkout.
- If the checkout lacks a revision a read needs, ask the user to bring it up to date, and skip the local read.
- Cap each read's output, because a wide range can print thousands of lines.
- Some reads stop to ask for a password, a sign-in or a certificate decision. Run them without prompts where the tool allows it. If one fails or waits for that reason, stop it and ask the user to run it once in their own terminal.
- If the checkout isn't on the target's branch (`scmBranch`), give the checks that depend on the branch to the user, because the checkout holds another branch's files.

## Which source control
## What to read

- **Git:** `lastBuiltRevision` is a 40-character hexadecimal hash. This covers GitHub, GitLab and Bitbucket connections too.
- **Unity Version Control, Perforce or SVN:** `lastBuiltRevision` is a plain number: a changeset, a changelist or a revision.
- **Telling those three apart:** a `.plastic` folder means Unity Version Control, and a `.svn` folder means SVN. For Perforce, `p4 info` shows a client root that contains the project's directory.

## Git

- `--name-status` prints paths from the repository's root, so `:/` makes `git diff` read `<path>` from there too.
- `core.quotePath=false` prints a name with non-ASCII characters as it is, not as quoted octal escapes.
- A renamed file prints as `R`, a similarity score, its old path and its new path. To see what changed in it, pass both: `":/<old path>" ":/<new path>"`.

```sh
git rev-parse --is-inside-work-tree
git cat-file -e "<good>^{commit}" && git cat-file -e "<bad>^{commit}"
git log --oneline <good>..<bad> | head -n 50
git -c core.quotePath=false diff --name-status <good> <bad> | head -n 40
git diff <good> <bad> -- ":/<path>" | head -n 200
```
1. The revisions after `<good>` up to `<bad>`, with their messages, up to 50.
2. The files they changed, up to 40. `<path>` below is a file's path as this list prints it. It can be relative to the repository's root, which can sit above the project's directory, so read each file from there. For a renamed file, compare its old path with its new one.
3. The diff of each suspect file between `<good>` and `<bad>`, up to 200 lines.
4. Whether a file exists at `<rev>`, and whether it's ignored or was never added, because either keeps it out of the build. `<file>` is a path relative to the project's directory, such as `Assets/Scripts/Player.cs`. To find the file that defines a missing type, search the project's directory first, for example `grep -rlE --include='*.cs' '(class|struct|interface|enum) <Name>\b' Assets Packages | head -n 20`, then check each file it finds.
- Check the checkout has `<rev>` first, because a missing revision fails the same way as a missing file.
- A file whose content is only a pointer to large file storage needs its content on that storage's server, or the build gets the pointer.

## Unity Version Control

A `.plastic` folder in the project's directory or a folder above it means Unity Version Control, and `lastBuiltRevision` is a changeset number.

- Never pass a path to `cm diff`, because with one it opens the Diff window instead of printing. Compare a file's two versions with `cm cat` instead.
- Cap every `cm` command's output with `head -c`, never `head -n`. When the sign-in has expired, `cm` asks "Select your system" and, with no one to answer, repeats it forever on one line, which `head -n` lets through.
- `cm` keeps running after `head` stops reading, so run each `cm` command in the background, where you can stop it. If one prints that question, or runs for more than a minute, stop it. Then ask the user to sign in by running `cm repo list <server>` in their own terminal, with the server the question names. Signing in is the user's action.
- `--repositorypaths` makes `cm diff` print repository paths, such as `/Assets/A.cs`. `cm cat` reads them only with the `serverpath:` prefix.
- For a file `cm diff` marks `A` (added) or `D` (deleted), the `cm cat` of the side without it fails with "The specified revision was not found". That's expected: the file is new or gone.
- For a file `cm diff` marks `A` (added) or `D` (deleted), the `cm cat` of the side without it fails with "The specified revision was not found". That's expected: the file is new or gone. For the same reason, the last command below fails if `<file>` isn't in the project at `<rev>`.

```sh
cm wi . | head -c 1000
Expand All @@ -41,26 +35,5 @@ cm diff cs:<good> cs:<bad> --repositorypaths | head -c 4000
cm cat "serverpath:<path>#cs:<good>" --file="<temp-dir>/good" | head -c 1000
cm cat "serverpath:<path>#cs:<bad>" --file="<temp-dir>/bad" | head -c 1000
diff "<temp-dir>/good" "<temp-dir>/bad" | head -n 200
```

## Perforce

`<good+1>` is the number after `<good>`, so the list leaves out the last successful changelist. `...` is every file under the current directory. `diff2 -q` prints depot paths such as `//depot/Project/Assets/A.cs#2`; `<path>` is that path without the `#` and the number after it.

```sh
p4 info
p4 changes -m 50 -L ...@<good+1>,@<bad>
p4 diff2 -q ...@<good> ...@<bad> | head -n 40
p4 diff2 -du "<path>@<good>" "<path>@<bad>" | head -n 200
```

## SVN

`--non-interactive` makes a read that needs a password or a certificate decision fail instead of waiting for an answer. If one fails that way, ask the user to run it once in their own terminal.

```sh
svn info
svn log --non-interactive -r <bad>:<good+1> --limit 50
svn diff --non-interactive --summarize -r <good>:<bad> | head -n 40
svn diff --non-interactive -r <good>:<bad> "<path>" | head -n 200
cm cat "<file>#cs:<rev>" --file="<temp-dir>/exists" | head -c 1000
```
2 changes: 1 addition & 1 deletion skills/new-unity-project/SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ of these as powerful capabilities. They are intentional, and limited by the safe
writes and the cloud-link narration included — prints in one block before the create launches,
and any line reverses on a word. Consent in the strict sense comes from guided mode's per-step
asks; paved mode's bar is that nothing runs unannounced and nothing is irreversible.
- **Human gates are never consumed.** Sign-in, license activation (including accepting the Unity Personal EULA) and publishing each run only after the user says yes to a question the agent asks and waits on.
- **Human gates are never consumed.** Sign-in, license activation (including accepting the Unity Personal EULA and the Unity Editor Software Terms, which `unity terms accept --yes` records only after that yes) and publishing each run only after the user says yes to a question the agent asks and waits on.
- **Only the user's own Editor and account.** Everything runs on this machine as this user.
- **No remote code.** All executed C# comes from this skill's text and its delegated skills.
- **Named commands first.** Where a dedicated `unity` command covers a step, the skill uses it.
Loading
Loading