t1k:jenkins-job
| Field | Value |
|---|---|
| Module | t1k-devops |
| Version | 4.1.3 |
| Effort | medium |
| Tools | — |
Keywords: batch jobs, build job, ci, clone job, cocos, config.xml, create-from-spec, createItem, crumb, discord thread, jenkins, job, job spec, pipeline, playable, template job
How to invoke
Section titled “How to invoke”/t1k:jenkins-job<jenkins-folder> [--spec <name> | --from <template-job>] [--projects <dir>] [--set PARAM=value]Jenkins Job Creation: render a job spec, or clone a template job via config.xml
Section titled “Jenkins Job Creation: render a job spec, or clone a template job via config.xml”Jenkins jobs are just an XML document. GET <job>/config.xml gives you the whole thing;
POST <folder>/createItem?name=X with a mutated copy creates a new job. This skill codifies
that round-trip. Two sources for the XML:
- Spec-driven (preferred, no live template needed):
create-from-specrenders a job from a JSON spec inspecs/. See Spec-driven creation. - Clone/mutate: read template → mutate → create → verify off the server, for a job type that has no spec.
Everything runs through scripts/jenkins-job.cjs (Node ≥18, uses built-in fetch; no curl,
no shell quoting traps on Windows).
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “Create a Unity/Cocos build job” (a spec exists) | Spec-driven creation |
| “Create one job from template X” | Workflow, skip step 2 |
| “Create one job per project in this folder” | Workflow full, incl. Batch rules |
| “What jobs already exist / did it work?” | list + verify — see Commands |
| “Change a param on jobs that already exist” | update — see Commands. Always --dry-run first. |
| “Delete a job I created by mistake” | Read Hard rules first — you probably cannot. |
| “Build a branch the job is not wired for” | Sibling job; never edit the production job |
Never ask the user for a Jenkins token before checking whether they have already
supplied one. jenkins-job.cjs resolves the credential in this order, and only the
last step involves the user:
- Env —
JENKINS_URL/JENKINS_USER/JENKINS_TOKEN, if all three are set. - The registered
jenkinsMCP server —t1k-mcp-management’sinstall-jenkins.shstores the same credential in~/.claude.jsonasAuthorization: Basic base64("<user>:<api-token>"). The script reads it from there automatically. A user whose Jenkins MCP tools work has already authenticated; asking them to mint a second API token is a bug. - Ask — only when neither exists. The script says so explicitly rather than
failing with a bare
missing env.
The MCP credential is reused only when its origin matches JENKINS_URL; a mismatch is refused, never retargeted. Credentials never go on argv or into output. The env form (JENKINS_URL, JENKINS_USER, JENKINS_TOKEN) always wins; its example is in references/setup-auth.md.
Only when all three resolution steps come up empty, get a token at
<JENKINS_URL>/user/<username>/security → Add new Token.
Workflow
Section titled “Workflow”- Pull the template.
get-config <folder> <template> --out template.xml. Read it — you need to know which parameters exist, the git remote, the branch spec, thescriptPath, and whether aGitHubPushTriggeris present. - Gather per-project facts (batch only). For each project dir, read the real values instead of
guessing: git remote (
git -C <dir> remote get-url origin), branch, and any project-name field the template’s parameters expect. Present the collected table to the user before creating anything. - ASK for the Discord thread ID. HARD REQUIREMENT — see Never inherit a thread ID.
- Ask about the open decisions with
AskUserQuestion, batched into one call. At minimum: thread ID (step 3), and any parameter whose template default is demonstrably wrong for the target projects. State the evidence for “wrong” — don’t just assert it. The push trigger is not one of these questions: it follows the house policy (--strip-triggersfor develop/creative-class, omitted for release-class AND forotherunclear/master-builder jobs — they keep their trigger too), reported back rather than asked. Offer the override on that same line so the user can name a job if they disagree. - Smoke one job. Generate + create exactly ONE, then
verifyit against the server and show the user the result. Wait for approval before the rest. (rules/preview-first-batch.md) - Create the remainder, then
verifyevery job in one pass and print a table.
Commands
Section titled “Commands”S=~/.claude/skills/t1k-jenkins-job/scripts/jenkins-job.cjs
bun $S list <folder> [--grep <substr>] # existing job names (collision check)bun $S get-config <folder> <job> --out <file> # pull a templatebun $S gen --base <template.xml> --out <job.xml> \ --set PARAM_NAME=value --set OTHER=value \ --repo git@github.com:Org/Repo.git --branch '*/develop' \ --script-path Jenkinsfile/Cocos \ --description "..." [--strip-triggers]bun $S create <folder> <name> --from <job.xml> # refuses if the job existsbun $S update <folder> <name> --set PARAM=value \ [--repo ...] [--branch ...] [--script-file <groovy>] [--dry-run] # GET config -> mutate -> POST backbun $S verify <folder> <name> --expect PARAM=value \ --expect-repo <url> --expect-triggers yes|no \ [--expect-script-file <groovy>] # reads config.xml BACK off the serverbun $S set-folder-library <folder> --branch <br> [--repo <url>] [--dry-run] # repoint a FOLDER's pipeline librarybun $S create-folder <parent> <name> --branch <br> [--repo <url>] [--dry-run] # clone a folder config, library repointedFolder-library commands back the t1k-jenkins-test-pipeline skill (per-person library-branch testing).
Per-command semantics (gen --set and --add-param, update redaction and read-back, --script-file byte comparison, verify --expect-script-file): references/command-semantics.md.
Spec-driven creation
Section titled “Spec-driven creation”Specs (specs/*.json) are the single source of truth for a job type’s parameters, defaults, SCM
block, properties and triggers; scripts/jenkins-spec.cjs renders them. No live template job is read.
bun $S spec-info # list specs (name, summary, parameter count)bun $S spec-info --spec unity-android # one spec: SCM, required inputs, secrets, every parameterbun $S gen-from-spec --spec <name> --out <job.xml> --repo <ssh url> [--branch <spec>] \ --set PARAM=value ... [--strip-triggers] # offlinebun $S create-from-spec <folder> <job-name> --spec <name> <same flags, no --out> [--dry-run]--spec also takes a path to a spec file, and scm.repo is either required (--repo) or fixed (--repo refused). Details: references/spec-driven.md.
Specs today: unity-android, unity-ios, unity-webgl, unity-automation-test, unity-autotest-unified, cocos-playable,
cocos-ios-2x, cocos-ios-3x, cocos-android-2x. unity-automation-test is the pre-unification editor-only AutoTest job;
for new AutoTest jobs use unity-autotest-unified (one job, TARGET=editor|phone|emulator, calls autoTestUnifiedPipeline).
Unified AutoTest traps (each one cost a build):
- A job whose stored
LIB_REFdefault is an old sha loads the old library and fails withNo such DSL method 'autoTestUnifiedPipeline'. A stored parameter beats the Jenkinsfile’s own default, so passLIB_REF=<sha>on the first build of a repointed job. A new job from this spec renders no default. - Always pass
BRANCH. A stored default may be an old feature branch that still carries the old Jenkinsfile. - Do not overlap two Unity builds on sv-2 (shared swap gate, shared prod host).
TARGET=phone: the phone must be awake and unlocked at stage 2, its NetBird peer reachable, and have ~1 GB free storage (the APK is ~204 MB).- A green build proves the new Jenkinsfile only when the log shows
Loading library ... Selected match.
The renderer refuses every problem at once, secrets never travel through argv (set them with set-secret), and a changed default is a spec edit plus its renderer test. The refusal list and the callers: references/spec-driven.md.
Never inherit a thread ID
Section titled “Never inherit a thread ID”For a cloned job. A spec-rendered job leaves PARAM_DISCORD_THREAD_ID empty (no spec carries one),
which is the safe state: nothing is inherited.
A template job’s PARAM_DISCORD_THREAD_ID (or any notification target: webhook URL, chat room,
channel ID) points at whatever thread the template’s author was using. Copying it means every
new job posts build notifications into someone else’s thread.
Always AskUserQuestion for the thread ID before creating any job. Do not reuse a value because
it appeared in the template, in a previous run of this skill, or earlier in the conversation —
unless the user names that exact value in this request. If the user does not know it yet, stop and
wait; do not create the jobs with a placeholder intending to fix it later.
Same rule for PARAM_DISCORD_WEBHOOK_URL and PARAM_GOOGLE_CHAT_WEBHOOK_URL when they are non-empty
in the template.
Building a branch the job was not made for
Section titled “Building a branch the job was not made for”- Check the parameter list first.
WarShip-Developcarries 34PARAM_*parameters and no branch parameter at all, its SCM branch hardcoded*/develop; never add one to the production job. - Copy it instead.
get-configit,genthe copy with your branch spec,createa sibling<Job>-Experiment,verifyit back off the server (branch spec, repo, tool name). No push trigger, andPARAM_SHOULD_NOTIFY_TO_CHAT_CHANNEL=false(the template defaults ittrue).
Batch rules
Section titled “Batch rules”- Collision check first —
list <folder>and compare case-insensitively. Jenkins job names are case-sensitive in the API, soTestandtestcan coexist and confuse everyone later. - Derive, never assume. Read the project name from the project’s own manifest / folder name and
apply whatever transform the template’s parameter documents (its
<description>usually says). - Uniform ≠ verified. Even when 11 projects look identical, read all 11. One outlier that you assumed away becomes a broken job.
- Report what you did NOT set. Any template parameter you left at its default, but which is arguably per-project, goes in the final report explicitly.
Hard rules
Section titled “Hard rules”set-secretis the only way to set a Password parameter.jenkins-job.cjs set-secret <folder> <job> --param NAME[,NAME] --from-file <path> | --stdinreads thepass:line of a keystore password record (or one stdin line), refuses a non-Password parameter, and reads the stored default back: it must be a{AQ...}blob that changed.update --seton a Password parameter is refused for the same reason.- A secret POSTed into a password parameter is encrypted by Jenkins on save. Writing a plaintext
<defaultValue>into aPasswordParameterDefinitionviacreateItem/POST config.xmlreads back as{AQAAABAA…}(observed on CocosPlayableLabs/FindTheSuspectsPLA2, core#3497), so no UI re-save is needed. Still don’t print the value;verifyby checking it starts with{, not by comparing plaintext. git@github.com:remotes need a matchingcredentialsIdalready configured in Jenkins. The template’s credential is inherited by the clone — if the new repos live under a different org, the SSH key may not grant access, and that surfaces only at first build.
Trigger policy (house, 2026-09)
Section titled “Trigger policy (house, 2026-09)”The GitHubPushTrigger is no longer a per-run keep-or-strip question. Class decides the trigger:
| Job class | Trigger |
|---|---|
develop | stripped |
creative | stripped |
other (no release signal and no informative spec/suffix — a “master builder”) | kept |
release | kept |
develop and creative jobs do not build on push; the t1k-jenkins-build skill decides whether a
merged change deserves a build, and the user can always press Build in Jenkins. release AND
other (unclear/master-builder) jobs keep the trigger (2026-09 house policy: “unclear jobs keep
auto-build”) — the fleet already has master/main-only jobs classed release-type with kept triggers,
so a new job with the same unclear shape must land the same way, not diverge from what the fleet
already does.
TimerTrigger is always kept — it drives nightly jobs and CleanWS, and is not a push trigger.
WorkflowMultiBranchProject jobs are not affected at all: branch indexing builds regardless of
push triggers.
Job class (M7: the same rule everywhere)
Section titled “Job class (M7: the same rule everywhere)”Release dominates, and the branch spec decides first — this is the ONE rule, and it is the SAME
rule deriveClass() implements in t1k-jenkins-build/scripts/jenkins-build.cjs (H2). Classify from
the branch spec in config.xml: any spec matching release* / */release-* is release, and so
is a job name ending -Release — regardless of what else the spec set contains, because release
gates the trigger and an ambiguous read must never resolve toward “safe to auto-trigger”. Absent a
release signal, a single other class found in the spec set (develop or creative) is used as-is;
when the spec set names MORE than one non-release class, that is other — ambiguous specs are never
guessed wide. Only when the spec gives no signal at all (*, master, empty) is the job name
consulted, and only for its -Creative suffix — never for -Develop: a job named Foo-Develop
that actually builds master classifies other, because guessing it wide is how the wrong job gets
triggered. Jobs exist in the fleet proving names lie in both directions: one with no -Develop
suffix builds */develop, another named nothing useful builds master.
Restrict any bulk script-console change to a preview-first batch, back up each job’s removed
<triggers> block verbatim, and verify by reading the config back. A user’s explicit sentence
naming a job overrides the policy for that job; nothing else does.
Creating Jenkins jobs from a template job’s config.xml, and changing parameter defaults / git
remote / branch on jobs that already exist, plus the read-only list / get-config / verify
support around it. Not for: deleting jobs, triggering or aborting builds, managing
credentials/nodes/plugins, or editing Jenkinsfiles and shared pipeline libraries.
Related tooling
Section titled “Related tooling”Related tooling (credential names shared with the Jenkins MCP, no MCP job-creation tool, and the projectUrl caveat): references/related-tooling.md.
Executed by
Section titled “Executed by”Runs in t1k-devops-engineer (or inline). Every call goes through scripts/jenkins-job.cjs; choosing the template and job class is judgment.
| Step | Agent |
|---|---|
Run scripts/jenkins-job.cjs (clone, mutate, preview, create) | t1k-devops-engineer |