Skip to main content

Module api

Module api 

Source
Expand description

The daemon’s JSON API, version 1: the request and response types every client deserializes, and the principal a transport authenticates. Plain data only: no I/O, no Docker or GitHub types, no secrets but a Pairing’s one-time link, which its Debug leaves out.

Routes, all under the authenticated principal:

RouteBody
GET /v1/statusStatus
POST /v1/repositories/{owner}/{name}/pause?PauseQueryPaused; 409 Busy while it runs a job
POST /v1/repositories/{owner}/{name}/resumenone, 204
POST /v1/repositories/pause?PauseQueryPaused; 409 Busy while any runs a job, pausing none
POST /v1/repositories/resumenone, 204: every repository resumed
POST /v1/profiles/{name}/reseednone, 202; 409 while it reseeds; cache.reseeded when done
POST /v1/caches/{name}/cleannone, 204; 409 Busy while a runner uses it
GET /v1/configConfigFile
POST /v1/config/checkTOML in, ConfigCheck
PUT /v1/configTOML in, ConfigCheck; 422 ConfigCheck when invalid
GET /v1/doctorDoctor; 503 ErrorResponse while no run has finished
GET /v1/attentionAttention; 404 from a daemon before 0.2
POST /v1/shutdownShutdownRequest in, 202 ShutdownAnswer
GET /v1/dashboardDashboard
POST /v1/dashboard/sign-outnone, 204
POST /v1/dashboard/pairings?PairingQueryPairings; 409 when the dashboard is off or has no [web] origins
GET /v1/jobs?JobQueryJobPage
GET /v1/jobs/{id}Job
GET /v1/jobs/{id}/samplesSampleSeries
GET /v1/jobs/{id}/logs?LogQuerytext/plain, one line per log line
GET /v1/host/samples?HostSampleQueryHostSamples
GET /v1/stats?StatsQueryStats
GET /v1/activity?ActivityQueryActivity
GET /v1/sizing?SizingQuerySizing
GET /v1/insights?InsightsQueryInsights
GET /v1/digestDigest
GET /v1/savingsSavings
POST /v1/notify/test?NotifyTestQueryNotifyTest; 404 without [notify] targets or with no such one
GET /v1/cachesCaches
GET /v1/caches/history?CacheHistoryQueryCacheHistory
GET /v1/events?EventQuerytext/event-stream of EventEnvelope
GET /v1/recordsRecords
DELETE /v1/records/{job}RemovedRecords; 409 while a shell is open in it
DELETE /v1/records?RemoveRecordsQueryRemovedRecords; records with an open shell stay
POST /v1/records/{job}/shell?ShellQueryUpgrade: SHELL_PROTOCOL, 101, then the shell’s terminal; 409 when the budget is full

Errors carry an ErrorResponse.

Structs§

