Skip to content

119. Signal GitHub Actions events to a running cycle ​

Date: 2026-11-02

Status ​

Accepted

This ADR partially supersedes one sentence of ADR 0144: "The bound process never polls the platform's pending-work list." On GitHub Actions, the invocation layer inside a bound fullsend run process may list its shim workflow's run records, which include the queued pending execution, as a change signal. The read never owns or consumes pending work; every other ADR 0144 rule stays current, including "Wake delivery alone never consumes pending work".

Context ​

ADR 0117 (proposed) steers a running cycle when a notification for its serialization key arrives while its sandbox runs. On GitHub Actions, that notification often never arrives:

  • No inbound path. GitHub Actions cannot deliver input to a running job.
  • No listener. ADR 0144 opens a wake listener only where the platform provides authenticated cross-worker traffic, which GitHub Actions does not.
  • Event-only harnesses. A harness without entity sources has no bound timer that re-reads the entity. Its only follow-up is the queued platform execution, which starts after the current job ends.

Every event that reaches a harness on GitHub Actions fires the repository's shim workflow. The resulting run records are a server-side log of what happened since the current run started, and Fullsend's forge client can already list a workflow's runs since a given time.

This ADR aims to give a running cycle on GitHub Actions a change signal without moving pending-work ownership into the bound process.

Options ​

OptionWhy not chosen
Platform pushes input into the running jobGitHub Actions has no such API
Poll forge events with input drivers and cursorsNeeds a driver, a race-safe cursor, and normalization per forge, as ADR 0106 noted
A courier job or relay serviceA new component to deploy, credential, and keep available
Rely on the bound timer's entity re-readWorks for entity-source harnesses only; event-only harnesses have no timer check
List the shim workflow's run records in the invocation layer (chosen)—

Decision ​

We adopt the shim workflow's run records, listed by the invocation layer inside a bound fullsend run, to signal a running cycle on GitHub Actions that its entity changed.

Each relevant new record becomes an in-memory wake signal for that cycle.

Where the read lives ​

  • The event source is part of the invocation layer, the component that owns the ADR 0106 serialization scope and the newest-pending slot in ADR 0144. It is not part of the bound timer and does not change the timer's rules.
  • It delivers an in-memory wake signal, the "trusted components in one process" path in ADR 0144.

What the signal does and does not do ​

The signalDoes
Prompts a steer attempt for the running sandbox (ADR 0117)Yes
Makes a check due for an entity-source harnessYes
Fills or takes the newest-pending slot as an eventNo. A run record is not a verified event payload
Consumes, claims, cancels, or dispatches pending workNo. The queued workflow run stays the ADR 0106 pending execution
Carries authority for admission, CEL evaluation, or sandbox executionNo. It is a scheduling hint only

Which records count ​

A run record is a candidate when all of these hold:

  • it belongs to the same repository and the same shim workflow file;
  • it was created at or after the current fullsend run call started;
  • its run-name names the same canonical entity; and
  • its triggering actor is not the App identity of the running harness itself.

Runs triggered by other registered agents still count: a review submitted or a handoff label added by another agent is an update the running cycle needs (ADR 0107 allows these bot-to-bot signals). Excluding only the running harness's own identity stops its status writes from waking itself; whether any update reaches the agent is decided by fresh admission (ADR 0117, proposed), not here.

The match does not depend on which jobs the run contains, so legacy routed runs and CEL-routed runs signal alike. A false match costs one steer attempt that admits nothing new, and it makes a check due. For an entity-source harness whose CEL stays true, that check can start another sandbox cycle; Fullsend adds no handled-state gate (ADR 0144), so avoiding a redundant cycle is the responsibility of the harness CEL or pre-script.

Cadence and limits ​

  • Listing repeats at a configured interval and once at the end of each turn, when a steer is cheapest.
  • Each listing uses a host-held credential with actions: read that never reaches the sandbox. The bound process holds no such credential today: the agent roles' App tokens (except the retro role's) carry no actions permission, and the job's workflow token is kept after the mint only as the provider-only credential of ADR 0114. This ADR does not widen ADR 0114. Until a listing credential is supplied, or whenever it cannot read Actions runs, the event source declines and the cycle runs without it.
  • The candidate set is re-derived from the call's start time on each listing, so no cursor is persisted; an in-memory set of records already seen prevents duplicate signals.

Workflow change ​

The shim workflows set a run-name that names the canonical entity. Runs for issue_comment and issues events carry no pull request list, so without a run-name the record cannot be tied to an entity.

Forge scope ​

  • GitHub: GitHub Actions only.
  • GitLab and Forgejo: not supported for this signal. It reads GitHub Actions run records, and no equivalent run-record listing is designed for GitLab pipelines or Forgejo Actions. Steering there uses ADR 0144 wakes alone, where ADR 0144 is implemented (ADR 0117).
  • Jira: not applicable. Entity-context-snapshot v1 does not stage Jira entities, so they do not steer (ADR 0117).

Consequences ​

  • Event-only harnesses on GitHub Actions can be steered during a cycle, but their next cycle still starts only from the queued workflow run.
  • Each listing costs one API request per page of up to 100 runs fetched, against the listing credential's rate budget.
  • Every shim run in an adopting repository gets a new title, which users see in the Actions UI.
  • A change that renames shim workflows or drops the run-name silences the signal; steering then falls back to ADR 0144 wakes alone.

Open questions ​

  • Which credential lists runs: a copy of the job's workflow token held only by the invocation layer, or an actions: read grant on each agent role's mint? Either is a trust-boundary change, decided with the implementation.
  • Should the signal also carry the run record's event name and actor into the steer span, for audit, even though they carry no authority?