Event payload reference

The envelope

The normalized event envelope is the single event contract in KiCI. Rules receive it as ctx.event, and every dynamic function — environment:, env:, and concurrencyGroup: resolvers, generated jobs, and a workflow’s concurrency.group — receives the same envelope as its argument.

Narrow on the type field to branch per trigger kind (if (event.type === 'push')). The raw provider webhook body is nested at payload; the typed variants below describe its shape per event type.

These fields are present on every envelope (the EventBase shape):

Field	Type	Description
type	string	Normalized event type discriminant.
action?	string	Sub-action (e.g. ‘opened’, ‘created’, ‘submitted’).
targetBranch?	string	Target branch (push target, PR base, or default branch).
sourceBranch?	string	Source branch (PR head branch). Only set for PR-like events.
provider?	string	Provider that originated this event.
isForkPR?	boolean	Whether this PR comes from a fork. Only set for PR-like events.
baseBranch?	string	Base branch ref for PR events.
senderUsername?	string	Sender username from the webhook payload.
sourceRepo?	string	Repository identifier (e.g. “owner/repo”).
changedFiles?	string[]	Files changed in this event (for path filtering).
payload?	Record<string, unknown>	Raw webhook payload from the provider. May be absent in flattened event forms.
[key: string]	unknown	Index signature for backward compatibility — untyped fields resolve to unknown.

Event types

One section per member of the EventPayload union. The heading is the type literal; the table lists the fields of that event’s payload property when it declares a typed shape.

pull_request

Carried by PullRequestEventPayload. The payload property has the following shape:

Field	Type	Description
action	string
number	number
pull_request	GitHubPullRequest
repository	GitHubRepository
sender	GitHubUser
[key: string]	unknown

push

Carried by PushEventPayload. The payload property has the following shape:

Field	Type	Description
ref	string
after	string
before	string
head_commit?	GitHubCommit
commits?	GitHubCommit[]
repository	GitHubRepository
sender?	GitHubUser
forced?	boolean
[key: string]	unknown

tag

Carried by TagEventPayload. The payload property has the following shape:

Field	Type	Description
ref	string
after	string
repository	GitHubRepository
sender?	GitHubUser
[key: string]	unknown

comment

Carried by CommentEventPayload. The payload property has the following shape:

Field	Type	Description
action	string
comment	GitHubComment
issue?	{ number: number; title?: string; pull_request?: unknown; [key: string]: unknown }
repository	GitHubRepository
sender	GitHubUser
[key: string]	unknown

review

Carried by ReviewEventPayload. The payload property has the following shape:

Field	Type	Description
action	string
review	GitHubReview
pull_request	GitHubPullRequest
repository	GitHubRepository
sender	GitHubUser
[key: string]	unknown

review_comment

Carried by ReviewCommentEventPayload. The payload property has the following shape:

Field	Type	Description
action	string
comment	GitHubComment
pull_request	GitHubPullRequest
repository	GitHubRepository
sender	GitHubUser
[key: string]	unknown

release

Carried by ReleaseEventPayload. The payload property has the following shape:

Field	Type	Description
action	string
release	GitHubRelease
repository	GitHubRepository
sender	GitHubUser
[key: string]	unknown

dispatch

Carried by DispatchEventPayload. The payload property has the following shape:

Field	Type	Description
action	string
client_payload?	Record<string, unknown>
repository	GitHubRepository
sender?	GitHubUser
[key: string]	unknown

create

Carried by CreateEventPayload. The payload property has the following shape:

Field	Type	Description
ref	string
ref_type	string
repository	GitHubRepository
sender	GitHubUser
[key: string]	unknown

delete

Carried by DeleteEventPayload. The payload property has the following shape:

Field	Type	Description
ref	string
ref_type	string
repository	GitHubRepository
sender	GitHubUser
[key: string]	unknown

status

Carried by StatusEventPayload. The payload property has the following shape:

Field	Type	Description
state	string
sha	string
context	string
description?	string
target_url?	string
branches?	Array<{ name: string; [key: string]: unknown }>
repository	GitHubRepository
sender	GitHubUser
[key: string]	unknown

