t1k:jenkins-unity
| Field | Value |
|---|---|
| Module | t1k-devops |
| Version | 4.1.3 |
| Effort | medium |
| Tools | — |
Keywords: android build, app store, auto-detect, build job, bundle id, cheat flags, create-from-spec, debug flags, define parity, define symbols, develop release creative, distribute, ios build, iphone, jenkins, job spec, new game, onboarding, project detection, signing team id, symbol parity, testflight, unity, unityandroid, unityios, unitywebgl, webgl
How to invoke
Section titled “How to invoke”/t1k:jenkins-unity<git-ssh-url> [--platform android|ios|webgl] [--project <ProjectName>] [--with-creative]Jenkins Unity Onboarding: the standard build jobs per new game (Android, iOS or WebGL)
Section titled “Jenkins Unity Onboarding: the standard build jobs per new game (Android, iOS or WebGL)”Given a new Unity game repo, create its standard Jenkins jobs on
https://jenkins.the1studio.org, each rendered from a T1K job spec. There is no template job
to clone or inherit from: the spec holds every parameter, default, SCM block, property and trigger.
| platform | folder | spec | jobs created | scriptPath (in the spec) |
|---|---|---|---|---|
| Android | UnityAndroid | unity-android | -Develop, -Release, -Creative | Jenkinsfile/Android |
| iOS | UnityIOS | unity-ios | -Develop, -Release (-Creative only with --with-creative) | Jenkinsfile/IOS |
| WebGL | UnityWebGL | unity-webgl | -Develop, -Release (-Creative only with --with-creative) | Jenkinsfile/WebGL |
This skill is a caller of t1k:jenkins-job (protected: true; read it, never edit it). The delta it owns: per-platform --set lists, role define-symbol appends, the iOS signing question, WebGL packaging, the independent spec verifier scripts/verify-params-independent.cjs, and Unity auto-detection scripts/detect-unity-project.cjs. Full description: references/architecture.md.
Where things live. Parameter tables: the spec files, never this skill (references/spec-reference.md).
Per-job contract and generation commands: references/param-matrix.md (read the section for YOUR
platform; platforms share the engine, the gate and the role appends, and no parameter table).
iOS signing and bundle id: references/ios-signing.md. Detection: references/project-detection.md.
Three rules hold on every platform. Passwords (keystore x2, PARAM_FACEBOOK_APP_SECRET) are
never on argv, printed or committed. The keystore passwords are set from keystore_pw.md by
jenkins-job.cjs set-secret right after the job is created (incident-history.md #3, #33); the facebook secret is still typed in Jenkins. A
keystore created by this studio has a RANDOM password, not its name. In-project delivery is the studio default: the keystore is committed in the game
repo, and the two Jenkins Password parameters are set by set-secret from the password record (incident-history.md #33). PARAM_DISCORD_THREAD_ID is set on every job to the
project’s Discord build thread, created if missing (references/discord-thread.md, incident-history.md #28).
PARAM_UNITY_TOOL_NAME comes from the studio config; pass --unity-tool <name> only to override it, never to restate it: references/tool-name.md.
Two credential sets, different env-var names for the same account: jenkins-job.cjs reads
JENKINS_URL/JENKINS_USER/JENKINS_TOKEN; the Jenkins MCP uses JENKINS_USERNAME/JENKINS_API_TOKEN
(a mismatch gives a 401 that looks like a bad token). Credentials come from env only, never argv,
never echoed. The Jenkins MCP has no job-creation tool: creation always goes through
create-from-spec; MCP verification is optional, never a gate. Detail: references/setup-credentials.md.
Bind three absolute paths and use the variables everywhere (a relative scripts/...cjs resolves
against the user’s project, because Step 0.5 sets cwd there, and fails MODULE_NOT_FOUND):
S=~/.claude/skills/t1k-jenkins-job/scripts/jenkins-job.cjs,
V=~/.claude/skills/t1k-jenkins-unity/scripts/verify-params-independent.cjs,
D=~/.claude/skills/t1k-jenkins-unity/scripts/detect-unity-project.cjs.
The Android keystore seam adds W=~/.claude/skills/t1k-jenkins-unity/scripts/keystore-wire.cjs
(references/step1-platform-rounds.md); it only maps JSON and touches nothing. --delivery in-project is its
default (incident-history.md #33); vault and repo are deprecated for one release, for existing jobs only (vault delivery needs ONE typed secret; the plain pair is legacy). Keystore passwords are never supplied, read or stored by this skill.
Step 0: resolve the PLATFORM first, before anything else
Section titled “Step 0: resolve the PLATFORM first, before anything else”Every later step is parameterised by it. --platform android|ios|webgl settles it. Absent, ask
(AskUserQuestion); never infer it from the repo, from a Jenkinsfile/IOS in the checkout, or
from the conversation. A wrong platform produces jobs in the wrong folder that cannot be deleted
(references/incident-history.md #4). Bind $FOLDER and $SPEC from the table above.
Per-platform jobs, define-symbol keys and round-2 questions are in one table: references/platform-table.md.
A run creates jobs on exactly one platform. A title needing several gets one run each, end to end; questions, matrix and both gates are per platform, and interleaving them is how a value crosses over.
Step 0.5: Unity project auto-detection (accelerator, never a requirement)
Section titled “Step 0.5: Unity project auto-detection (accelerator, never a requirement)”Run bun $D detect (cwd = where the user invokes from, or --cwd/--project-dir). Algorithm,
edge cases and the two-mode define-symbols contract: references/project-detection.md.
status | Action |
|---|---|
not-a-unity-project | Fall back to Step 1 entirely, asking for everything. The default outside a Unity checkout, never a failure. |
multiple-candidates | AskUserQuestion which of the candidates, never the first; re-run detect --project-dir <chosen>. |
ok | Show EVERY detected field and fold them into Step 1 as proposed, editable defaults, never silent auto-fill (jobs are not cheaply reversible). |
Read the define-symbol field for the resolved platform. A null list is never resolved by
substituting defineSymbolsAndroid: the lists genuinely differ (one project’s Android list carries
THEONE_CHEAT and CREATIVE; its iPhone list neither), so substituting ships a cheat menu into a
store build. A null means the project was probably never switched to that build target: say so and ask.
Surface every warnings entry verbatim (references/incident-history.md #12/#15/#18/#19).
| When | Action |
|---|---|
status: ok, platform android or ios, at least one list non-null | Run bun $D symbol-parity --android "<defineSymbolsAndroid>" --ios "<defineSymbolsIOS>" (quote both; a null list: omit its flag, never pass the other platform’s list in its place; "" is an empty list, not a null). Keep the JSON for Step 1 and Reporting. |
platform webgl | Not run: WebGL lists legitimately diverge. |
THEONE_CHEAT / CREATIVE normally differ between the lists, so level: expected is normal, one
line, no question. Only candidate tokens (level: review) are a decision. Report-only: exit 0 for
every outcome, never blocks, never fills iOS from Android (#32, references/project-detection.md
§ Android vs iOS symbol parity).
Step 1: input gathering (one batched AskUserQuestion, 3 questions, plus a platform round)
Section titled “Step 1: input gathering (one batched AskUserQuestion, 3 questions, plus a platform round)”- Git repo URL, SSH form (
git@github.com:The1Studio/<Project>.git). Skip if given, or pre-fill from Step 0.5’srepoUrland confirm. <ProjectName>: propose from the repo name (strip.gitand a leadingUnity) or the detectedprojectName. It becomes the job-name prefix andPARAM_BUILD_FILE_NAME: a wrong value is wrong in two places.- Readback of the detected values to confirm: the project’s editor version (
unityVersion, shown NEXT TO the studio tool name the config resolves — say it when the two differ; the job takes the studio value,incident-history.md#12), the branch per job (*/develop,*/release*,*/creativeproposed; on iOS always asked), and the define-symbol source (detected list or spec default). No thread id question exists: the skill resolves, and if needed creates, the Discord build thread itself (references/discord-thread.md,incident-history.md#28). iOS andsymbol-paritysignificant: true: list thecandidatetokens with direction (“on Android, missing on iOS” / the reverse) and ask ONE decision with three options: (1) keep the iOS list as detected (deliberate; record it); (2) add the chosen symbols to the iOS jobs’ list (warn: the job then diverges fromProjectSettings.assetand a local iOS build still lacks them, so fix ProjectSettings too); (3) stop and fix ProjectSettings first, then re-run. Before offering (2) readreferences/sdk-symbol-sync.md3b, 5 and 6: a flag at 0 or an absent SDK means keep.levelnoneorexpected: one readback line, no question. Platformandroid: no question, Reporting line only.
The GitHubPushTrigger is decided per job by house policy, reported back, not asked:
-Develop/-Creative strip it (--strip-triggers; t1k-jenkins-build decides Develop builds),
-Release keeps it (incident-history.md #26). State the per-job result in the readback and offer the
override; only an explicit user sentence flips a job off the policy.
A second AskUserQuestion call carries the platform round, never combined with the first:
Android keystore name/alias (no passwords), iOS store/bundle id/branches, WebGL orientation and
packaging. The one exception is a dependent follow-up call inside the Android round, when the project has no
keystore yet and the human wants one created (t1k:unity:mobile:keystore-create, mapped by scripts/keystore-wire.cjs;
only when detection returned status: ok). In that round in-project delivery is the first and recommended
choice: the keystore is committed in the game repo, the studio default for every game (incident-history.md #33). Full text: references/step1-platform-rounds.md, references/ios-signing.md.
Step 2: pre-flight probes (all read-only; report every result in one table before generating)
Section titled “Step 2: pre-flight probes (all read-only; report every result in one table before generating)”Seven read-only probes, reported in one table before generating. Hard stops: credentials (1), spec (4), verifier self-test (5) and Unity image (7). Probe 2 stops on a name collision, probe 3 only warns, and probe 6 never stops. Commands and per-probe handling: references/preflight-probes.md.
This phase must NOT create/update/POST anything, and must NOT create a scratch job “to check
permissions”: Job/Delete is unproven for this account (incident-history.md #4); permission is proven by
creating the first job the user actually wants.
Step 3: generate the job configs, offline
Section titled “Step 3: generate the job configs, offline”gen-from-spec makes no network call. Commands and per-job --set lists:
references/param-matrix.md, section for the resolved platform. Define symbols by mode
(DETECTED vs FALLBACK, same file): detected mode replaces the spec default with the project’s own
list; fallback runs the spec’s own default through the same steps. Three role rules, both modes:
- Develop: the list, unfiltered, then
bun $D develop-append --list "<list>"(appendsTHEONE_CHEATandCREATIVE, idempotent per symbol; Develop is an internal QA build). PrintappendedSymbols. - Release:
bun $D strip-debug-flags --list "<list>", thennode $D release-append --list "<stripped>"(appendsPRODUCTION). Never conditional, never asked about. Printstrippedeven when empty (“stripped: none”) andappendedSymbols. - Creative (Android always; iOS/WebGL only with
--with-creative): the same stripped output, thenbun $D creative-append --list "<stripped>"(appendsCREATIVEandTHEONE_HIDE_FPS, idempotent per symbol). PrintappendedSymbols: a partial append reads like a full one otherwise.
BLOCKING GATE: prove every generated config conforms to the spec, before Step 4 makes any live call
Section titled “BLOCKING GATE: prove every generated config conforms to the spec, before Step 4 makes any live call”Governed by skills/t1k-cook/references/workflow-gates.md. Override: none.
Pass conditions, all four, evidence not assertion (commands and per-platform lists:
references/hard-gate-conditions.md): (1) $V --config <xml> --spec $SPEC --expect ... is green for
every generated XML (names, order, kinds, every non---set default, empty thread id, empty
secrets, scriptPath); (2) $V --self-test --spec $SPEC is green, so the check provably can fail;
(3) the gen-from-spec log of each job shows only intended --sets (Release has no line for
spec-default flags; iOS Release MUST contain SHOULD_BUILD_AND_DISTRIBUTE); (4) role isolation
holds across the run’s jobs.
On failure: stop, create nothing, report the failing condition with its row via
AskUserQuestion; never patch around it. A renderer or spec defect is a theonekit-core fix in
t1k-jenkins-job (protected: true) and this work waits.
Step 4: preview-first create, then the rest
Section titled “Step 4: preview-first create, then the rest”Per rules/preview-first-batch.md. Entry condition: the gate above passed.
- Create exactly one job:
node $S create-from-spec $FOLDER <ProjectName>-Develop --spec $SPEC <the same flags as its gen-from-spec call, minus --out>(add--dry-runfirst to preview).-Developis the smoke target because the user actually wants it, never a scratch job. A 200 fromcreateItem(empty body) does not prove the config landed: always verify (what that response does and does not prove:references/step4-create.md). - Verify it twice, with two different parsers, and NOT the same assertions (commands:
references/param-matrix.md§ “Step 4 smoke-verification commands”; why:references/step4-verification.md). Branch is checked by$Valone;--expect-triggersgoes to the engine per job (nofor Develop/Creative,yesfor Release). - Print both tables and the job URL, then
AskUserQuestion: proceed with the remaining job(s), re-check something, correct viaupdate, or stop. A clean smoke is not auto-permission.
Then create the remaining jobs and run both verifiers against every created job in one final
table (per-job assertions: param-matrix.md § “Verification assertions”). Define-symbol checks are
string equality, never substring. Optional, never a gate: trigger a build via the Jenkins MCP
(triggerBuild/getBuild/getBuildLog) if registered this session.
Reporting
Section titled “Reporting”Once the store credential exists (references/store-auto-version.md), offer PARAM_AUTO_VERSION=true
on Android -Release jobs (version then comes from the store; default off, state which). State
explicitly: the platform and folder; every job name + URL; every parameter left at the spec default
that is arguably per-project (PARAM_DISCORD_WEBHOOK_URL, PARAM_BUILD_VERSION); the value
PARAM_UNITY_TOOL_NAME took and where it came from (the studio config, or your --unity-tool);
the Discord build thread per kind (name, id, created or reused, links file updated), or that it was
left empty so notifications go nowhere and how to fix it (references/discord-thread.md); that set-secret stored the two keystore passwords and read them back (a push-triggered Release
build needs them stored first) — on in-project delivery state that the create flow commits the keystore and that set-secret ran; the trigger decision; any branch probe 3 reported missing; the symbol-parity
level, the tokens by direction and the decision taken (Android and iOS runs both; not WebGL).
Silence about a default reads as a decision nobody made.
Per-platform additions (Android keystore and delivery path; for iOS the parity level, the store, team and bundle id; WebGL orientation and optimization value): references/report-per-platform.md.
Failure handling: rollback is update, never delete
Section titled “Failure handling: rollback is update, never delete”- Wrong value or wrong name:
update --dry-runfirst, then for real, then re-verify with both parsers. A wrong job name is reported to a Jenkins admin, never deleted and recreated:references/failure-handling.md. - Never
--seta password parameter, onupdateorgeneither: the value lands on argv. Usejenkins-job.cjs set-secret <folder> <job> --param <NAME> --from-file <keystore_pw.md>(or--stdin); it refuses a non-Password parameter and reads the value back.
Hard rules
Section titled “Hard rules”34 recorded gotchas from real Jenkins runs: read references/incident-history.md before generating.
The gotchas that bite first are listed in references/bite-first.md with their incident numbers in references/incident-history.md: #4 (Job/Delete unproven), #25 (verifier self-test), #28 (Discord build thread on every job), #33 (keystores committed in-project) and #34 (Harbor image per Unity patch).
After onboarding: a new 3rd-party SDK means a Release symbol
Section titled “After onboarding: a new 3rd-party SDK means a Release symbol”Integrating an SDK (AppLovin, AdMob, ByteBrew, Adjust, Firebase Remote Config, Facebook SDK, an
analytics selector) is not finished until its define symbol is on the Release jobs, Android and iOS.
Do this unprompted when you integrate one, and on any “is Release missing anything” request: run the
audit in references/sdk-symbol-sync.md, apply with update + verify, and report the Develop and
Creative gaps without changing them.
Related
Section titled “Related”t1k:jenkins-jobis the engine and owns the specs (protected: true). The full reference index, the preview-first rule and the<HARD-GATE>contract:references/related.md.
Executed by
Section titled “Executed by”Runs in t1k-devops-engineer (or inline). Onboarding is script-driven; platform choice comes from the caller.
| Step | Agent |
|---|---|
Run scripts/detect-unity-project.cjs, render configs offline, run scripts/verify-params-independent.cjs | t1k-devops-engineer |
| Create the Android/iOS/WebGL jobs after the preview is approved | t1k-devops-engineer |