Skip to main content

​
Command Overview

beacon ci exec starts a temporary Beacon collector, runs the child command after --, stops the collector, validates the runtime log, and prints the artifact paths. The child command’s exit code is preserved.
Command syntax
beacon ci exec -- <command>
When GITHUB_ACTIONS=true, Beacon records GitHub Actions run metadata such as workflow, run ID, commit, ref, and actor in the CI session result. Other CI environments are marked as ephemeral CI runs when CI is set.

​
Flags

FlagDescription
--harness <harness>CI harness to configure. Defaults to claude; supported values include claude, codex, or comma-separated aliases
--log-path <path>CI runtime JSONL log path
--jsonPrint the execution and validation result as JSON
--min-events <count>Minimum matching events required during validation. Defaults to 1
--keep-artifactsKeep CI runtime log and collector config after exit. Enabled by default
--forward <destination>Optionally forward CI events to a customer-managed SIEM. Supported values are splunk and falcon
--forward-endpoint <url>SIEM HEC endpoint URL for the selected --forward provider. Tokens are read from BEACON_CI_SPLUNK_HEC_TOKEN or BEACON_CI_FALCON_HEC_TOKEN
--require-telemetry <bool>Fail when telemetry validation fails. Defaults to true; set false to warn without gating the child command result
--upload <destination>Upload the completed CI runtime JSONL after validation. Supported values are s3 and gcs; repeat for multiple destinations
Hidden operational flags are available for custom runners and tests, including --base-dir, --work-dir, --collector, --otlp-grpc-port, and --otlp-http-port. --upload s3 reads BEACON_CI_S3_BUCKET and optional BEACON_CI_S3_PREFIX. --upload gcs reads BEACON_CI_GCS_BUCKET and optional BEACON_CI_GCS_PREFIX.
--content-retention is deprecated and hidden. Beacon now captures supported CI content subject to redaction, sanitization, truncation, and event-size limits; the flag is accepted as a no-op for compatibility.

​
Examples

Wrap an agent command in GitHub Actions:
Wrap an agent command in GitHub Actions
beacon ci exec -- claude -p "Run the repository test suite and summarize failures"
Write CI telemetry to a known artifact path:
Write CI telemetry to a known artifact path
beacon ci exec \
  --log-path "$RUNNER_TEMP/beacon/runtime.jsonl" \
  -- claude -p "Review this pull request"
Run with telemetry validation as a warning instead of a hard gate:
Run with telemetry validation as a warning instead of a hard gate
beacon ci exec \
  --require-telemetry=false \
  -- claude -p "Inspect the changed files"
Print machine-readable output:
Print machine-readable output
beacon ci exec --json -- claude -p "Check release readiness"
Upload the completed CI runtime log to S3:
Upload the completed CI runtime log to S3
BEACON_CI_S3_BUCKET="my-beacon-telemetry" \
BEACON_CI_S3_PREFIX="github-actions" \
beacon ci exec --upload s3 -- claude -p "Review this pull request"

beacon ci

Review CI artifact paths and command group behavior.

beacon ci validate

Validate CI runtime telemetry artifacts after a job step.

CI Telemetry Exports

Export CI runtime JSONL through workflow artifacts, S3, GCS, or downstream pipelines.