Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Document CI session mode for release

shukieshahf9ff6a3e3799
diff --git a/.github/workflows/claude-security-review-session.yml b/.github/workflows/claude-security-review-session.yml
deleted file mode 100644
index 04f83498..00000000
--- a/.github/workflows/claude-security-review-session.yml
+++ /dev/null
@@ -1,72 +0,0 @@
-name: Beacon Claude Security Review telemetry
-
-on:
- pull_request:
- paths:
- - action.yml
- - .github/workflows/claude-security-review-session.yml
- - cli/beacon/**
- - collector-builder/exporter/beaconjsonexporter/**
- - examples/github-actions/**
- workflow_dispatch:
-
-permissions:
- contents: read
- pull-requests: write
-
-jobs:
- security-review:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v4
- with:
- ref: ${{ github.event.pull_request.head.sha || github.sha }}
- fetch-depth: 2
-
- - uses: actions/setup-go@v5
- with:
- go-version-file: cli/beacon/go.mod
-
- - name: Build branch Beacon CLI
- run: |
- set -euo pipefail
- mkdir -p /tmp/beacon-session-test
- cd cli/beacon
- go build -o /tmp/beacon-session-test/beacon .
-
- - name: Build branch Beacon collector
- run: |
- set -euo pipefail
- go install go.opentelemetry.io/collector/cmd/[email protected]
- cd collector-builder
- mkdir -p dist
- "$(go env GOPATH)/bin/builder" --config builder.yaml
- cp dist/beacon-otelcol/beacon-otelcol /tmp/beacon-session-test/beacon-otelcol
- chmod +x /tmp/beacon-session-test/beacon /tmp/beacon-session-test/beacon-otelcol
-
- - name: Start Beacon telemetry
- id: beacon
- uses: ./
- with:
- mode: start
- binary-path: /tmp/beacon-session-test/beacon
- harnesses: claude
-
- - name: Run Claude Code Security Review
- uses: anthropics/claude-code-security-review@main
- with:
- claude-api-key: ${{ secrets.CLAUDE_API_KEY }}
- comment-pr: false
- upload-results: true
- claudecode-timeout: "10"
- run-every-commit: true
-
- - name: Finish Beacon telemetry
- if: always() && steps.beacon.outcome == 'success'
- uses: ./
- with:
- mode: finish
- binary-path: /tmp/beacon-session-test/beacon
- min-events: "1"
- upload-artifact: "true"
- artifact-name: beacon-claude-security-review-runtime-log
diff --git a/.github/workflows/codex-action-session.yml b/.github/workflows/codex-action-session.yml
deleted file mode 100644
index 2c527ab0..00000000
--- a/.github/workflows/codex-action-session.yml
+++ /dev/null
@@ -1,68 +0,0 @@
-name: Beacon Codex Action telemetry
-
-on:
- pull_request:
- paths:
- - action.yml
- - .github/workflows/codex-action-session.yml
- - cli/beacon/**
- - collector-builder/exporter/beaconjsonexporter/**
- - examples/github-actions/**
- workflow_dispatch:
-
-permissions:
- contents: read
-
-jobs:
- codex-review:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v4
-
- - uses: actions/setup-go@v5
- with:
- go-version-file: cli/beacon/go.mod
-
- - name: Build branch Beacon CLI
- run: |
- set -euo pipefail
- mkdir -p /tmp/beacon-session-test
- cd cli/beacon
- go build -o /tmp/beacon-session-test/beacon .
-
- - name: Build branch Beacon collector
- run: |
- set -euo pipefail
- go install go.opentelemetry.io/collector/cmd/[email protected]
- cd collector-builder
- mkdir -p dist
- "$(go env GOPATH)/bin/builder" --config builder.yaml
- cp dist/beacon-otelcol/beacon-otelcol /tmp/beacon-session-test/beacon-otelcol
- chmod +x /tmp/beacon-session-test/beacon /tmp/beacon-session-test/beacon-otelcol
-
- - name: Start Beacon telemetry
- id: beacon
- uses: ./
- with:
- mode: start
- binary-path: /tmp/beacon-session-test/beacon
- harnesses: codex
-
- - name: Run Codex Action
- uses: openai/codex-action@main
- with:
- openai-api-key: ${{ secrets.OPENAI_API_KEY }}
- codex-home: ${{ steps.beacon.outputs.codex-home }}
- prompt: "Summarize this pull request and list one potential risk. Do not modify files."
- sandbox: read-only
- safety-strategy: read-only
-
- - name: Finish Beacon telemetry
- if: always() && steps.beacon.outcome == 'success'
- uses: ./
- with:
- mode: finish
- binary-path: /tmp/beacon-session-test/beacon
- min-events: "1"
- upload-artifact: "true"
- artifact-name: beacon-codex-action-runtime-log
diff --git a/action.yml b/action.yml
index bc1f7775..e4344d7e 100644
--- a/action.yml
+++ b/action.yml
@@ -94,6 +94,7 @@ runs:
# 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: |
@@ -109,7 +110,11 @@ runs:
exit 0
fi
- version="${INPUT_VERSION:-$DEFAULT_BEACON_VERSION}"
+ 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" ;;
diff --git a/cli/beacon/README.md b/cli/beacon/README.md
index c0355c67..11de811e 100644
--- a/cli/beacon/README.md
+++ b/cli/beacon/README.md
@@ -69,21 +69,34 @@ approval decision, repository, session, or message. Quick filters surface
high-severity events, failures, approvals, MCP activity, file changes, and events
that may need review.
-## Claude Code in CI
+## Agent Telemetry in CI
-Use `beacon ci exec` to collect Claude Code OpenTelemetry for a single CI job
-without installing a persistent endpoint service or changing
-`~/.claude/settings.json`:
+Use `beacon ci exec` to collect Claude Code or Codex OpenTelemetry for a single
+CI command without installing a persistent endpoint service or changing local
+developer configuration:
```bash
./beacon ci exec -- claude --print "Summarize this repository in one sentence"
```
+For actions or workflows that launch an agent internally, use CI session mode:
+
+```bash
+./beacon ci start --harness claude,codex
+# run one or more agent CI steps here
+./beacon ci finish --min-events 1
+```
+
Beacon starts the bundled `beacon-otelcol` in the foreground, writes a
-job-scoped collector config under `$RUNNER_TEMP/beacon` when available, injects
-Claude telemetry environment variables into only the child process, validates
-that structured Beacon events reached the runtime JSONL log, and returns the
-Claude command's exit code when telemetry validation succeeds.
+job-scoped collector config under `$RUNNER_TEMP/beacon`, configures supported
+agent harnesses to export OTLP to the local collector, validates that structured
+Beacon events reached the runtime JSONL log, and writes normalized JSONL for
+artifact upload or customer-managed forwarding.
+
+`ci exec` injects telemetry only into its child process. `ci start` writes
+session exports to `$GITHUB_ENV` when run through the composite action, which
+lets later `uses:` actions inherit Claude Code environment variables or a
+generated Codex `CODEX_HOME`.
Validate an existing CI artifact explicitly:
@@ -194,22 +207,65 @@ build.
### GitHub Action
-A composite action wraps binary resolution, `ci exec`, and artifact upload so a
-workflow can capture Claude Code telemetry in a few lines:
+A composite action wraps binary resolution, `ci exec`, session
+`start`/`finish`, and artifact upload. For a direct command, use the default
+`exec` mode:
```yaml
- name: Run Claude with Beacon telemetry
- uses: asymptote-labs/[email protected]
+ uses: asymptote-labs/agent-beacon@<tag>
with:
command: claude --print "Summarize the changes in this pull request"
```
The action downloads a pinned Beacon release and verifies it against the
-release `checksums.txt` before running (override the tag with `version`, or
-point at a vendored binary with `binary-path` for air-gapped runners). It
-uploads the runtime JSONL log as an artifact by default. To forward to a
-customer-managed SIEM, set `forward`/`forward-endpoint` and provide the token
-through a job- or workflow-level environment variable from a secret:
+release `checksums.txt` before running. When the action is invoked from a
+version tag, that tag is used as the default Beacon CLI release; set `version`
+explicitly or use `binary-path` when testing from a branch or local checkout.
+It uploads the runtime JSONL log as an artifact by default.
+
+To wrap a third-party agent action, split the action into `start` and `finish`
+steps:
+
+```yaml
+- name: Start Beacon telemetry
+ uses: asymptote-labs/agent-beacon@<tag>
+ with:
+ mode: start
+ harnesses: claude,codex
+
+- name: Run agent review action
+ uses: vendor/agent-review-action@main
+
+- name: Finish Beacon telemetry
+ if: always()
+ uses: asymptote-labs/agent-beacon@<tag>
+ with:
+ mode: finish
+ min-events: "1"
+```
+
+For Codex-based actions that accept a custom home directory, pass the generated
+Codex home output:
+
+```yaml
+- name: Start Beacon telemetry
+ id: beacon
+ uses: asymptote-labs/agent-beacon@<tag>
+ with:
+ mode: start
+ harnesses: codex
+
+- uses: openai/codex-action@main
+ with:
+ openai-api-key: ${{ secrets.OPENAI_API_KEY }}
+ codex-home: ${{ steps.beacon.outputs.codex-home }}
+ prompt: "Review this pull request"
+```
+
+To forward to a customer-managed SIEM, set `forward`/`forward-endpoint` on
+`exec` or `start` and provide the token through a job- or workflow-level
+environment variable from a secret:
```yaml
jobs:
@@ -218,7 +274,7 @@ jobs:
env:
BEACON_CI_SPLUNK_HEC_TOKEN: ${{ secrets.SPLUNK_HEC_TOKEN }}
steps:
- - uses: asymptote-labs/[email protected]
+ - uses: asymptote-labs/agent-beacon@<tag>
with:
command: claude --print "Summarize this repository"
forward: splunk
@@ -235,7 +291,7 @@ credentials at the job level and set `upload`:
aws-region: us-east-1
- name: Run Claude with Beacon telemetry
- uses: asymptote-labs/[email protected]
+ uses: asymptote-labs/agent-beacon@<tag>
env:
BEACON_CI_S3_BUCKET: my-beacon-telemetry
BEACON_CI_S3_PREFIX: github-actions
@@ -244,8 +300,10 @@ credentials at the job level and set `upload`:
upload: s3
```
-See [`examples/github-actions/claude-code-telemetry.yml`](../../examples/github-actions/claude-code-telemetry.yml)
-for a complete reference workflow.
+See [`examples/github-actions/claude-code-telemetry.yml`](../../examples/github-actions/claude-code-telemetry.yml),
+[`examples/github-actions/claude-security-review-session.yml`](../../examples/github-actions/claude-security-review-session.yml),
+and [`examples/github-actions/codex-action-session.yml`](../../examples/github-actions/codex-action-session.yml)
+for complete reference workflows.
## Wazuh
diff --git a/examples/github-actions/claude-code-telemetry.yml b/examples/github-actions/claude-code-telemetry.yml
index 59c4f0df..4ca99ac8 100644
--- a/examples/github-actions/claude-code-telemetry.yml
+++ b/examples/github-actions/claude-code-telemetry.yml
@@ -4,6 +4,7 @@
#
# This file lives under examples/ (not .github/workflows/) so it is a
# reference only and does not run in this repository.
+# Replace <tag> with the Beacon release tag you want to run.
name: Claude Code telemetry
@@ -36,7 +37,7 @@ jobs:
# aws-region: us-east-1
- name: Run Claude with Beacon telemetry
- uses: asymptote-labs/[email protected]
+ uses: asymptote-labs/agent-beacon@<tag>
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
with:
diff --git a/examples/github-actions/claude-security-review-session.yml b/examples/github-actions/claude-security-review-session.yml
index 3dd0e0cc..ec3feaea 100644
--- a/examples/github-actions/claude-security-review-session.yml
+++ b/examples/github-actions/claude-security-review-session.yml
@@ -1,5 +1,6 @@
# Reference workflow for wrapping Anthropic's Claude Code Security Review
# action with a Beacon CI telemetry session.
+# Replace <tag> with the Beacon release tag you want to run.
name: Beacon Claude Security Review telemetry
@@ -21,10 +22,9 @@ jobs:
fetch-depth: 2
- name: Start Beacon telemetry
- uses: asymptote-labs/agent-beacon@vNEXT
+ uses: asymptote-labs/agent-beacon@<tag>
with:
mode: start
- version: vNEXT
harnesses: claude
- name: Run Claude Code Security Review
@@ -37,10 +37,9 @@ jobs:
- name: Finish Beacon telemetry
if: always()
- uses: asymptote-labs/agent-beacon@vNEXT
+ uses: asymptote-labs/agent-beacon@<tag>
with:
mode: finish
- version: vNEXT
min-events: "1"
upload-artifact: "true"
artifact-name: beacon-claude-security-review-runtime-log
diff --git a/examples/github-actions/codex-action-session.yml b/examples/github-actions/codex-action-session.yml
index 9b5393e7..6e6c0904 100644
--- a/examples/github-actions/codex-action-session.yml
+++ b/examples/github-actions/codex-action-session.yml
@@ -1,5 +1,6 @@
# Reference workflow for wrapping OpenAI's customizable Codex Action with a
# Beacon CI telemetry session.
+# Replace <tag> with the Beacon release tag you want to run.
name: Beacon Codex Action telemetry
@@ -18,10 +19,9 @@ jobs:
- name: Start Beacon telemetry
id: beacon
- uses: asymptote-labs/agent-beacon@vNEXT
+ uses: asymptote-labs/agent-beacon@<tag>
with:
mode: start
- version: vNEXT
harnesses: codex
- name: Run Codex Action
@@ -35,10 +35,9 @@ jobs:
- name: Finish Beacon telemetry
if: always()
- uses: asymptote-labs/agent-beacon@vNEXT
+ uses: asymptote-labs/agent-beacon@<tag>
with:
mode: finish
- version: vNEXT
min-events: "1"
upload-artifact: "true"
artifact-name: beacon-codex-action-runtime-log