Skip to content
Helmhive Helmhive Helmhive

Manage runners

Every runner has a control state that decides whether the scheduler may give it work. Changing it is server-authorized and audited.

Control states

Section titled “Control states”
State Behavior
Active Claims matching work.
Draining Finishes current work, claims nothing else, then becomes Disabled on its own.
Disabled Heartbeats but cannot claim jobs. Can be enabled again.
Revoked Blocked forever. Cannot reconnect or be re-enabled.

Actions

Section titled “Actions”
  • Drain (from Active) lets the runner finish its current job and then disables it. No confirmation is asked.
  • Disable (from Active or Draining) stops new assignments immediately without interrupting a job that is already running.
  • Enable (from Disabled) returns the runner to Active.
  • Revoke permanently blocks the identity and cancels its active work on the next heartbeat. Revocation cannot be undone, and reviewed evidence from jobs it already completed stays valid. Your operator should also remove the runner service and its provider state on the host.

Rotate a provider login

Section titled “Rotate a provider login”

Helmhive never holds the provider login, so rotation is a coordinated handoff rather than a secret replacement:

  1. Choose Rotate provider login and confirm Request rotation. The runner is disabled immediately and its row shows Provider login rotation required with the commands to run.
  2. Your operator signs out and back in to the provider on the runner host and verifies the login.
  3. Choose Mark credentials rotated and confirm. This records that the login was rotated and verified outside Helmhive. The runner stays disabled until you Enable it.

While a rotation is pending, Issue replacement token issues a rotation token instead of a registration token. Exchanging it replaces the runner’s own Helmhive credential, clears the pending rotation, and reactivates the runner.

Heartbeats and readiness

Section titled “Heartbeats and readiness”

A runner is Online when its provider login is authenticated and it has checked in within the last forty-five seconds by default; otherwise it is Needs attention or Offline. Available slots count only for runners that are Active, Online, and Authenticated. A heartbeat that reports a changed label set or an execution-environment fingerprint that no longer matches is rejected.

Section titled “Related”

Execution environments explains automatic environment upgrades, and Limits and defaults lists the timing values.