t1k:cocos:h5:jenkins-setup
| Field | Value |
|---|---|
| Module | h5 |
| Version | 0.9.8 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/t1k:cocos:h5:jenkins-setup[<repo-path>] [--repo <The1Studio/Repo>] [--thread <discord-thread-id>] [--dry-run]Cocos H5 — Jenkins Autobuild Setup
Section titled “Cocos H5 — Jenkins Autobuild Setup”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.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “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 |
Prerequisites
Section titled “Prerequisites”| Need | Check | If missing |
|---|---|---|
| A hand-made repo | git -C <repo> remote get-url origin ends in The1Studio/<Repo>.git | Create it from The1Studio/H5CocosTemplate by hand first. This skill does not do it |
| Jenkins reachable | bun ~/.claude/skills/t1k-jenkins-job/scripts/jenkins-job.cjs list CocosPlayableLabs --grep PlatformMatrix | t1k-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 id | The user supplies it — see step 2 | Ask. There is no derivation, and no default |
Workflow
Section titled “Workflow”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.
Step 4 — Confirm the webhook
Section titled “Step 4 — Confirm the webhook”Creating the job makes Jenkins install https://jenkins.the1studio.org/github-webhook/ on the repo.
Verify it rather than assuming:
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.
Step 5 — First build
Section titled “Step 5 — First build”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.
Step 6 — Report
Section titled “Step 6 — Report”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).
Executed by
Section titled “Executed by”seed-target-params.cjs and jenkins-job.cjs list: t1k-fact-fetcher. Thread-id question and job creation: orchestrating skill/user.
Hard rules
Section titled “Hard rules”changelog: falseis 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 classorModule "db://assets/H5GameFoundation/..." not found, the job is running an older library: check itsLIBRARY_REFand 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_SOURCEdefaults topinnedin a game job — it builds against the SDK version committed in the repo’sextensions/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’sbooleanParam(name: 'TARGET_<ID>', …)rows are re-derived each run fromci/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 literalfalseand the first run blanks the page; with it the page converges on the config either way. That is also why editingtargets— 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 toTARGETS, 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’stargets. Do not edittargetsto build one portal for one run. At job creation the seed ticks exactly the game’s pickedtargets. - Credentials: never print and never ask.
t1k-jenkins-jobreuses the Jenkins MCP credential from~/.claude.json(orJENKINS_URL/JENKINS_USER/JENKINS_TOKENfrom 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 pickedtargets, 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
PlatformMatrixstep 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.
Related
Section titled “Related”t1k-jenkins-job(theonekit-core) — the job-creation mechanics this skill calls and does not restatescripts/seed-target-params.cjs— this skill’s own script: reads theTARGET_<ID>names and their published ids from the cloned config and emits the--set/--expecttokens for the game’s pickedtargets. It ships with this kit, so it is invoked project-relative (.claude/skills/t1k-cocos-h5-jenkins-setup/scripts/seed-target-params.cjs), unliket1k-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— theTARGET_<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 handt1k:cocos:playable:pipeline— the playable-ad path (different template, different deliverable)
Related: commits 48dc38c, 4e47b36, 34fd49e.