The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
name: "Agent Beacon CI Telemetry"
description: "Capture agent CI telemetry to Agent Beacon JSONL, artifacts, or customer-managed destinations."
author: "Asymptote Labs"
branding:
icon: "radio"
color: "purple"
inputs:
mode:
description: "How to run Beacon CI telemetry: 'exec' (default), 'start', or 'finish'."
required: false
default: "exec"
command:
description: >-
The Claude Code command to run, e.g. claude --print "Summarize this repo".
Executed via bash -c so the configured telemetry environment reaches it.
Required when mode is 'exec'.
required: false
default: ""
harnesses:
description: "Comma-separated agent harnesses to configure, e.g. claude,codex."
required: false
default: ""
version:
description: >-
Beacon CLI release tag to download (e.g. v0.0.39). Defaults to a version
pinned by this action. SIEM forwarding requires a release that includes
the ci exec --forward feature.
required: false
default: ""
binary-path:
description: >-
Path to an existing beacon binary. When set, the download and checksum
verification are skipped. Use for air-gapped or self-hosted runners. The
beacon-otelcol collector must sit beside it.
required: false
default: ""
min-events:
description: "Minimum Beacon events required for telemetry validation to pass."
required: false
default: "1"
require-telemetry:
description: >-
Fail the step when telemetry validation fails. Set to 'false' to downgrade
a telemetry-pipeline failure to a warning so it does not gate the build.
required: false
default: "true"
forward:
description: >-
Optional SIEM forwarder: 'splunk' or 'falcon'. Leave empty to disable.
The token must be supplied via the BEACON_CI_SPLUNK_HEC_TOKEN or
BEACON_CI_FALCON_HEC_TOKEN environment variable (set it at the job or
workflow level from a secret), never as an input.
required: false
default: ""
forward-endpoint:
description: "SIEM HEC endpoint URL for the selected --forward provider."
required: false
default: ""
upload:
description: >-
Optional post-run artifact upload destinations: 's3', 'gcs', or a
comma-separated list. Configure provider credentials at the job level
using the normal AWS or Google Cloud CI mechanisms.
required: false
default: ""
upload-artifact:
description: "Upload the runtime JSONL log as the universal workflow artifact."
required: false
default: "true"
artifact-name:
description: >-
Name for the uploaded telemetry artifact. The default names it after the
job and its matrix index so every job and matrix leg in a run keeps its
own artifact. Set a distinct name for each use of this action in one job.
required: false
default: beacon-runtime-log-${{ github.job }}-${{ strategy.job-index }}
outputs:
log-path:
description: "Path to the Beacon runtime JSONL log."
value: ${{ steps.paths.outputs.log-path }}
state-path:
description: "Path to the Beacon CI session state file."
value: ${{ steps.paths.outputs.state-path }}
codex-home:
description: "Path to Beacon's generated Codex home directory."
value: ${{ steps.paths.outputs.codex-home }}
runs:
using: "composite"
steps:
- name: Resolve Beacon binary
id: resolve
shell: bash
env:
# A specific tag is pinned here rather than resolving "latest" so runs
# are reproducible and the downloaded archive can be checksum-verified.
DEFAULT_BEACON_VERSION: "v0.0.49"
ACTION_REF: ${{ github.action_ref }}
INPUT_VERSION: ${{ inputs.version }}
INPUT_BINARY_PATH: ${{ inputs.binary-path }}
run: |
set -euo pipefail
if [ -n "${INPUT_BINARY_PATH}" ]; then
if [ ! -x "${INPUT_BINARY_PATH}" ]; then
echo "::error::binary-path '${INPUT_BINARY_PATH}' is not an executable file"
exit 1
fi
echo "beacon-bin=${INPUT_BINARY_PATH}" >> "$GITHUB_OUTPUT"
echo "Using provided beacon binary: ${INPUT_BINARY_PATH}"
exit 0
fi
version="${INPUT_VERSION:-${ACTION_REF:-$DEFAULT_BEACON_VERSION}}"
if [ "${version#v}" = "${version}" ]; then
echo "::error::Beacon release version '${version}' is not a version tag. Set the version input or binary-path when using a branch/local action ref."
exit 1
fi
case "$(uname -s)" in
Linux) os="linux" ;;
Darwin) os="darwin" ;;
*) echo "::error::unsupported operating system $(uname -s)"; exit 1 ;;
esac
case "$(uname -m)" in
x86_64|amd64) arch="amd64" ;;
arm64|aarch64) arch="arm64" ;;
*) echo "::error::unsupported architecture $(uname -m)"; exit 1 ;;
esac
ver_no_v="${version#v}"
archive="beacon_${ver_no_v}_${os}_${arch}.tar.gz"
base="https://github.com/asymptote-labs/agent-beacon/releases/download/${version}"
workdir="$(mktemp -d)"
echo "Downloading ${archive} (${version})"
curl -fsSL "${base}/${archive}" -o "${workdir}/${archive}"
curl -fsSL "${base}/checksums.txt" -o "${workdir}/checksums.txt"
# Verify the archive against the release checksums before extracting.
expected="$(grep " ${archive}\$" "${workdir}/checksums.txt" | awk '{print $1}')"
if [ -z "${expected}" ]; then
echo "::error::no checksum entry for ${archive} in checksums.txt"
exit 1
fi
if command -v sha256sum >/dev/null 2>&1; then
actual="$(sha256sum "${workdir}/${archive}" | awk '{print $1}')"
else
actual="$(shasum -a 256 "${workdir}/${archive}" | awk '{print $1}')"
fi
if [ "${expected}" != "${actual}" ]; then
echo "::error::checksum mismatch for ${archive}: expected ${expected}, got ${actual}"
exit 1
fi
tar -xzf "${workdir}/${archive}" -C "${workdir}"
chmod +x "${workdir}/beacon" "${workdir}/beacon-otelcol" 2>/dev/null || true
echo "beacon-bin=${workdir}/beacon" >> "$GITHUB_OUTPUT"
echo "Verified and extracted beacon ${version} to ${workdir}"
- name: Resolve Beacon paths
id: paths
shell: bash
run: |
set -euo pipefail
log_dir="${BEACON_CI_BASE_DIR:-${RUNNER_TEMP:-$(mktemp -d)}/beacon}"
mkdir -p "${log_dir}"
echo "base-dir=${log_dir}" >> "$GITHUB_OUTPUT"
echo "log-path=${log_dir}/runtime.jsonl" >> "$GITHUB_OUTPUT"
echo "state-path=${log_dir}/session.json" >> "$GITHUB_OUTPUT"
echo "codex-home=${log_dir}/codex-home" >> "$GITHUB_OUTPUT"
- name: Run command with Beacon telemetry
id: exec
if: ${{ inputs.mode == 'exec' }}
shell: bash
env:
BEACON_BIN: ${{ steps.resolve.outputs.beacon-bin }}
INPUT_HARNESSES: ${{ inputs.harnesses }}
INPUT_COMMAND: ${{ inputs.command }}
INPUT_MIN_EVENTS: ${{ inputs.min-events }}
INPUT_REQUIRE_TELEMETRY: ${{ inputs.require-telemetry }}
INPUT_FORWARD: ${{ inputs.forward }}
INPUT_FORWARD_ENDPOINT: ${{ inputs.forward-endpoint }}
INPUT_UPLOAD: ${{ inputs.upload }}
LOG_PATH: ${{ steps.paths.outputs.log-path }}
run: |
set -euo pipefail
if [ -z "${INPUT_COMMAND}" ]; then
echo "::error::input 'command' is required when mode is 'exec'"
exit 1
fi
args=(ci exec
--log-path "${LOG_PATH}"
--min-events "${INPUT_MIN_EVENTS}"
"--require-telemetry=${INPUT_REQUIRE_TELEMETRY}"
)
if [ -n "${INPUT_HARNESSES}" ]; then
args+=(--harness "${INPUT_HARNESSES}")
fi
if [ -n "${INPUT_FORWARD}" ]; then
args+=(--forward "${INPUT_FORWARD}")
if [ -n "${INPUT_FORWARD_ENDPOINT}" ]; then
args+=(--forward-endpoint "${INPUT_FORWARD_ENDPOINT}")
fi
fi
if [ -n "${INPUT_UPLOAD}" ]; then
IFS=',' read -ra upload_values <<< "${INPUT_UPLOAD}"
for upload in "${upload_values[@]}"; do
upload="${upload//[[:space:]]/}"
if [ -n "${upload}" ]; then
args+=(--upload "${upload}")
fi
done
fi
# INPUT_COMMAND is passed through the environment (not interpolated into
# this script) so workflow inputs cannot inject shell commands.
"${BEACON_BIN}" "${args[@]}" -- bash -c "${INPUT_COMMAND}"
- name: Start Beacon telemetry session
id: start
if: ${{ inputs.mode == 'start' }}
shell: bash
env:
BEACON_BIN: ${{ steps.resolve.outputs.beacon-bin }}
INPUT_HARNESSES: ${{ inputs.harnesses }}
INPUT_FORWARD: ${{ inputs.forward }}
INPUT_FORWARD_ENDPOINT: ${{ inputs.forward-endpoint }}
LOG_PATH: ${{ steps.paths.outputs.log-path }}
STATE_PATH: ${{ steps.paths.outputs.state-path }}
run: |
set -euo pipefail
harnesses="${INPUT_HARNESSES:-claude,codex}"
args=(ci start
--log-path "${LOG_PATH}"
--state-path "${STATE_PATH}"
--github-env "${GITHUB_ENV}"
--harness "${harnesses}"
)
if [ -n "${INPUT_FORWARD}" ]; then
args+=(--forward "${INPUT_FORWARD}")
if [ -n "${INPUT_FORWARD_ENDPOINT}" ]; then
args+=(--forward-endpoint "${INPUT_FORWARD_ENDPOINT}")
fi
fi
"${BEACON_BIN}" "${args[@]}"
- name: Finish Beacon telemetry session
id: finish
if: ${{ always() && inputs.mode == 'finish' }}
shell: bash
env:
BEACON_BIN: ${{ steps.resolve.outputs.beacon-bin }}
INPUT_MIN_EVENTS: ${{ inputs.min-events }}
INPUT_REQUIRE_TELEMETRY: ${{ inputs.require-telemetry }}
INPUT_UPLOAD: ${{ inputs.upload }}
STATE_PATH: ${{ steps.paths.outputs.state-path }}
run: |
set -euo pipefail
args=(ci finish
--state-path "${STATE_PATH}"
--min-events "${INPUT_MIN_EVENTS}"
"--require-telemetry=${INPUT_REQUIRE_TELEMETRY}"
)
if [ -n "${INPUT_UPLOAD}" ]; then
IFS=',' read -ra upload_values <<< "${INPUT_UPLOAD}"
for upload in "${upload_values[@]}"; do
upload="${upload//[[:space:]]/}"
if [ -n "${upload}" ]; then
args+=(--upload "${upload}")
fi
done
fi
"${BEACON_BIN}" "${args[@]}"
- name: Upload Beacon telemetry
if: ${{ always() && inputs.upload-artifact == 'true' && inputs.mode != 'start' }}
uses: actions/upload-artifact@v4
with:
name: ${{ inputs.artifact-name }}
path: ${{ steps.paths.outputs.log-path }}
if-no-files-found: warn