Skip to content

t1k:cocos:h5:jenkins-setup

FieldValue
Moduleh5
Version0.9.8
Effortmedium
Tools—

Keywords: autobuild job, cocosplayablelabs, game autobuild, game ci job, h5 build job, h5 game autobuild, h5 game job, h5 game on jenkins, h5 game repo, h5 jenkins, h5 pipeline, jenkins job for the h5 game, jenkins platform matrix, new h5 game, platform matrix job, platformmatrix, rocktesth5, set up the h5 build job, setup h5 game, testh5template

/t1k:cocos:h5:jenkins-setup
[<repo-path>] [--repo <The1Studio/Repo>] [--thread <discord-thread-id>] [--dry-run]

One H5 game repo gets one Jenkins job that builds it for every portal target through cocos-platform-sdk’s PlatformMatrix pipeline. This skill checks the repo is actually ready to be built, then creates and verifies that job — seeding its per-portal checkboxes with the portals the game picked, so the job page is correct before the first build.

The repo already exists. It is created by hand from The1Studio/H5CocosTemplate — this skill never clones a template, never creates a repository, and never pushes an initial commit. Its input is a working copy of a repo that already has a remote.

Not this skill: provisioning the repo itself, and not the playable-ad path. A playable ad is one ad-network deliverable scaffolded from PlayableAdsTemplate and tracked by t1k:cocos:playable:pipeline — different product surface, different template, different job shape. The contract this job runs under is cocos-platform-sdk’s docs/ci-game-autobuild.md; read that doc, do not restate it here.

IntentPath
“Set up the build job for this H5 game”Workflow, all steps
“Is this repo ready to be built at all?”Step 1 alone — it is read-only and reports every unmet precondition at once
“The job exists but a build fails”Not this skill — the failure is pipeline-side. Re-read ci-game-autobuild.md and the job’s console log, then check the Hard rules row that matches the error
“Just create the Jenkins job, I checked the repo myself”Step 2 onward, with --repo <origin-url>
“Which template / which Jenkins folder?”Steps 1 and 3 — job name is <Repo>-PlatformMatrix, folder is CocosPlayableLabs
“The job page shows the wrong portals ticked”Step 3’s seed — it derives the boxes from the repo’s ci/platform-matrix.json targets
NeedCheckIf missing
A hand-made repogit -C <repo> remote get-url origin ends in The1Studio/<Repo>.gitCreate it from The1Studio/H5CocosTemplate by hand first. This skill does not do it
Jenkins reachablebun ~/.claude/skills/t1k-jenkins-job/scripts/jenkins-job.cjs list CocosPlayableLabs --grep PlatformMatrixt1k-jenkins-job § Setup. Auth reuses the jenkins MCP credential; never pass a token as argv, and never print or ask for one
A Discord thread idThe user supplies it — see step 2Ask. There is no derivation, and no default

Step 1 — Preconditions: read them, never guess

Section titled “Step 1 — Preconditions: read them, never guess”

All seven are checkable from the game repo alone. Run them in one pass and report every failure at once, each with the fix — a repo that fails three of these should not need three round trips. The seven checks, each with its read command and its fix, plus the repair unit for rows 6 and 7, are in references/preconditions.md. Run all seven in one pass.

A Jenkinsfile/PlatformMatrix that is a thin loader calling platformMatrix(configFile: 'ci/platform-matrix.json') is correct — do not “improve” it by adding a pipeline {}, parameters {} or stages {} block. A Declarative pipeline may exist only once per run, and the library step owns all three.

Step 2 — Ask for the Discord thread id, and only that

Section titled “Step 2 — Ask for the Discord thread id, and only that”

Everything else this skill writes is derivable from the repo: the job name is <Repo>-PlatformMatrix, the folder is CocosPlayableLabs, the SCM URL is the origin remote, the branch is */develop, the script path is Jenkinsfile/PlatformMatrix. The thread id is the one value nothing can derive, so it is the one question — ask it with AskUserQuestion.

Never reuse a thread id from another job. A thread id carried over from a sibling repo posts this game’s build results into the wrong Discord thread, and nothing downstream flags it. If the user does not have one, stop here rather than inventing a placeholder: a job created with a copied or fake id looks healthy and reports to the wrong place.

