github-actions-authoring

Design event-driven GitHub Actions without remote-state polling.

SKILL.md

GitHub

GitHub Actions authoring

Read applicable AGENTS.md and their declared adapter alias, otherwise .agents/skills/github-actions-authoring/SKILL.md from the repository root if present. Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.

Never poll in CI. A workflow reacts to a state transition. Read github-actions-checklist first, then every applicable AGENTS.md. Repository-local policy and the consumer wrapper own runner labels, permissions, action pins, concurrency, secrets, and required-check names.

Design the event graph

  • Name the producer, the durable transition it emits, and the consumer that owns the next action.
  • Use needs for jobs in one workflow. Use workflow_call when the caller must await a reusable workflow. When a consumer must run after failure or skip, give it an explicit status condition and read needs.<job>.result. The implicit success condition skips it otherwise.
  • Use workflow_run when a completed workflow is the trusted event boundary. Validate the source workflow, repository, branch or pull-request head, conclusion, and artifacts before acting.
  • The workflow_run receiver must already exist on the default branch. GitHub chains at most three workflow_run levels. Plan that rollout, and collapse a deeper chain into one DAG.
  • Use repository_dispatch for a cross-repository transition or an authenticated external callback. Authenticate the sender, pass immutable correlation data, validate it against the source, and make duplicate delivery safe. The receiver must already exist on the default branch before senders are enabled.
  • Prefer a provider-native completion event, callback, queue, or state-machine transition for a deployment or service.
  • A scheduled reconciliation workflow may repair a missed event. It inspects one snapshot and exits. It does not wait for convergence.

Persistent workspaces

Apply the persistent-workspace rules in github-actions-checklist.

Reject polling designs

  • Do not add a sleep-and-read loop, a repeated query of a run, check, deployment, lease, or service, a CLI waiter, or a recursive redispatch whose purpose is to watch remote state change.
  • A timeout caps cost. It does not make polling event-driven.
  • If the producer cannot emit a usable event, add the bridge at the producer or provider boundary and let that bridge dispatch the correlated completion event.
  • Bounded retries are allowed only for the same failed operation, and only when the failure is transient and the operation is idempotent.
  • A local process readiness check is allowed when that process runs inside the job and cannot emit a workflow event.
  • Neither exception allows repeated observation of remote state.

Validate the result

  • Test accepted, rejected, duplicate, stale, and out-of-order events.
  • Preserve required-check names. Prove that every terminal producer outcome causes one terminal consumer outcome.
  • Run the local workflow checker and affected tests. Inspect the event graph for credentials crossing an untrusted boundary, a missing correlation field, and any remaining polling path.

Consumer wrapper owns: runner labels, permissions, action pins, concurrency, secrets, and required-check names.