Jenkins

Changelog

1. 0.4.0

   Jenkins 0.4.0: every call says which controller it drives

   0.3 made the controller a Jenkins connection, but the plugin still took one of them, in a setting - so an organisation with a controller per team, or a release Jenkins beside the everyday one, could only ever reach one.

   All nine functions now take the connection as their first argument, jenkins: picked from a list in a workflow, passed by id from an agent. The two skills say so, and keep to one controller for every call about one build, because a job of the same name on another controller is another job. Their examples are now written the way an agent sends them - the tool's name and a JSON object.

   Coming from 0.3: the plugin's jenkins parameter is gone. A workflow calling any of these needs the new first argument set to the connection the parameter used to name. This needs a server that resolves a connection argument; on an older one the call says the connection never reached it rather than calling nowhere.

2. 0.3.0

   Jenkins 0.3.0: the controller to drive is a Jenkins connection

   Jenkins used to be configured on the plugin's own page: a url, a user and a token. That meant one controller per workspace, and its API token typed into a plugin setting rather than kept where a workspace keeps hosts.

   The plugin now brings a connection kind of its own, Jenkins. Add one with the controller's root as the URL and point the plugin's jenkins parameter at it: Basic auth with user:apiToken as the secret, or no auth for a Jenkins read anonymously. The crumb a build trigger needs is still fetched with the same credential.

   Coming from 0.2: the url, user and token parameters are gone. Make a Jenkins connection from them and point jenkins at it. This needs a server that hands a plugin's own kind of connection over with its address; on an older one the plugin says so rather than calling nowhere.

3. 0.2.0

   Jenkins 0.2.0: find the job, and read the test report a case at a time

   Two calls, for the questions asked either side of "why is it red".

   search finds a job by name wherever a folder has put it. Every word of the query has to appear somewhere in the full name or the description, in any order and whatever the capitals, so "deploy prod" finds platform/prod/deploy-api and leaves deploy-staging alone. Guessing at a path and getting a 404 twice costs more than looking, and "there is no such job" is a bad answer to give somebody whose job is called something slightly different.

   Jenkins has a search of its own and it is the wrong one to build on. /search/suggest answers display names — a job in a folder comes back as "folder » job", which is not a path anything can then be asked about — and it says nothing about whether what it found is passing. So the job tree is read instead, three levels of folders in one nested request, and the matching happens in the plugin because Jenkins offers nowhere to send it. Three levels is where real installations stop: team, product, branch. Deeper than that is not found rather than found slowly, and folder starts further in, which is also the answer on a controller too large to read in one go.

   testCases answers the shape of the run where testResults answers the shape of a failure: every case, what it cost, and how long it has been failing. Ordered by slowest unless told otherwise, which turns "the build takes eighteen minutes" into "four tests take eleven of them" — a thing somebody can act on, and one no amount of console log says, because a log records when things happened and not what they cost. failed is the failures, slowest first. name is for comparing two builds.

   flaky is the one worth knowing about: only the tests that have been failing for more than one build. That is age, which Jenkins counts and nothing else here can — 1 means this build broke it, 11 means eleven builds have been red and nobody looked. Telling today's breakage from the broken window that was already there is most of triage.

   Durations come back in milliseconds, converted. Jenkins times a build in milliseconds and a test case in seconds, in the same API, and says so nowhere; passing both through unchanged would be handing somebody a trap to fall into exactly once.

4. 0.1.0

   A Jenkins plugin, for the minute after a build goes red

   Which job, which build, what broke, and can it be run again. That question is answered today by somebody opening a browser tab, and the answer is nearly always one of four things — the job's state, a build's result, the failing tests, the last hundred lines of the log. So: jobs, job, build, buildLog, testResults, trigger and queueItem, all seven fronted to agents, with two skills beside them on triaging a failure and on what triggering actually does.

   The log is fetched by its tail rather than whole, and that is the piece worth knowing about. A console log runs to megabytes and everything handed to a plugin has to fit in a sandbox, so buildLog asks Jenkins how long the log is — progressiveText says so in a header and takes a byte offset — and pulls a window off the end of it. A 40 MB log costs forty kilobytes. Where the header does not come back, from an old controller or a proxy that drops it, the whole console is fetched and cut here instead: same answer, dearer. There is deliberately no call that answers a whole log.

   Two things Jenkins says that are not answers are translated. A job's status is a colour — blue is passing, red_anime is failing-and-building-now — and comes back here as a word and a boolean. And the links Jenkins writes point wherever its administrator said it lives, which on a great many instances is still localhost:8080, so every url answered is built from the url the plugin was configured with: the one address known to work, because the answer just came back from it.

   A job is named however somebody spelled it — deploy, platform/services/deploy, or a pasted link — and a url that names a build answers that build, whatever which said. Only the path is read out of a link and never the host, which is worth saying out loud: a link to a different Jenkins names a job on this one, or nothing at all.

   trigger answers a queue item rather than a build, because that is all Jenkins knows yet, and it fetches a CSRF crumb first. An API-token request has been exempt from CSRF since 2.96 so that GET usually buys nothing, but the instances where the exemption does not hold fail with a 403 and an HTML page behind it, which is the least debuggable answer Jenkins has. A crumb issuer that refuses is read as "CSRF is off", not as an error.

   The credential is an optional pair: user and token together, or neither for an instance read anonymously. One without the other is a thrown sentence rather than a bearer token Jenkins cannot read — it authenticates a token as somebody. No permission is asked for; the Basic credential is orknux.encoding, which is ungranted.

   The mark comes from simple-icons, so icons.mjs writes both variants. The root README gains the blurb and the count, and plugins.test.js gains jenkins in the sweep plus a test that watches the requests on their way out: that a folder path, a link and a plain name all arrive at job/a/job/b, that the log is asked for by an offset, and that a trigger sends the crumb it just fetched.