t1k:jenkins-cocos
| Field | Value |
|---|---|
| Module | t1k-devops |
| Version | 4.1.3 |
| Effort | medium |
| Tools | — |
Keywords: build-job, cocos, cocos-creator, cocos-ios, cocosplayablelabs, ios2x, ios3x, jenkins, job-spec, playable, playable-ads, playablelabs, web-mobile
How to invoke
Section titled “How to invoke”/t1k:jenkins-cocos[project path | repo URL | job name]Cocos Jenkins Jobs
Section titled “Cocos Jenkins Jobs”Route first — four job kinds, one flow, plus a separate matrix flow:
| Want | Spec | Folder | Definition |
|---|---|---|---|
| Playable ad (single HTML for PlayableLabs upload) | cocos-playable | CocosPlayableLabs | SCM, Jenkinsfile/Cocos |
| Cocos Creator 2.x iOS build | cocos-ios-2x | CocosIOS | SCM, Jenkinsfile/iOS2x |
| Cocos Creator 2.x Android build | cocos-android-2x | CocosAndroid | SCM, Jenkinsfile/Android2x |
| Cocos Creator 3.x iOS build | cocos-ios-3x | CocosIOS | inline ios(this), no SCM |
A game integrating cocos-platform-sdk for web portals, mini-games, native | — | — | platform-matrix flow, references/platform-sdk-matrix.md |
cocos(this) always runs buildWebMobile + buildSuperHtml whatever PARAM_COCOS_PLATFORM says,
so cocos-playable can never produce a mini-game or native build. Engine ambiguous or Unity → t1k:jenkins-unity.
Jobs are rendered from a JSON spec, never cloned from a live job; there is no template job to
read, diff or inherit from. This skill is a caller, not a fork: every Jenkins round-trip goes
through ~/.claude/skills/t1k-jenkins-job/scripts/jenkins-job.cjs (gen-from-spec,
create-from-spec, spec-info), whose flags are that skill’s contract. The specs are the SSOT for
parameters, defaults and SCM: references/spec-reference.md.
Paths, resolved once: S = ~/.claude/skills/t1k-jenkins-job/scripts/jenkins-job.cjs · V =
~/.claude/skills/t1k-jenkins-cocos/scripts/verify-params-independent.cjs · D =
~/.claude/skills/t1k-jenkins-cocos/scripts/detect-cocos-project.cjs. Credentials resolve
automatically from the registered jenkins MCP registration — run from /tmp, never print or
pass one.
Step 0 — auto-detection
Section titled “Step 0 — auto-detection”bun $D detect finds the Cocos Creator project (assets/ + settings/v2/packages/, case-exact)
and reports what it can genuinely read. An accelerator, never an autorun — show the result and
confirm. It reads projectDir, repoUrl/repoName, branch, dirty, cocosVersion → cocosToolName
(a 2.x project is not recognised: ask for everything) and scenes[] with UUIDs; it proposes
buildFileName (the project folder name without its Cocos prefix). It refuses PARAM_START_SCENE and PARAM_PLAYABLE_VERSION_ID
with a stated reason — a wrong start scene is a silently broken build. not-a-cocos-project → ask
for everything; multiple-candidates → ask which. Limits: references/project-detection.md.
Step 1 — pick the spec and gather inputs
Section titled “Step 1 — pick the spec and gather inputs”Pick the spec from the table above (the Creator version decides 2x vs 3x for iOS), then read its
contract: bun $S spec-info --spec <name> lists requiredParams (with setBy) and whether
--repo / --branch apply. Establish each independently — none is derivable from another:
job name (user; unrelated to the repo), repo URL (the real git remote), PARAM_BUILD_FILE_NAME
(the Cocos project folder name without its Cocos prefix, gotcha ledger g-t1k-jenkins-cocos-06), Cocos tool name, and per kind: signing team id and bundle
id (iOS), version id / asset flags / store links / trigger policy (playable). Full matrix:
references/param-matrix.md.
PARAM_DISCORD_THREAD_IDis always empty (gotcha ledger g-t1k-jenkins-cocos-11). iOS specs require the input to be stated: pass--set PARAM_DISCORD_THREAD_ID=.PARAM_PLAYABLELABS_API_TOKENis never set by this skill. The user types it at build time; never ask for it, read one from anywhere, or put it in argv (incident-history.md#1).
Step 2 — pre-flight probes
Section titled “Step 2 — pre-flight probes”| Probe | Green means |
|---|---|
bun $V --self-test | every spec’s clean synthetic config passes and every deliberate break is caught |
bun $S list <folder> --grep <name> | the job name is free (create-from-spec also refuses to overwrite) |
Job/Create on the folder | held; Job/Delete often is not (gotcha ledger g-t1k-jenkins-cocos-10) |
t1k-service-binding.cjs status --service discord | present → reuse; absent → create first (playable only) |
Step 3 — render offline
Section titled “Step 3 — render offline”gen-from-spec is offline and deterministic. Iterate here — every re-run is free.
bun $S gen-from-spec --spec cocos-playable --out /tmp/generated.xml --repo <ssh-url> \ --set PARAM_BUILD_FILE_NAME=<project-folder-without-Cocos> --set PARAM_COCOS_TOOL_NAME='Cocos 3.8.x' \ --set PARAM_START_SCENE=<uuid from the start scene's .scene.meta> [--project <cocos-root>] [--strip-triggers]bun $S gen-from-spec --spec cocos-ios-2x --out /tmp/generated.xml --repo <ssh-url> --branch '*/<br>' \ --set PARAM_BUILD_FILE_NAME=<project-folder-without-Cocos> --set PARAM_SIGNING_TEAM_ID=<id> --set PARAM_BUNDLE_ID=<id> \ --set PARAM_DISCORD_THREAD_ID=bun $S gen-from-spec --spec cocos-ios-3x --out /tmp/generated.xml \ --set PARAM_BUILD_FILE_NAME=<project-folder-without-Cocos> --set PARAM_SIGNING_TEAM_ID=<id> --set PARAM_BUNDLE_ID=<id> \ --set PARAM_DISCORD_THREAD_ID= # no --repo / --branch: inline pipeline, no SCMPass --set only for inputs the spec requires or the user chose; the renderer refuses an unknown
name and lists missing required inputs (gotcha ledger g-t1k-jenkins-cocos-09).
- Matched and conformant.
bun $V --config /tmp/generated.xml --expect NAME=value ...exits 0: parameter set and order equal the spec, defaults equal the spec, SCM/script match. - Every value the skill set is proven. One
--expectper--set, including parameters the spec leaves element-less (PARAM_PLAYABLE_VERSION_ID) — a pass proves the element was inserted. - Start scene is real (
cocos-playable). The verifier FAILs a blank or templatePARAM_START_SCENE, also when--expectnames that value; add--project <cocos-root>so it also FAILs a uuid that matches no.scene.meta(without it, it says the check did not run). A project cloned from the template keeps the template uuid as its real scene: pass--project <cocos-root>to both the renderer and the verifier, and a.scene.metaholding it clears the refusal. - The traps held. Element-less parameters stayed element-less (the verifier fails a stray value), the thread id is empty, no plaintext secret.
- The evidence is the verifier’s output, not the renderer’s own log: they must agree, and the
renderer’s
verifyalone is never sufficient (incident-history.md#13).
Step 4 — preview-first create
Section titled “Step 4 — preview-first create”- One job. Generate and create exactly ONE. Never a batch on the first run.
- Independent verifier green on the generated config (Step 3 gate).
- Print the URL
…/job/<folder>/job/<name>/to the user before thecreatecall. - Ask, then act. Confirm URL, spec, inputs set, trigger policy via
AskUserQuestion. Proceed only on explicit confirmation.
Then bun $S create-from-spec <folder> <name> --spec <spec> <same flags> (--dry-run previews)
and read the job back — a 200 is not evidence the config landed (gotcha ledger g-t1k-jenkins-cocos-15). Run
bun $V --fetch <folder> <job> --expect ... on the live read-back. A wrong job is fixed with an
update, never deleted (gotcha ledger g-t1k-jenkins-cocos-10). Report the job URL, the spec, every parameter set with
its value, that the API token and thread id were left for the user, and any explicit unknown.
Building a feature branch
Section titled “Building a feature branch”cocos-playable and cocos-ios-2x have no branch parameter: the branch is the fixed SCM
BranchSpec, and the Jenkinsfile loads from that same branch. To build another branch, mutate the
job, build, and revert (or merge to the tracked branch first):
bun $S update <folder> <job> --branch '*/feat/<name>' --dry-run # preview, then drop --dry-run# ... trigger and watch the build ...bun $S update <folder> <job> --branch '<the original branch>' # REVERT, alwaysReport the branch the job was left on. cocos-ios-3x has no SCM; its source is wherever the shared
ios(this) pipeline reads from, so there is no branch to switch here.
Hard rules
Section titled “Hard rules”Full list references/incident-history.md; the spec files are the parameter SSOT (references/spec-reference.md).
- Element-less parameters exist (no
<defaultValue>; adjacent ones corrupt under a naive locator). The spec encodes which; the verifier checks them.
Related
Section titled “Related”t1k-jenkins-job— the engine and the specs; its flags and batch rules are authoritative.references/platform-sdk-matrix.md— the platform-matrix flow forcocos-platform-sdkgames.t1k-setup-project/references/discord-thread.md— thread creation. This skill never creates a Discord thread: threads are provisioned inline in the main session, since a routed fork has no MCP servers.t1k:jenkins-unity— the Unity sibling: same workflow, different spec set.
Executed by
Section titled “Executed by”Runs in t1k-devops-engineer (or inline). Jenkins job generation is script-driven; deciding the job class and thread binding stays with the caller.
| Step | Agent |
|---|---|
Run scripts/detect-cocos-project.cjs, generate configs offline, run scripts/verify-params-independent.cjs | t1k-devops-engineer |
| Create the job live after the preview is approved | t1k-devops-engineer |