Skip to content

t1k:jenkins-unity

FieldValue
Modulet1k-devops
Version4.1.3
Effortmedium
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

/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.

platformfolderspecjobs createdscriptPath (in the spec)
AndroidUnityAndroidunity-android-Develop, -Release, -CreativeJenkinsfile/Android
iOSUnityIOSunity-ios-Develop, -Release (-Creative only with --with-creative)Jenkinsfile/IOS
WebGLUnityWebGLunity-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.

statusAction
not-a-unity-projectFall back to Step 1 entirely, asking for everything. The default outside a Unity checkout, never a failure.
multiple-candidatesAskUserQuestion which of the candidates, never the first; re-run detect --project-dir <chosen>.
okShow 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).

WhenAction
status: ok, platform android or ios, at least one list non-nullRun 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 webglNot 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)”
  1. Git repo URL, SSH form (git@github.com:The1Studio/<Project>.git). Skip if given, or pre-fill from Step 0.5’s repoUrl and confirm.
  2. <ProjectName>: propose from the repo name (strip .git and a leading Unity) or the detected projectName. It becomes the job-name prefix and PARAM_BUILD_FILE_NAME: a wrong value is wrong in two places.
  3. 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*, */creative proposed; 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 and symbol-parity significant: true: list the candidate tokens 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 from ProjectSettings.asset and a local iOS build still lacks them, so fix ProjectSettings too); (3) stop and fix ProjectSettings first, then re-run. Before offering (2) read references/sdk-symbol-sync.md 3b, 5 and 6: a flag at 0 or an absent SDK means keep. level none or expected: one readback line, no question. Platform android: 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.

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>" (appends THEONE_CHEAT and CREATIVE, idempotent per symbol; Develop is an internal QA build). Print appendedSymbols.
  • Release: bun $D strip-debug-flags --list "<list>", then node $D release-append --list "<stripped>" (appends PRODUCTION). Never conditional, never asked about. Print stripped even when empty (“stripped: none”) and appendedSymbols.
  • Creative (Android always; iOS/WebGL only with --with-creative): the same stripped output, then bun $D creative-append --list "<stripped>" (appends CREATIVE and THEONE_HIDE_FPS, idempotent per symbol). Print appendedSymbols: 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.

  1. 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-run first to preview). -Develop is the smoke target because the user actually wants it, never a scratch job. A 200 from createItem (empty body) does not prove the config landed: always verify (what that response does and does not prove: references/step4-create.md).
  2. 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 $V alone; --expect-triggers goes to the engine per job (no for Develop/Creative, yes for Release).
  3. Print both tables and the job URL, then AskUserQuestion: proceed with the remaining job(s), re-check something, correct via update, 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.

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-run first, 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 --set a password parameter, on update or gen either: the value lands on argv. Use jenkins-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.

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.

  • t1k:jenkins-job is the engine and owns the specs (protected: true). The full reference index, the preview-first rule and the <HARD-GATE> contract: references/related.md.

Runs in t1k-devops-engineer (or inline). Onboarding is script-driven; platform choice comes from the caller.

StepAgent
Run scripts/detect-unity-project.cjs, render configs offline, run scripts/verify-params-independent.cjst1k-devops-engineer
Create the Android/iOS/WebGL jobs after the preview is approvedt1k-devops-engineer