ActionPreview
The 409 a request without force, or with a confirm for something else, gets: what the action would do, said before anything is sent to GitHub. Has the message of an ErrorResponse, so a client that reads only that still gets it.
ActionQuery
POST /v1/jobs/{id}/cancel and POST /v1/jobs/{id}/rerun query parameters.
ActionResult
POST /v1/jobs/{id}/cancel and POST /v1/jobs/{id}/rerun once GitHub was asked: how it took it. The job’s record is not changed: GitHub’s listings bring the run’s new state and a re-run’s new jobs.
ActionTarget
What an action acts on: the job as the history records it, and the run’s attempt as GitHub said it.
Activity
GET /v1/activity: every job runnerd’s runners started or finished in a window, by when that happened rather than when the job was queued, so a job that waited or ran long counts in the window it started or ended in.
ActivityQuery
GET /v1/activity query parameters.
Admission
How a job’s runner was admitted.
Attention
GET /v1/attention: what needs attention now, most urgent first.
AttentionItem
One thing that needs attention.
AutoPlan
What auto sizing will do: its rules, the changes its next look would make as the history and config are now, and the profiles a recent change holds.
Budget
The memory budget runners and the mirror share, in bytes.
BudgetParts
The budget as a bar draws it, from Status::budget_parts.
BuildCacheActivity
What the build cache did for one job, from BuildCacheCounts::activity.
BuildCacheCounts
What the shared build cache served one runner and took from it (ADR 0052), counted by the cache itself.
BuildCacheStats
The shared build cache (ADR 0052): its size now, and what it served the jobs of the last 7 days.
Busy
The body of a 409 refused because runners use what the request would change. Has the message of an ErrorResponse, so a client that reads only that still gets it.
CacheHistory
GET /v1/caches/history: every measurement, oldest first.
CacheHistoryQuery
GET /v1/caches/history query parameters.
CacheLimit
A cache volume against its limit, from CacheVolume::limit_status.
CacheSize
One volume’s size at one measurement.
CacheVolume
One cache volume and its size.
Caches
GET /v1/caches: every cache volume of the configured profiles, as last measured. Docker measures volumes slowly, so runnerd measures them at start and whenever no runner runs after jobs ended.
ChartLine
A line across a job’s memory or CPU chart.
ChartLines
The lines across a job’s memory and CPU charts, from Job::chart_lines.
Check
One thing the host needs to run runners. Its Display is the line runnerd doctor prints.
CheckCount
How many checks carry one CheckStatus::label.
ClosedPart
Room past the bar’s blocks that no runner may start in.
Commits
btrfs’s transaction commits over the stretches the daemon read them.
CompareQuery
GET /v1/jobs/{id}/compare query parameters.
ComparedSteps
A job’s steps as far as a comparison reads them: the first COMPARE_STEPS_MAX in order, while their names, each cut to its first 800 bytes, add up to at most COMPARE_STEP_BYTES. Steps pair by these names.
ConfigCheck
POST /v1/config/check and PUT /v1/config: what runnerd check-config prints for a config. PUT refuses an invalid one with 422 and this body, which has an ErrorResponse’s message.
ConfigFile
GET /v1/config: the config the daemon runs with. Parse text with config::Config::parse for its fields.
Counted
The growth count (ADR 0130): what the runners use, and the room kept for what they may still grow by.
CpuAdmission
What a runner reserved of the CPU budget. CPU in millicores, times in seconds.
CpuBudget
The CPU budget runners share, in millicores.
Dashboard
GET /v1/dashboard: the dashboard’s [web] settings, as the daemon read them when it started.
Delivery
What one target did with a message.
Digest
GET /v1/digest: the last 24 hours.
DiskWrites
The disk-writes section of Insights: what the jobs that ended in the window wrote, the workflows and jobs that wrote most, and what the drive wrote while the daemon read it.
DiskWritten
What a job’s runner container wrote to the disks under Docker’s root, from its cgroup’s io.stat: what its processes, the Docker Engine inside it and that engine’s containers sent the disks from the job’s start to the container’s last read. Bytes still in the page cache then go to the disk after, on the runner slice’s account.
Doctor
GET /v1/doctor: what runnerd doctor checks, for the config the daemon runs with.
DoctorQuery
GET /v1/doctor query parameters.
DoctorSummary
The doctor’s checks laid out for a reader, from Doctor::summary.
DriveShare
One owner’s share of what the drive wrote.
DriveShares
Whose the drive’s bytes were, over the stretches the daemon read the runner slice, or over all it read the drive when it never read the slice: a stretch that missed one figure leaves the others’ shares be.
DriveWrites
What the disks under Docker’s root wrote while the daemon read them in a window: from /sys/class/block, the runner slice’s io.stat, which keeps what its containers wrote after they are gone, the daemon’s own /proc/self/io, and btrfs’s commit count.
ErrorResponse
The body of every error response.
EventEnvelope
One event as GET /v1/events sends it: the SSE data field. The SSE event field is event.kind() and the SSE id field is id.
EventQuery
GET /v1/events query parameters. Resume with the Last-Event-ID header.
FailureSummary
What a failed job’s log says of its failure. Each part is absent where the evidence is.
Figure
One of the overview’s four health figures, worded once for every client: the web dashboard lays them out as tiles, the TUI on one line.
FigureDelta
One figure of this job beside the baseline’s.
FreePart
What the bar leaves free past every block, less what the host holds back.
Gap
A stretch of a lane without a job.
Health
Whether CI keeps up now, from Status::health.
HeldPart
Memory the budget holds for something other than a slot.
Holder
A program outside the slice and the memory its processes hold.
HostBudget
What the host’s memory leaves the runners (ADR 0055). New runners fit in the lower of MemoryMax and limit; running ones are never stopped for it.
HostCredit
What the host’s limit takes off the plain count (ADR 0108): Budget::memory_in_use less bytes is what it counts, used of that is what the runners use, and the rest is room kept for what runs to grow into.
HostFigure
One figure of the host’s reading, as Budget::host_figures gives it: Host available 23G of 64G.
HostHazard
What the host’s memory came to while CI ran over a window, from the readings the budget’s events stored (ADR 0108): how long MemAvailable stood under each line, the least it and SwapFree fell to, and how much of that came while the host’s limit took a credit. Times are seconds, sizes bytes.
HostMemory
The host’s memory at one moment, beside the slice’s: what admission fits new runners in besides MemoryMax (ADR 0055). Read every few seconds; not kept in the history.
HostSample
One sample of the whole slice runners run in.
HostSampleQuery
GET /v1/host/samples query parameters.
HostSamples
GET /v1/host/samples: the slice’s use over time, oldest first.
HostSpan
How long the host stood under a line while CI ran, in seconds.
Insight
One thing the history says, about one job or one repository.
InsightFigure
The number an insight is about, short, for a figure beside its sentence: 6m 10s over from 4m 40s.
Insights
GET /v1/insights: what the history says about the window.
InsightsHeading
What the insights page says over its list, as Insights::heading words it: 5 insights, 4 warnings, from the last 14 days, 1 insight from the last 14 days, no insights from the last 14 days. A client may set the figure apart; together, as its Display writes them, they read as one line.
InsightsQuery
GET /v1/insights query parameters.
Job
GET /v1/jobs/{id}: a job with its steps.
JobComparison
GET /v1/jobs/{id}/compare: a job beside its baseline.
JobList
GET /v1/jobs: one page of jobs (ADR 0135). A JobPage with fields more, so a client that reads a JobPage reads it too, and one that reads a JobList from an older daemon finds them absent.
JobMetrics
What a job used, over the samples taken while it ran (every few seconds). None until a sample exists.
JobOrder
An order a list of jobs can be read in: what it is sorted by, and which way.
JobPage
One page of jobs, as GET /v1/jobs answered before it searched and sorted: what JobList holds.
JobQuery
GET /v1/jobs query parameters. Jobs come newest first (by ID, which grows with time), or by sort (ADR 0135). JobQuery::check says which queries the daemon refuses.
JobRunner
The runner a job ran on.
JobSizing
The jobs of one name in one workflow of one repository.
JobSummary
A job without its steps: what lists and events carry.
JobTitle
A job’s name as every client writes it, in parts for a page that sets the workflow apart.
JobWrites
What the jobs that ended in a window wrote, each its runner container’s DiskWritten.
LabelledFigure
One figure of a group: Median a job 120M, or Lookups hit, 7 days 75% of 400.
Lane
One slot as it was: the profile and slot its runners had when they ran, whatever the config holds now.
Limit
One resource’s limit for a job’s container.
Limits
What a job’s container may use, from Job::limits.
LineRange
Lines from from up to, not including, to.
LineRead
Stored lines to read: up to limit from line from (past a gap pruning left, too), each cut to its first prefix bytes, stopping after the line that brings the text read to bytes.
ListingFailure
Why runnerd cannot list a repository’s queued jobs (ADR 0132): what class of failure GitHub’s answer was, never its text. The engine keeps it until a listing answers or a reload removes the repository; a restart forgets it.
LogGroup
A foldable group of lines, from its ##[group] to its ##[endgroup] line.
LogLinesQuery
GET /v1/jobs/{id}/log/lines query parameters. The response is application/x-ndjson: one StyledLine per line, in order.
LogMark
An error or warning line.
LogNeedle
A query, ready to find.
LogOutline
GET /v1/jobs/{id}/log/outline: a job’s log as structure.
LogQuery
GET /v1/jobs/{id}/logs query parameters. The response is text/plain, one log line per line.
LogSearch
GET /v1/jobs/{id}/log/search: one page of the lines whose message holds a query.
LogSearchQuery
GET /v1/jobs/{id}/log/search query parameters.
LogSummary
A job’s stored log.
LongWait
A job that waited.
MemoryHold
A bound of the config holding a profile’s memory away from what its jobs need: the config check refuses a profile past it, so the advice goes no further than bound, and auto sizing writes it as is (ADR 0086, 0088). Under a raise it says only that no raise past bound is possible, not that the jobs fit.
Milestone
A moment of a job’s life.
Need
What a set of jobs needs, as the advice sizes for it, from Sizing::need.
Notification
What a webhook target is posted, as JSON; an ntfy target gets its title, message, priority and link.
NotifyTest
POST /v1/notify/test: what each target did with a test message.
NotifyTestQuery
POST /v1/notify/test query parameters.
Outcome
A job’s or a step’s outcome: its word and what it means.
OutlineParts
What the store keeps of a job’s outline: its saved state, None for a log no outline was kept of, and its groups, marks and section lines, each by line.
Outliner
Builds a job’s outline a line at a time. The store resumes one from its saved state for each batch of lines and saves it after, in the transaction that stores the lines.
Pairing
A link that signs one device in to the dashboard on origin, and nowhere else, within lifetime.
PairingQuery
POST /v1/dashboard/pairings: which of [web] origins to make a link for.
Pairings
POST /v1/dashboard/pairings: fresh one-time links that sign a device in to the dashboard.
PauseQuery
POST /v1/repositories/{owner}/{name}/pause and POST /v1/repositories/pause query parameters.
Paused
POST /v1/repositories/{owner}/{name}/pause and POST /v1/repositories/pause: the repository, or every one, is paused, and stays paused when the daemon restarts.
Peaks
The peaks of a set of jobs, each the highest of its samples.
Phase
A stretch of a job’s life.
PoolStatus
One of a repository’s pools: its runners in one profile.
Pooled
The count the budgets go by while pooling takes something off Budget::memory_in_use (ADR 0099).
Pressure
One line of a pressure stall file, in hundredths of a percent: 250 is 2.5% of the time.
PreviewFacts
The facts of an ActionPreview: what the route found for the job.
PricedRun
A job of the history as pricing reads it: one a runner of this machine took, completed or lost. Times are milliseconds.
PricedRunner
A window’s jobs priced at one runner.
Pricing
The runner each profile’s jobs are priced at, from the config running now.
PricingHistory
What pricing reads of the history.
ProfileSizing
One profile: its limits now, its jobs’ peaks and waits, and the advice.
ProfileStatus
A runner profile and what runs in its slots.
QueuedJob
A queued job runners of this daemon can take, as GitHub listed it at the last poll.
Reading
A figure and the words that follow it, such as 8G and of 24G reserved in runnerd.slice, for a client that sets the figure apart.
Record
One record: the runner of a failed job as the job left it.
RecordLimits
The limits on records, from [records] in the config.
RecordNote
What the job history keeps about a failed job’s record, after the record is gone too.
Records
GET /v1/records: every record, oldest first, and the limits they are kept within.
RemoveRecordsQuery
DELETE /v1/records query parameters: exactly one of them.
RemovedRecords
DELETE /v1/records…: what was removed.
ReplaceQuery
PUT /v1/config query parameters.
RepositoryStatus
A configured repository and its queue.
RepositoryWaits
A repository’s waits this week against the week before.
Resize
A profile’s new memory, slots and, when auto sizing changed them, cpus.
Run
A run of a line’s text in one style.
RunComparison
A job’s latest runs and what they say together, from Job::compare.
RunLink
One run of a job, to open in the history or on GitHub.
RunnerFailure
A runner that could not be registered or started (runner.failed).
RunnerSpan
A runner container in a slot: up from its start to its removal, with a job or without, as a warm runner waits. Its life is not its job’s run.
RunnerStatus
A runner registered for one job, in its container.
RunningJob
A runner of this daemon that holds a slot, and the job it runs, if it took one.
Sample
One sample of a container’s use.
SampleSeries
GET /v1/jobs/{id}/samples: what the job’s container used over time, from its start to its removal. Samples older than history.samples are deleted; the job’s metrics stay.
SampleUsage
What a container used over a stretch of its run, from SampleSeries::usage_between.
SavedOutline
What the store keeps of an outline between batches of lines: one row per job.
SavedWindow
The jobs of one window and what they would have cost.
Savings
GET /v1/savings: what this machine’s job minutes would have cost on GitHub-hosted runners.
Search
One page of a search, fed the log in the batches it asks for: while let Some(read) = search.wants() { search.read(lines(read)) }, then Search::finish.
SeedMemory
A seed container’s memory cap: its profile’s limit when the reseed started, or, for a requested reseed whose profile drained, the room it holds until it starts.
ShellMemory
A shell container’s memory cap: its record’s profile’s limit when the shell opened.
ShellQuery
POST /v1/records/{job}/shell query parameters.
ShutdownAnswer
What POST /v1/shutdown answers: how the daemon stops now, which a stop asked for earlier may have made more urgent than the request.
ShutdownRequest
POST /v1/shutdown.
Sizing
GET /v1/sizing: what the job history says each configured profile needs.
SizingChange
A profile’s memory and slots as auto sizing changed them in the config file.
SizingHold
A profile auto sizing changes nothing in before until, and lowers nothing in before lower_until.
SizingQuery
GET /v1/sizing query parameters.
SizingRefused
A raise of a profile’s cpus or slots its jobs ask for that auto sizing cannot make, as when it does not fit the CPU budget or Docker’s disk.
SizingRevert
A lowering of a profile’s memory by auto sizing that went too far, which the advice takes back (ADR 0070).
SlotForm
One way to read a slot’s block, from SlotReading::forms.
SlotKey
A profile’s slot, as a runner had it.
SlotPart
A slot’s block of the budget.
SlotReading
What a slot’s block reads under its name, from Status::slot_reading: what its job uses of what the block is, or without a sample of its job, what the slot is doing and the block’s size.
SlotStatus
One slot of a profile: room for one job.
SlotTimeline
GET /v1/timeline: what each slot ran over a window.
SlottedBar
A job’s bar and the slot its runner had.
SlottedRunner
A runner container’s span and its slot.
Span
A stretch of time, in seconds since the epoch: from from up to to.
Spread
Percentiles of a set of values, by nearest rank: each is one of the values, and with fewer than 100 values p99 is the largest.
Started
A job that started: when, and how long it had waited since it was queued.
Starts
A profile’s jobs by whether their runner was already up when GitHub queued them (ADR 0050).
Stats
GET /v1/stats: finished jobs per repository and time bucket, for trends. Sums, so clients can average.
StatsQuery
GET /v1/stats query parameters.
StatsRow
The finished jobs of one repository in one bucket.
StatsSummary
Finished jobs summed over a time, every repository of the query together, from Stats::daily.
Status
GET /v1/status: what the daemon serves and runs right now.
Step
One step of a job, as GitHub reports it.
StepDelta
One step beside the baseline’s step of the same name.
StepLines
A stored step and its lines.
StepUsage
What a step’s samples say, as the store reads them over its window: the samples after its start up to its end.
StoredLine
A stored line as a LineRead gives it: its number, and its text, cut to the bytes the read asked for.
StoredLog
What the store has of a job’s log besides its outline.
StyledLine
One stored line of a job’s log, styled.
Swap
A host’s swap at one reading: zram and zswap’s device included, as /proc/meminfo counts it.
Timeline
A job’s phases, in the order they happen. A runner’s container starts before GitHub gives it a job.
TimelineBar
One job on a timeline.
TimelineQuery
GET /v1/timeline query parameters.
TimelineRows
What the store reads for a timeline, before SlotTimeline::assemble lays it out.
Toned
Text and what it means, for a client to colour.
Total
One figure of what a job used, worded for every client.
Usd
An amount in US dollars, as whole micro-dollars, so no float carries money.
WaitFigure
One of a repository’s wait figures: its label, such as Warm median, and its value, – without jobs to take it over.
WaitSpread
How long some jobs waited.
WeekWaits
The waits of the jobs that started in a week, from queued to started, leaving out the time before the history’s start and the time no runnerd ran (ADR 0081).
WriteSection
A part of the disk-writes section, under its title.
WriteTop
A workflow, or a job, and what its jobs in the window wrote.

