This runbook qualifies every V1–V9 closure instruction that depends on Unreal Engine. It separates repository/project availability from the capabilities of the shell that happens to be running the audit.
Designated execution profile#
The profile name is ue55-linux:
- runner class: GitHub Actions labels
[self-hosted, Linux, Unreal]; - engine: Unreal Engine 5.5.x;
- engine root:
/root/workspace/UnrealEngine-5.5; - commandlet executable:
/root/workspace/UnrealEngine-5.5/Engine/Binaries/Linux/UnrealEditor-Cmd; - run-as user:
ueagent; - automation target:
LinuxEditor; - Linux cook/package target:
LinuxviaRunUAT BuildCookRun; - durable output: the exact log, Automation report or cooked archive, and an
oshun.unreal-evidence.v1record produced byscripts/audit/write-unreal-evidence-record.mjs.
An executed record is invalid unless it identifies the full source commit,
engine version and executable digest, project path and digest, commandlet, exact
argv, run-as user, target platform, timestamps, exit code, and output artifact
byte counts/digests. The machine contract is
scripts/audit/unreal-evidence.schema.json.
Project binding#
| Closure surface | Project that must be recorded | Normal commandlet | Target |
|---|---|---|---|
| V2 | V2/ue/V2.uproject |
UnrealEditor-Cmd for automation; RunUAT BuildCookRun for a cook |
LinuxEditor or Linux |
| V3 | V3/ue/V3.uproject |
UnrealEditor-Cmd / project BuildGraph |
LinuxEditor or the explicitly selected cook target |
| V4 | V4/ue/V4.uproject |
UnrealEditor-Cmd |
LinuxEditor |
| V5 | V5/ue/V5.uproject |
UnrealEditor-Cmd / RunUAT BuildCookRun |
LinuxEditor or Linux |
| V6 | V6/ue/V6.uproject |
UnrealEditor-Cmd / BuildGraph |
LinuxEditor or Linux |
| V7 | V7/ue/Mawu.uproject |
UnrealEditor-Cmd / RunUAT BuildCookRun |
LinuxEditor or Linux |
V8 has no standalone .uproject in this repository. A V8 task that says
“place/cook/play in UE” must first name and approve the owning runtime project;
until then it is blocked on a project binding, not satisfied by choosing an
unrelated .uproject.
Local capable-host path#
On a host that actually satisfies ue55-linux, first retain:
git rev-parse HEAD
test -x /root/workspace/UnrealEngine-5.5/Engine/Binaries/Linux/UnrealEditor-Cmd
id ueagent
Run editor automation as ueagent, for example V4:
runuser -u ueagent -- V4/.ci/run-ue-automation-smoke.sh
Do not copy this command to a different project without changing the recorded
project, suite, target, and expected output. A cook must record
RunUAT BuildCookRun, its exact platform/configuration/map/archive arguments,
and the cooked archive digest; an editor automation run is not cook evidence.
macOS or other host without Unreal#
Do not install, emulate, or silently skip UE merely to make the local step green. Send the commit to the designated remote runner. For V4, push a branch or tag that resolves to the intended commit and use the dispatchable remote job:
gh workflow run v4-pr-gate.yml --ref <branch-or-tag>
gh run list --workflow v4-pr-gate.yml --commit <full-commit-sha>
gh run view <run-id> --json headSha
gh run watch <run-id> --exit-status
gh run download <run-id> --name v4-ue55-linux-evidence
The returned headSha must equal <full-commit-sha> before its evidence can be
used. A branch name without that equality check is mutable and therefore not an
evidence identity.
The UE5.5 Automation Smoke job is required to run on
[self-hosted, Linux, Unreal] and upload the log, Automation report, and
evidence JSON even when the commandlet is red. The current V2 planning job and
V3 Windows worker are not substitutes for this Linux executed-evidence profile.
The existing V6 Linux BuildGraph job has the right runner class but does not yet
emit oshun.unreal-evidence.v1. V2, V3, V5, V6, or V7 closure therefore needs a
project-owned dispatch/PR job on the same runner profile, upgraded to emit this
record, before it can claim qualifying remote execution.
Missing-host semantics#
If either the commandlet path or ueagent is absent, record
not-run-on-this-host with the checked path, host/OS, source commit, timestamp,
and missing prerequisite. This status means only that the current host cannot
execute the job. It is not evidence that Unreal is unavailable to the project,
that the project cannot compile, or that a remote job passed or failed.
Never create an oshun.unreal-evidence.v1 record for a skipped run. That schema
is reserved for an actually executed command with retained outputs.
Evidence acceptance#
An Unreal closure claim requires all of the following:
- An executed
oshun.unreal-evidence.v1record that passes the writer's validator and matchesscripts/audit/unreal-evidence.schema.json. - Exact commandlet output and Automation/cook output retained by digest.
- A green command exit for a pass claim; a red record remains useful evidence but cannot close the product gate.
- For playable/cooked claims, the packaged binary/archive plus runtime media
and the relevant accessibility/performance results. A
LinuxEditorAutomation pass alone does not prove cook, placement, playback, or quality. - The record and artifacts committed or linked to an immutable CI artifact with retention sufficient for the release decision.