t1k:jenkins-build
| Field | Value |
|---|---|
| Module | t1k-jenkins |
| Version | 3.7.52 |
| Effort | medium |
| Tools | — |
Keywords: auto build, build, build develop, build url, ci build decision, decide build, develop build, develop-class branch, jenkins, jenkins build, jenkins trigger, run the develop build, should this build, skip build marker, trigger build
How to invoke
Section titled “How to invoke”/t1k:jenkins-build<git remote | job name> [--branch <name>] [--repo-dir <path>]Jenkins Build Decision — should this change build, and start it if so
Section titled “Jenkins Build Decision — should this change build, and start it if so”Develop-class Jenkins jobs no longer build on push. Something has to decide whether a merged change deserves a build, and that something is this skill: it gathers facts, applies the rubric, and either triggers the job, asks the developer, or stays quiet.
Everything runs through scripts/jenkins-build.cjs (Node >= 18, built-in fetch, no
dependencies). The script emits facts as JSON; the reasoning below is the skill
body’s job, per rules/ai-driven-design.md. The rubric itself lives in
references/decision-rubric.md; file classification lives in the data file
references/file-classes.json, so adding an engine means adding globs, not editing code.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| A merge just landed on a develop-class branch | Deciding a merge |
[t1k:develop-build-decision ...] frame appeared | Deciding a merge under the standing approval |
| “build X develop” / “trigger the build” from the user | Explicit request |
| “should this build?” | facts, then the rubric, then report the verdict without triggering |
| “which job builds this repo/branch?” | resolve |
| A Release job | Release preflight, then refuse unless the user names that job in an explicit sentence |
Policy
Section titled “Policy”- Auto when confident. Every signal green means trigger without asking. The user’s policy is standing approval for that case; asking anyway is the failure mode here.
- Ask when mixed. Signals in conflict (plan still open but commits look complete,
tests not run, only config changed, last build failed and the fix is unclear) means
report the signals and ask. Use
AskUserQuestion, never a prose question. - Skip on work-in-progress. WIP markers unless an explicit
[build]is present (rubric § Marker precedence), a[skip build]marker, docs-only or ci-only changes, nothing new since the last built SHA, or a build for the same SHA already running. A skip is silent: one line at most, never a question. - Release is never automatic.
triggerrefuses anything that is not develop or creative class. Passing--allow-classis allowed only after an explicit user sentence naming that job, and the script records that it was overridden. On the class that the allow-list refuse path covers —release, andother(a release job whose spec says only*/main/*/masterand whose name lacks-Release) — the trigger ALSO runs the project’s release preflight first, see Release preflight. - Merges outside this session get no decision. A merge in the GitHub UI, or an
--automerge that lands after the session ends, never reaches this skill. The user’s stated fallback is asking the AI or pressing Build in Jenkins. Do not claim coverage the session does not have. - No Jenkins, no noise. No job matches the repo, or no credential resolves: say so in one line and move on. Never block a merge or a cleanup step on this.
The push trigger stays on Release jobs, so a push to a release branch already builds without help. That is the reason for rule 4.
Commands
Section titled “Commands”S=~/.claude/skills/t1k-jenkins-build/scripts/jenkins-build.cjs
bun $S resolve --repo <git-remote-url> --branch <name> # jobs whose SCM + branch spec matchbun $S facts --job <fullName> --repo-dir <path> --branch <name> # JSON facts for the rubricbun $S trigger --job <fullName> [--param K=V ...] [--wait] [--allow-class <name>] [--force]bun $S trigger --job <fullName> --repo-dir <path> --branch <name> [--allow-class <name>] # + the release preflightbun $S preflight --job <fullName> --repo-dir <path> --branch <name> # run the release gate, no triggerbun $S preflight --list # what is configured, and whether each command resolvesbun $S wait --job <fullName> --build <n> [--timeout-min 9] [--interval-sec 60] # poll an EXISTING build to terminal; exit 2 = unknownresolve, facts (which requires --branch), trigger (which re-checks the queue and accepts only 201 Created plus a Location) and wait are described in references/command-semantics.md. Read it before the first call.
Triggers, branch spec and scriptPath come only from config.xml. api/json hides
trigger children and the definition block, so a facts pass that trusted api/json
would report “no trigger” for a job that has one.
Deciding a merge
Section titled “Deciding a merge”- Confirm the target is develop-class.
resolve --repo <remote> --branch <name>. No match is a one-line “no Jenkins job for this repo/branch” and the step ends. More than one match is normal, not an error (L6) — a repo commonly has an Android AND an iOS job both building the same develop branch. Run steps 2-5 for EACH matched job independently: they are genuinely separate builds with their own facts, verdicts, and trigger calls, not one decision applied twice. Report one verdict block per job. - Gather facts.
facts --job <fullName> --repo-dir <repo path> --branch <name>. - Apply the rubric in
references/decision-rubric.md. Read the whole fact set before deciding; a single green signal is not a BUILD. - Act on the verdict. BUILD: trigger via
scripts/jenkins-build.cjsONLY — never the MCPtriggerBuildtool, see Jenkins MCP — then report the URL. ASK: report the conflicting signals and ask. SKIP: one line, no question. - Always report verdict + driving signals + build URL. Never trigger silently.
The [t1k:develop-build-decision ...] frame
Section titled “The [t1k:develop-build-decision ...] frame”The hook emits [t1k:develop-build-decision repo=<remote|unknown> branch=<name|pr-merge> pr=<number|none>] after a non---auto gh pr merge or a develop-class push. Treat it as a request to run this decision under the standing approval: a confident BUILD proceeds, a mixed signal set asks, and WIP skips quietly unless [build] is present. It never authorizes a Release build. How to resolve branch=pr-merge, pr=none and repo=unknown: references/merge-frame.md.
Avoiding a double decision (R12)
Section titled “Avoiding a double decision (R12)”jenkins-build-nudge’s frame and a git-manager step 5 / t1k-babysit-pr post-merge
report can describe the SAME merge or push: the Bash call that performs it is exactly
what the hook is watching, so the same call that produces step 5’s raw facts (or
babysit-pr’s own merge) also fires the hook’s frame, same session, same turn. Match
them by repo + branch for a push, repo + PR number for a merge: when a
[t1k:develop-build-decision ...] frame with that repo and branch/pr already appeared
this turn, treat the cleanup step’s raw facts as belonging to THAT frame’s decision, not
a second one — run steps 1-5 once for the merge, and report one verdict, never two. Only
run the rubric independently from step 5’s / babysit-pr’s own facts when NO matching
frame appeared this turn (the hook was disabled, its own repo resolution came back
unknown, or the merge landed via a path the hook does not watch). This is the ONE
place the matching rule is defined — agents/t1k-git-manager.md step 5 and
skills/t1k-babysit-pr/SKILL.md’s post-merge step both point back here rather than
each carrying their own copy.
Explicit request
Section titled “Explicit request”“Build X develop” from the user goes straight to trigger, skipping the rubric’s
auto-decision only in that the user’s request is itself the decision. Still run facts
first when the user asks a question rather than giving an instruction (“should this
build?”). Never pass --allow-class on the strength of an inference; the user must name
the job.
Which version a build gets
Section titled “Which version a build gets”Unity Release jobs with PARAM_AUTO_VERSION=true take their version name from the stores, not the
branch, and Android builds fail loudly when BUILD_NUMBER is not above the highest Play versionCode.
references/version-resolution.md has the resolution rule and what each failure means; the parameter
is sticky, so pass it explicitly when it matters.
Release preflight
Section titled “Release preflight”The release gate runs before any release-class trigger. It reads releasePreflight.checks from the t1k-config-*.json fragments and fails closed (exit 3 for blocked, exit 4 for cannot-run, nothing POSTed). preflight --list is the read-only wiring probe. Branch matching, parameterised specs and exit semantics: references/release-preflight.md.
What this does NOT enforce. A push to a release* branch (the job keeps its
GitHubPushTrigger), the Jenkins UI Build button and the MCP triggerBuild tool never reach
jenkins-build.cjs. For those the in-build gate is the only check, after the job is queued and
the project is open.
Bypass is recorded, not prevented. Any non-empty value of the check’s bypassEnv in the
CALLER’s shell turns that check into skipped; the trigger reports it in the preflight array
and appends one JSON line ({ts, job, branch, checkedSha, var}) to
<claudeDir>/telemetry/release-preflight-bypass.jsonl. Deleting the config key disables the
gate the same way. Say so in the verdict — an unreported bypass is the failure mode.
Jenkins MCP, when it is loaded
Section titled “Jenkins MCP, when it is loaded”Never use the MCP triggerBuild tool for this skill (H3). It bypasses
checkTriggerAllowlist, the script-only guard that refuses a Release job without an explicit
--allow-class. Triggering goes through scripts/jenkins-build.cjs trigger ONLY, every time,
regardless of whether the jenkins MCP server is loaded this session.
The MCP’s read-only tools (getBuild, getBuildLog) are fine for STATUS checks — polling a
triggered build, reading its log — because they carry no trigger path and no allow-list to bypass.
Auth resolution matches t1k-jenkins-job: env vars JENKINS_URL / JENKINS_USER / JENKINS_TOKEN, then the registered jenkins MCP credential (host-guarded; a user whose Jenkins MCP works has already authenticated, so do not ask for a new token), then ask. The shared library is core’s .claude/hooks/lib/jenkins-auth.cjs. Credentials never go on argv or into output. Details: references/setup-auth.md.
Hard rules
Section titled “Hard rules”-
Every parameter is sticky in The1Studio’s pipelines. Each job’s Jenkinsfile declares parameter defaults as
env.PARAM_X ?: <fallback>, so atriggercall that omits a parameter does NOT fall back to the Jenkinsfile’s own default — it re-runs with whatever value the PREVIOUS build happened to use. If the verdict depends on a specific parameter value (a clean-build flag, a target platform, a feature toggle), pass it explicitly; do not assume an omitted parameter means “the Jenkinsfile’s stated default”.factsreports every parameter’s CURRENT declared default asinheritedParams(secrets redacted as<redacted>, every other value stripped of any embedded URL userinfo) and flags a release-flavored one asinheritedReleaseMarkers(references/release-markers.json— thePRODUCTIONdefine symbol, a distribute/store/upload flag set totrue; one grouped entry per matched parameter,{name, value, ruleIds, reasons}— a name can legitimately satisfy more than one rule, e.g.DISTRIBUTE_TO_STORE). See decision-rubric.md’s Marker precedence rule 6: it downgrades a preliminary BUILD to ASK on any develop-class job that has one — but only once a build could actually start, i.e. only when rule 4 or rule 5 already computed BUILD (I1). A silent[skip build]or WIP-only SKIP (rules 2 and 3), and any ASK or SKIP the rest of the rubric (rule 5) reaches on its own — docs-only, ci-only, nothing new — all still win over this signal unmodified, since no build is happening (or none was going to be flagged any more cautiously) for a sticky parameter to matter to; policy 3 above still applies unmodified in that case. State this in the verdict output too: name any parameter the decision depends on and whether it was passed explicitly or left to inherit from the last build. -
A job name ending
-Releasedominates every branch spec.deriveClass()reads the NAME as well as the spec set, so a job calledFoo-Releasewhose spec says*/developstill classifiesrelease— the preflight runs and the allow-list refuses. When you expect a develop-class job, check the name, not just the spec. -
A single
*never crosses a slash in a branch spec.*/release*does NOT matchrelease/1.2(onlyrelease-1.2); use*/release/*for a slash-style release branch.contract.md§ 5’s parenthetical says otherwise and is wrong; the matcher’s own doc comment andtests/jenkins-build.test.cjsare the authority, andtests/release-preflight.test.cjspins this so nobody “fixes” the matcher to satisfy the prose. -
Testing the trigger (child-process fake Jenkins, and a private
HOME) and the shared config reader (readConfigFragments(), no second hand-rolled scanner):references/testing-notes.md. -
Never poll the CDN build URL to see whether a build is done.
cdn.builds.the1studio.orgsits behind Cloudflare, which caches a 404 formax-age=3600: a GET issued before the Jenkins upload finishes pins the 404 at that edge for an hour, and the link posted to Discord then 404s for everyone hitting it. Verify through Jenkins instead: poll the build status, or wait for theFinished: Uploading to .../index.htmlconsole line. If you must fetch the page early, add a cache-busting query (index.html?v=<n>), never the bare URL.
Executed by
Section titled “Executed by”Mixed: the two fact-gathering steps (resolve, facts) are lookups for t1k-fact-fetcher, and the verdict is judgment that stays in this skill body. Rationale: references/executed-by.md.
Routing SSOT: docs/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
resolve — which jobs match this repo/branch | t1k-fact-fetcher |
facts — last build state, commits since the built SHA, markers | t1k-fact-fetcher |
Poll a build to terminal status (trigger --wait, or wait --build <n> for one already running) | t1k-ci-watcher |
| Apply the BUILD / ASK / SKIP rubric and report the verdict | premium (the skill body itself) |
Deciding whether a change deserves a develop-class build, and triggering it. Reading job
and build facts for that decision. Not for: creating or editing jobs (use
t1k-jenkins-job / t1k-jenkins-unity), deleting jobs, aborting builds, managing
credentials/nodes/plugins, editing Jenkinsfiles, or triggering Release jobs.