Enums§

ActionAnswer
What GitHub answered an action, as runnerd classifies it.
ActionOutcome
How GitHub took an action.
ActionRefusal
What class of refusal an ActionOutcome::Refused was. Never GitHub’s own words.
AdmissionPolicy
[host] admission, as a job’s record and the budget name it.
Advice
What to set a profile’s memory and slots to. memory is the largest sampled peak plus the margin, or plus PAGE_CACHE_ROOM when that is more, rounded up to 256M: the cap kills a job that goes over it, so it is sized for the heaviest run, not a percentile.
AttentionKind
Where an attention item comes from.
AutoNote
What auto sizing does about a job near its cap.
BarEnd
How a bar or a runner’s span ends.
Baseline
What a job is compared with.
BaselineRead
The baseline as the store found it.
Basis
What a runner reserved goes by, in the order measured admission falls back.
Bucket
How GET /v1/stats groups jobs in time.
CacheKind
What a cache volume holds.
ChangeKind
How a figure changed from the baseline.
ChartLineKind
What a line across a job’s chart stands for.
CheckStatus
How a Check came out.
ClosedKind
What closes room past the bar’s blocks.
Color
A colour a run of text was printed in, from the closed set a log is drawn with. Bright and dark shades are one colour; white, default and 256-colour or RGB colours beyond the first 16 have none.
Column
A column of a table of jobs or of records, as the history, runnerctl jobs and the records name it.
CountBrake
Why the growth count rests (ADR 0130).
DoctorState
How current the daemon’s doctor checks are (ADR 0132). Times are seconds since the Unix epoch.
Event
Everything that happens, tagged by type.
Feature
What a client reads from the daemon that a runnerd older than the client may not serve: a route it lacks, which the client says is not supported rather than empty (ClientError::is_unsupported, JobList::understood).
FigureKind
What a figure measures.
Fix
What clears an attention item. A client reads a fix of a kind or view it does not know as none (AttentionItem::fix).
GapKind
What a lane’s stretch without a job means.
HealthKind
Which health figure a Figure is.
HeldKind
What holds a part of the budget beside the slots.
HoldCause
What failed, that holds a repository’s runners back for a while.
InsightKind
What an insight is, tagged by kind.
JobAction
What an owner asks GitHub to do with a job.
JobActions
Whether a daemon cancels and re-runs jobs, as GET /v1/status says.
JobPeak
Which of a job’s own peaks Basis::Job goes by.
JobRange
How far back a list of jobs reaches, by when GitHub queued them, as every client offers it.
JobSort
What a sorted list of jobs is sorted by.
JobState
Where a job is in its life, as this daemon saw it.
LimitSource
Where a job’s limit comes from.
LineKind
What a line is, from the command the runner prefixed it with.
ListingProblem
What a failed listing ran into.
LogEvidence
How much of a job’s log there is to read, in order of precedence.
MarkKind
What a marked line says.
Measure
Whether a job’s DiskWritten is all it wrote. A job no reading measured has no figure at all.
MemoryBound
Which bound of the config holds a profile’s memory.
NotifyEvent
What a notification target is sent, and the events [notify] targets choose from.
OutcomeKind
What kind of outcome a job’s or a step’s is, for each client to colour as it colours that meaning.
OutlineChange
What a line changes in the outline, for the store to keep.
Period
Which window a SavedWindow covers.
PhaseKind
The phases of a job, in the order they happen.
Principal
Who sent a request, as the transport authenticated it. Handlers get it from one place, so a new transport only has to produce one.
Priority
How urgent a notification is, as ntfy ranks it.
ProfilePlan
What auto sizing does next with one profile at a given time, from AutoPlan::profile_plan.
RecordFilter
JobQuery::record: jobs by what became of their record.
RecordMark
What became of a failed job’s record, as a list marks it (JobSummary::record_mark): what the history notes, which RecordNote::state reads in full on the job’s page. Docker’s images are the inventory (GET /v1/records); a record removed outside runnerd reads removed once runnerd lists the images and finds it gone.
RecordRemoval
Why a record was removed.
RecordState
What became of a failed job’s record, from RecordNote::state.
RevertCause
What showed a lowering went too far.
RunSeen
The run as GitHub said it when the preview was made.
Section
A page inside a View of several, as every client names it.
Severity
How much an insight matters.
ShareOwner
Whose a share of what the drive wrote was.
Sku
A GitHub-hosted Linux runner, by the billing SKU GitHub’s pricing page and usage report name it with, as a profile’s priced_as takes it. Windows, macOS and GPU runners are not here: runnerd runs Linux containers.
SlotState
What a slot is doing, from Status::slot_state.
SortOrder
Which way a sorted list goes.
StepLog
Which lines a step printed, as far as the log tells.
StepMatch
How a step of one job was paired with the other’s.
Stopping
How a stopping daemon treats running jobs (ADR 0091).
Subject
What an attention item is about, for a client to link.
Superseded
Why a request that came with a confirmation got a new preview instead, and nothing was sent.
Tone
What a shown fact means for the reader. On the wire in kebab-case, as an attention item carries it.
Unavailable
Why a job has no baseline.
UnknownCause
Why runnerd cannot tell what GitHub did. Not on the wire: the result’s message words it.
View
A group of pages of the web dashboard, a group of views of runnerctl tui, in the order every client lists them: what runs now, the jobs, what the history says, the machine’s room and the daemon’s settings (ADR 0132).
Visibility
A repository’s visibility as GitHub gives it.
WaitKind
What a Waiting reason waits on, which clients draw it by.
Waiting
Why a queued job has no runner of its own yet. Jobs are served oldest first; each takes the first of these that holds for it.

