Skip to content

t1k:jenkins-job

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

/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-spec renders a job from a JSON spec in specs/. 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).

IntentPath
“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:

  1. Env — JENKINS_URL / JENKINS_USER / JENKINS_TOKEN, if all three are set.
  2. The registered jenkins MCP server — t1k-mcp-management’s install-jenkins.sh stores the same credential in ~/.claude.json as Authorization: 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.
  3. 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.

  1. 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, the scriptPath, and whether a GitHubPushTrigger is present.
  2. 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.
  3. ASK for the Discord thread ID. HARD REQUIREMENT — see Never inherit a thread ID.
  4. 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-triggers for develop/creative-class, omitted for release-class AND for other unclear/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.
  5. Smoke one job. Generate + create exactly ONE, then verify it against the server and show the user the result. Wait for approval before the rest. (rules/preview-first-batch.md)
  6. Create the remainder, then verify every job in one pass and print a table.
Terminal window
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 template
bun $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 exists
bun $S update <folder> <name> --set PARAM=value \
[--repo ...] [--branch ...] [--script-file <groovy>] [--dry-run] # GET config -> mutate -> POST back
bun $S verify <folder> <name> --expect PARAM=value \
--expect-repo <url> --expect-triggers yes|no \
[--expect-script-file <groovy>] # reads config.xml BACK off the server
bun $S set-folder-library <folder> --branch <br> [--repo <url>] [--dry-run] # repoint a FOLDER's pipeline library
bun $S create-folder <parent> <name> --branch <br> [--repo <url>] [--dry-run] # clone a folder config, library repointed

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

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.

Terminal window
bun $S spec-info # list specs (name, summary, parameter count)
bun $S spec-info --spec unity-android # one spec: SCM, required inputs, secrets, every parameter
bun $S gen-from-spec --spec <name> --out <job.xml> --repo <ssh url> [--branch <spec>] \
--set PARAM=value ... [--strip-triggers] # offline
bun $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_REF default is an old sha loads the old library and fails with No such DSL method 'autoTestUnifiedPipeline'. A stored parameter beats the Jenkinsfile’s own default, so pass LIB_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.

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-Develop carries 34 PARAM_* parameters and no branch parameter at all, its SCM branch hardcoded */develop; never add one to the production job.
  • Copy it instead. get-config it, gen the copy with your branch spec, create a sibling <Job>-Experiment, verify it back off the server (branch spec, repo, tool name). No push trigger, and PARAM_SHOULD_NOTIFY_TO_CHAT_CHANNEL=false (the template defaults it true).
  • Collision check first — list <folder> and compare case-insensitively. Jenkins job names are case-sensitive in the API, so Test and test can 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.
  • set-secret is the only way to set a Password parameter. jenkins-job.cjs set-secret <folder> <job> --param NAME[,NAME] --from-file <path> | --stdin reads the pass: 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 --set on 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 a PasswordParameterDefinition via createItem/POST config.xml reads back as {AQAAABAA…} (observed on CocosPlayableLabs/FindTheSuspectsPLA2, core#3497), so no UI re-save is needed. Still don’t print the value; verify by checking it starts with {, not by comparing plaintext.
  • git@github.com: remotes need a matching credentialsId already 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.

The GitHubPushTrigger is no longer a per-run keep-or-strip question. Class decides the trigger:

Job classTrigger
developstripped
creativestripped
other (no release signal and no informative spec/suffix — a “master builder”)kept
releasekept

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.

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 (credential names shared with the Jenkins MCP, no MCP job-creation tool, and the projectUrl caveat): references/related-tooling.md.

Runs in t1k-devops-engineer (or inline). Every call goes through scripts/jenkins-job.cjs; choosing the template and job class is judgment.

StepAgent
Run scripts/jenkins-job.cjs (clone, mutate, preview, create)t1k-devops-engineer