workflow_run

Carried by WorkflowRunEventPayload. The payload property has the following shape:

Field	Type	Description
action	string
workflow_run	{ head_branch: string; name: string; conclusion?: string; status?: string; [key: string]: unknown; }
repository	GitHubRepository
sender	GitHubUser
[key: string]	unknown

fork

Carried by ForkEventPayload. The payload property has the following shape:

Field	Type	Description
forkee	{ full_name: string; [key: string]: unknown }
repository	GitHubRepository
sender	GitHubUser
[key: string]	unknown

star

Carried by StarEventPayload. The payload property has the following shape:

Field	Type	Description
action	string
repository	GitHubRepository
sender	GitHubUser
[key: string]	unknown

watch

Carried by WatchEventPayload. The payload property has the following shape:

Field	Type	Description
action	string
repository	GitHubRepository
sender	GitHubUser
[key: string]	unknown

webhook

Carried by WebhookEventPayload. Adds no typed fields beyond the shared envelope; payload is the raw provider body (Record<string, unknown>).

kici_event

Carried by KiciEventPayload. Adds no typed fields beyond the shared envelope; payload is the raw provider body (Record<string, unknown>).

workflow_complete

Carried by WorkflowCompleteEventPayload. Adds no typed fields beyond the shared envelope; payload is the raw provider body (Record<string, unknown>).

job_complete

Carried by JobCompleteEventPayload. Adds no typed fields beyond the shared envelope; payload is the raw provider body (Record<string, unknown>).

generic_webhook

Carried by GenericWebhookEventPayload. Adds no typed fields beyond the shared envelope; payload is the raw provider body (Record<string, unknown>).

schedule

Carried by ScheduleEventPayload. Adds no typed fields beyond the shared envelope; payload is the raw provider body (Record<string, unknown>).

lifecycle

Carried by LifecycleEventPayload. Adds no typed fields beyond the shared envelope; payload is the raw provider body (Record<string, unknown>).

rerun

Carried by RerunEventPayload. Adds no typed fields beyond the shared envelope; payload is the raw provider body (Record<string, unknown>).

manual_schedule

Carried by ManualScheduleEventPayload. Adds no typed fields beyond the shared envelope; payload is the raw provider body (Record<string, unknown>).

unknown

Carried by UnknownEventPayload. Adds no typed fields beyond the shared envelope; payload is the raw provider body (Record<string, unknown>).

Shared GitHub object shapes

The typed payload shapes above reference these partial GitHub object types. Each lists only the commonly accessed fields; the index signature on every shape resolves any other field to unknown.

GitHubRepository

Field	Type	Description
full_name	string
default_branch	string
name?	string
owner?	{ login: string; [key: string]: unknown }
private?	boolean
[key: string]	unknown

GitHubUser

Field	Type	Description
login	string
id?	number
[key: string]	unknown

GitHubPullRequest

Field	Type	Description
number	number
draft?	boolean
title?	string
body?	string
state?	string
merged?	boolean
head	{ ref: string; sha: string; repo?: { full_name: string; [key: string]: unknown }; [key: string]: unknown; }
base	{ ref: string; repo?: { full_name: string; [key: string]: unknown }; [key: string]: unknown; }
user?	GitHubUser
labels?	Array<{ name: string; [key: string]: unknown }>
[key: string]	unknown

GitHubCommit

Field	Type	Description
id	string
message	string
author?	{ name?: string; email?: string; username?: string; [key: string]: unknown }
timestamp?	string
added?	string[]
removed?	string[]
modified?	string[]
[key: string]	unknown

GitHubComment

Field	Type	Description
id	number
body	string
user	GitHubUser
[key: string]	unknown

GitHubReview

Field	Type	Description
id	number
state	string
body?	string
user	GitHubUser
[key: string]	unknown

GitHubRelease

Field	Type	Description
id	number
tag_name	string
name?	string
body?	string
draft?	boolean
prerelease?	boolean
target_commitish?	string
[key: string]	unknown