opschain step emit-event
Included from Basic tier
opschain step emit-event <type> [--data key=value ...] [--data-file key=@path ...]
Records, from inside a running step, one custom event on the events stream
when this step succeeds: sourced from this step, inheriting the change's
correlation chain, and matchable by triggers on the type. The event is
appended as a JSON line to the file named by $OPSCHAIN_EVENTS; the
engine applies it on step success, and the event's data passes the run's
secret masker before storage.
Types are namespaced <namespace>:<name>, matching
^[a-z0-9_]+:[a-z0-9_:]+$. The api: system: info: error: warn:
prefixes are the server's and are refused.
Flags
| Flag | Meaning |
|---|---|
--data key=value | One event data entry (repeatable); the value is a string. Keys match ^[a-z0-9_]{1,50}$. |
--data-file key=@path | One event data entry read from a file (repeatable); the content embeds as parsed JSON when it is valid JSON, as a string otherwise. Same key grammar. |
Entries from both flags merge into one data object; a repeated key keeps
the later entry (--data-file entries are applied after --data).
Environment
| Variable | Meaning |
|---|---|
OPSCHAIN_EVENTS | The emitted-events file this command appends to (set by the executor). |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Event recorded. |
| 1 | A data file or the events file could not be read/written. |
| 2 | Usage error. |
Named errors
custom event type "<type>" must be <namespace>:<name> matching ^[a-z0-9_]+:[a-z0-9_:]+$custom event type "<type>" uses the reserved prefix "<prefix>" — api: system: info: error: warn: are the system's--data entries are key=value with a key matching ^[a-z0-9_]{1,50}$, got "<entry>"(same for--data-file)--data-file entries are key=@path, got "<entry>"$OPSCHAIN_EVENTS is not set:opschain stepsubcommands only work inside a running OpsChain step
All exit 2.
Examples
opschain step emit-event release:published --data version=2.3.1
opschain step emit-event scan:completed --data-file report=@scan-report.json
See also
opschain learn 5.4— custom events;opschain learn 5.2— triggers that match them.opschain docs cli/step-set-output— pass data to later steps instead of the event stream.