Constants§

ACTIONS_CACHE
What doctor and the Caches page name GitHub Actions’ cache.
ATTENTION_MAX
The most items an Attention lists; the rest are counted in omitted.
BUILD_CACHE_TOOLS
The tools whose caches the build cache serves, as clients name them over its counts (ADR 0052, 0083). The image points each at it but Nx, which fails its run when the cache does not answer.
COMPARE_STEPS_MAX
The most steps of each job a comparison reads, in order of their numbers.
COMPARE_STEP_BYTES
The most bytes of step names of each job a comparison reads, each name read from its first 800 bytes, the most a title is read from; a first step is read whatever its name’s length.
CONFIRM_SECS
How long a preview’s confirmation can be sent back, in seconds.
GRANULE
Advice rounds memory up to a multiple of this: 256M.
GROWTH_WINDOW
How far back the growth count’s brake compares what runs uses: 10 minutes (ADR 0130, admission::growth::GROWTH_WINDOW).
INSIGHT_DAYS
The window GET /v1/insights reads by default, in days.
INSIGHT_DAYS_MAX
The longest window GET /v1/insights reads, in days.
JOBS_HEADING
What a count of jobs, or a list of them on a page, is headed: the history’s figures, a profile’s facts, the waits table. Not the name of View::Jobs, though it reads the same.
JOBS_PAGE_BYTES
The text a page holds at most, in bytes, counted over each job’s repository, workflow, name, branch, URL and labels as the list shows them (row_bytes): a page ends before the job that would pass it. A job’s text is cut to JOB_TEXT_MAX and JOB_LABELS_MAX, so even a page’s first job is far below it.
JOBS_PAGE_DEFAULT
Jobs a page holds unless limit says otherwise.
JOBS_PAGE_MAX
Jobs a page holds at most.
JOB_ACTIONS_CHECK
The doctor check that says whether the token can cancel and re-run jobs. Advisory: the attention list leaves it out whatever its status, since only GitHub’s answer to a real request says for sure.
JOB_LABELS_MAX
The most bytes of a job’s labels, as stored (a JSON array of strings), a list shows; past them it shows none, and the job is in JobList::shortened.
JOB_SEARCH_MAX
The longest search, JobQuery::q, in bytes.
JOB_TEXT_MAX
The most bytes of a job’s repository, workflow, name, branch and URL a list shows, each, to the last whole character; past them, the text is cut and the job is in JobList::shortened.
LINES_DEFAULT
GET /v1/jobs/{id}/log/lines: lines a page holds unless limit says otherwise.
LINES_MAX
GET /v1/jobs/{id}/log/lines: lines a page holds at most.
LINE_BYTES_MAX
The most of a stored line’s text a styled line shows, in bytes; the rest is counted in StyledLine::omitted.
NOT_SUPPORTED
What a client says where an older daemon lacks a route or a field it reads: never an empty answer in its place.
PAGE_CACHE_ROOM
What a cap keeps at least over the largest peak, for page cache: 1G. Peaks leave page cache out, and a container whose memory past them leaves the kernel less than about 500M of page cache to reclaim at its cap reclaims badly, which throttles its sockets and slows its downloads (ADR 0055).
RECORDS_NEAR_FULL
The share of [records] max_total past which the records are near it, in percent: new ones then remove the oldest to fit.
RUNS_MAX
The most runs a styled line holds; the text after them is counted in StyledLine::omitted.
SAMPLE_INTERVAL
Seconds between two samples of a running job’s container. Clients without a Sizing or SampleSeries that says so, such as a job’s figures in runnerctl, word their sampling caveat from it.
SEARCH_QUERY_MAX
The longest query, in bytes.
SELF_HOSTED_RATE
What a minute of a job costs on this machine, in micro-dollars, subtracted from each hosted rate. GitHub postponed its $0.002 a minute charge for self-hosted runners; this is the one place to set it if it comes back.
SHELL_PROTOCOL
The Upgrade protocol of POST /v1/records/{job}/shell: after 101 Switching Protocols the connection carries the shell’s terminal, raw bytes both ways.
SIBLINGS_MAX
The most other jobs of the run a confirmation names.
SLOT_DISK
The least share of Docker’s disk, in bytes, auto sizing leaves each slot when it adds slots under measured admission: 2G. Every slot’s Docker store shares a quarter of Docker’s disk; at a 2G share the stores measured on a busy host keep their images between jobs, and at 1G, the least a share can be, every store over 1G is emptied after each job. What a store keeps does not set it: a store fills the share it gets (ADR 0090).
TIMELINE_BARS_MAX
The most job bars a timeline holds, and the most runner spans: past it, the latest are kept and SlotTimeline::cut_before says from when.
TIMELINE_DEFAULT
The window a timeline shows unless since says otherwise: the last 24 hours, in seconds.
TIMELINE_WINDOW_MAX
The longest window a timeline shows, in seconds: 7 days, the samples the history keeps by default.