Step 3 — Create the job through t1k-jenkins-job

Section titled “Step 3 — Create the job through t1k-jenkins-job”

Job creation is not re-implemented here. Every Jenkins config.xml mechanic — auth, crumb, createItem, the verify read-back — is owned by core’s t1k-jenkins-job; call its script.

The two paths resolve differently, and that is correct. t1k-jenkins-job ships with core, which installs to the user scope, so its script lives under ~/.claude/. This skill’s own script ships with theonekit-cocos, which installs per project — into the game repo’s own .claude/ — so it is reached project-relative, exactly like every other t1k-cocos-* script (bun .claude/skills/t1k-cocos-base-compref/scripts/compref.cjs). A ~-rooted SEED is wrong: the skill would find its own script only on a machine that also had the whole cocos kit installed globally, and nowhere else.

The block below is fail-closed end to end. The seed’s argv is what ticks the boxes, so a seed that failed silently would leave a job looking seeded and building nothing, and $(cat …) over an empty file expands to nothing — the failure mode is invisible. set -euo pipefail makes a failed bun abort the script instead of continuing with an empty substitution; the -s guards assert each file is non-empty before it is consumed; and the --expect token list is computed into a checked file before create, never inline in the verify command, so a seed that fails after the job exists cannot also silently skip the verification of it.

Run the command sequence in references/job-creation.md: collision check, get-config, seed, gen, the size-checked expect list, create, then verify. The seed and expect files must be non-empty before the next step runs; the expect list covers every box, not just the thread id.

The verify above is the read-back the tick-count rests on. It fetches config.xml off the server and fails unless every box matches, so a green run asserts the ticked set equals the game’s picked targets — not merely that some box was written. A FAIL there means the seed and the created job disagree; re-clone rather than hand-editing the XML. Note where its token list comes from: /tmp/<Repo>-expect.txt, computed and size-checked in step 3b, not a fresh $(bun …) in the verify command. An inline substitution that produced nothing would leave verify checking only the thread id and repo — reporting success while asserting nothing about the boxes.

Keep the GitHubPushTrigger. --strip-triggers is for a job you intend to drive by hand, and a game autobuild job driven by hand is not an autobuild job. verify --expect-triggers yes is the assertion that it survived gen.

