action.yml

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."
    required: false
    default: "beacon-runtime-log"

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