Functions§

actions_cache_place
Where jobs’ GitHub Actions cache is (ADR 0082), with [caches.build] actions_cache at served.
actions_in_flight
The 409 while another action on the same run is being sent to GitHub, or one with the same confirmation.
actions_no_run
The 422 for a job whose run the history did not record.
actions_not_configured
The 403 for a job of a repository the config no longer has.
actions_off
What both routes answer, 403, while [github] job_actions is off.
ago
How long ago at was: just now under ten seconds, then as duration writes it, 1h 05m ago.
attention_items
Everything that needs attention now, most urgent first: from status, the doctor’s last run as doctor says it, and insights when they could be read, at now (seconds since the Unix epoch). Each item stands on evidence that holds now; a source without it is left out, and doctor checks that are not current are one item saying so.
billed_minutes
How many minutes GitHub bills a job that ran from started to finished (ms): each partial minute rounded up, and at least one.
cores
Millicores as a number of CPUs to a tenth, rounded up: 2.5, 32.
cores_used
Millicores in use as cores, to a hundredth rounded up so use never reads as none: 0.25, 1.5, 12, 0.01.
cpu_time
CPU time given in milliseconds: 4.6s to a tenth under a minute, then as duration writes it.
cpus
Millicores as 2.5 CPUs or 1 CPU, to a tenth rounded up.
duration
Seconds as a stopwatch writes them, its width holding as it counts: 45s, 1m 12s, 2h 05m, 3d 4h.
force_pause_consequence
What forcing a pause does to jobs running jobs: cancels its run on GitHub and removes its runner, or for several, cancels their runs on GitHub and removes their runners.
host_margin
The plain margin MemAvailable keeps beside the runners on a host with total memory: the larger of MARGIN_MIN and total / MARGIN_SHARE (ADR 0055).
in_cores
Millicores in use as cores_used writes them, with the unit: 1.5 cores, 1 core.
job_title
workflow / job, or the job’s name alone; for a job whose name the daemon does not know yet, as for one its runner took before the daemon saw it queued, job <id>, or a job without an ID.
need
What a set of jobs whose largest sampled peak is peak needs, with margin percent: the peak plus the margin, or plus PAGE_CACHE_ROOM when that is more, rounded up to GRANULE. The largest, not a percentile: the cap kills a job that goes over it, so a cap below a peak a job reached kills it again.
percent
Hundredths of a percent as a percentage: 1.5%, 12%.
period
A setting’s length in words, as a config’s periods read: 5 minutes, 24 hours, 90 s.
reads_since
From when, in milliseconds, Savings::of reads the history at now (ms): the earlier of the month’s start and 30 days before.
records_check
The doctor’s records check for records taking bytes of [records] max_total: a warning with what to run when they are near it (records_near_full), else how much they take.
records_near_full
Whether records taking bytes are near max_total (RECORDS_NEAR_FULL).
reseed_requested
A reseed of profile the daemon accepted: jvm: reseed requested; it runs once the profile's slots are free.
reseeded
A reseed of profile done, as cache.reseeded reports it: jvm: reseeded or jvm: reseed failed: ….
row_bytes
The bytes of a job’s text the page budget counts, as the store counts them in its columns.
sampled_note
The caveat on a sampled peak, as every client words it: memory peaks are sampled every 2 s; spikes shorter than that do not show.