When the seed exits non-zero, stop — do not create the job. It fails closed on three distinct inputs (not ids this clone declares, no TARGET_* BooleanParameterDefinition, cannot read the job's inputs), each with its own fix. Ids match exactly and case-sensitively, so Yandex or quickgame_oppo is a typo the seed will not paper over. Causes and fixes: references/seed-failures.md.

Creating the job makes Jenkins install https://jenkins.the1studio.org/github-webhook/ on the repo. Verify it rather than assuming:

Terminal window
gh api repos/The1Studio/<Repo>/hooks --jq '.[].config.url'

A POST to the same endpoint that returns 422 “Hook already exists” is confirmation, not an error. A repo with no hook is a repo whose pushes never reach the job — the push trigger in the config is not the same thing as the webhook that fires it.

Trigger the job once — Jenkins MCP triggerBuild, or a push to develop.

The boxes are already on the page, ticked as seeded, so run #1 builds the game’s targets without a manual tick. That holds only with The1Studio/cocos-platform-sdk#206 merged, and the dependency is not optional: without it, run #1 resets every box to unticked, and a manual run honours any tick it finds. The mechanics and the two #206 commits: references/first-build.md.

Job URL, Discord thread id, the targets list read back from ci/platform-matrix.json, the seed-target-params: … ticked <n> line from step 3’s seed, and the first build’s result. Say which of the two the first build actually was — a real build, or a run that failed before reaching a target. Also say whether cocos-platform-sdk#206 is merged yet: until it is, the seed is a one-run courtesy rather than a durable state (see step 5).

seed-target-params.cjs and jenkins-job.cjs list: t1k-fact-fetcher. Thread-id question and job creation: orchestrating skill/user.

  • changelog: false is load-bearing, not decoration. Without it a job polls every repo its last build checked out, so every cocos-platform-sdk merge starts every game job — one SDK release becomes a fleet-wide build storm. This is precondition 2 and the single most common cause of “why did our job just start?”.
  • Game mode checks out submodules and cleans the workspace itself, inside the pipeline library (cocos-platform-sdk #172, #174), not in the job config. If every target fails with Missing class or Module "db://assets/H5GameFoundation/..." not found, the job is running an older library: check its LIBRARY_REF and the loaded cocos-platform-sdk commit in the console log.
  • Creator’s “Missing class” race is rebuilt up to 3 builds per target (cocos-platform-sdk #175). A single failed target is therefore not proof the game is broken — check whether that target was retried before reporting a failure. Reporting a retry that eventually succeeded as a defect wastes a pipeline investigation.
  • SDK_SOURCE defaults to pinned in a game job — it builds against the SDK version committed in the repo’s extensions/platform-manager, installed from CPM. “The pipeline has a bug we already fixed” is usually a repo that has not bumped its pinned SDK yet.
  • A declarative parameters {} block re-evaluates on every run, so a seeded default is not permanent — which is exactly why the seed is safe. The pipeline’s booleanParam(name: 'TARGET_<ID>', …) rows are re-derived each run from ci/platform-matrix.json (cocos-platform-sdk#206), which rewrites the job’s stored defaults. So the seed this skill writes is the page’s state only before run #1 — but it is not undone by a later run, because the rewrite derives the SAME ticks from the SAME config file the seed read. The distinction that matters: without #206 the rewrite is a literal false and the first run blanks the page; with it the page converges on the config either way. That is also why editing targets — not the boxes — is how a game’s portal set is changed.
  • Portal choice per run is the TARGET_<ID> checkboxes on Build with Parameters — but only on a run a user starts, and only when the ticked set differs from the config’s own defaults (cocos-platform-sdk#206). A ticked set equal to the defaults counts as “no choice” and falls through to TARGETS, then the config; a push-triggered, timer or upstream run ignores the boxes entirely, because their stored defaults are the previous run’s config. Ticking none also falls back to the config’s targets. Do not edit targets to build one portal for one run. At job creation the seed ticks exactly the game’s picked targets.
  • Credentials: never print and never ask. t1k-jenkins-job reuses the Jenkins MCP credential from ~/.claude.json (or JENKINS_URL/JENKINS_USER/JENKINS_TOKEN from env). Do not echo an env var, do not put a token on a command line, and do not ask the user to paste one into the conversation.
  • Creates a Jenkins job, its parameters, and its SCM/trigger config; seeds its TARGET_<ID> checkboxes from the repo’s picked targets, and verifies the repo webhook.
  • Does not create the git repo, clone a template, push a commit, or write game code.
  • Does not own the pipeline itself. Mode selection, target adapters, SDK sourcing and the PlatformMatrix step belong to cocos-platform-sdk and are documented in its docs/ci-game-autobuild.md.
  • Does not create Plane work items. Tracking for an H5 game is out of scope here.
  • t1k-jenkins-job (theonekit-core) — the job-creation mechanics this skill calls and does not restate
  • scripts/seed-target-params.cjs — this skill’s own script: reads the TARGET_<ID> names and their published ids from the cloned config and emits the --set/--expect tokens for the game’s picked targets. It ships with this kit, so it is invoked project-relative (.claude/skills/t1k-cocos-h5-jenkins-setup/scripts/seed-target-params.cjs), unlike t1k-jenkins-job’s script under ~
  • cocos-platform-sdk PR #206 — the required companion: it makes each checkbox default configTicks('<id>') and reads the boxes only on a user-started run whose ticked set differs from the config defaults. Merged as the two commits in Related. Without it the first run blanks the seeded page; the skill’s step 5 states this dependency in full
  • cocos-platform-sdk → docs/ci-game-autobuild.md — the pipeline contract this job runs under
  • cocos-platform-sdk scripts/ci-gen-jenkins-params.mjs — the TARGET_<ID> naming rule this skill’s script mirrors (paramName()) and the id→label shape its exact-id match reads (label(), which writes '<id> · <portal>' into the box’s <description>); a new portal row there is what makes a stale clone detectable
  • The1Studio/H5CocosTemplate — the repo template the game repo is made from by hand
  • t1k:cocos:playable:pipeline — the playable-ad path (different template, different deliverable)

Related: commits 48dc38c, 4e47b36, 34fd49e.