macroscope-actions

Composite GitHub Actions for Macroscope — run Macroscope agents from workflows you own.

The model: your workflow owns the run. Triggers, sequencing, retries, concurrency, cancellation, and the conclusion are all yours, in GitHub's native vocabulary — on:, needs:, if:, strategy.matrix, concurrency:. Macroscope is the execution backend: the run action starts an agent (defined as markdown under .macroscope/check-run-agents/github-actions/ in your repo), holds the run open, and reports its run ID, verdict, and summary as step outputs. The workflow job is itself the check — there is no Macroscope-owned check run on this path — so branch protection reads your job's conclusion directly. Supported triggers include pull_request, push, schedule, release, and workflow_dispatch, subject to the repository trust policy described below.

Macroscope rejects workflow_run because the triggering workflow's provenance is not authenticated; run the agent in the source workflow instead, using needs: to sequence it after other jobs. It also rejects pull_request_target because it may execute untrusted code with base-repository authority; use pull_request instead.

The run action is the supported workflow entry point. It mints GitHub OIDC, starts or rejoins one durable Macroscope run, polls until the server returns a terminal result, and writes the result as step outputs, a job summary, and a downloadable JSON result artifact.

Governance

Canonical source: prassoai/back. This repository is a generated artifact of that monorepo's release workflow, so the actions, the API they call, and their tests change together. It accepts no contributions — pull requests are closed by policy, and support and source live in the monorepo.

Repository access restrictions, branch and tag protection, and feature availability are managed in GitHub repository settings, not enforced by this source tree. Do not assume those protections are configured; verify the repository settings directly.

Authentication

The run action authenticates with a per-job GitHub OIDC token — there is no Macroscope API key or secret to store, rotate, or leak. The job grants id-token: write; the action mints the token and Macroscope verifies its claims against a repo-level trust policy. GitHub Actions agent runs default to enabled for existing and new repository settings; a repo admin can disable the integration in Macroscope settings.

permissions:
  contents: read
  id-token: write       # REQUIRED: mints the OIDC token that authenticates to Macroscope
  # no checks: scope — the job itself is the check run, concluded by GitHub

A permissions: map is closed — every scope it does not list is revoked — so id-token: write must be present. Without it the action fails immediately, naming the missing scope.

Usage

Full-diff agents pass an explicit base:

name: Macroscope Release Audit

on:
  pull_request:

permissions:
  contents: read
  id-token: write

jobs:
  release-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
      - id: macroscope
        uses: prassoai/macroscope-actions/run@<sha> # v1
        with:
          repository: ${{ github.repository }}
          agent: Release Audit
          commit: ${{ github.event.pull_request.head.sha }}
          base: ${{ github.event.pull_request.base.sha }}
          fail-on: failure
          timeout: "1800"
          additional-instructions: |
            Focus on release-blocking regressions.

PR metadata agents pass pull-request instead:

name: Macroscope PR Metadata

on:
  pull_request:

permissions:
  contents: read
  id-token: write

jobs:
  pr-metadata:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
      - id: macroscope
        uses: prassoai/macroscope-actions/run@<sha> # v1
        with:
          repository: ${{ github.repository }}
          agent: PR Metadata Audit
          commit: ${{ github.event.pull_request.head.sha }}
          pull-request: ${{ github.event.pull_request.number }}

Inputs

Input	Required	Default	Description
api-url	no	https://actions.macroscope.com	HTTPS Macroscope control plane URL.
repository	yes		Repository in owner/name form; must match GitHub OIDC claims.
agent	yes		Agent title under .macroscope/check-run-agents/github-actions/.
commit	no	${{ github.sha }}	Target commit SHA.
base	no		Base commit SHA for diff-shaped inputs.
pull-request	no		Pull request number for PR metadata inputs and PR-scoped tools.
fail-on	no	failure	failure, neutral, or never.
timeout	no	1800	Maximum seconds to wait for a terminal result.
additional-instructions	no		Extra prompt text, capped at 16 KiB.

Outputs

Output	Description
run-id	Durable Macroscope run ID. Written once start succeeds.
verdict	Terminal verdict: success, neutral, or failure.
summary	Terminal agent summary.

Job summary and result artifact

Every valid terminal result appends a Macroscope section to $GITHUB_STEP_SUMMARY: agent verdict, run status, run ID, summary, and a reason when provided, plus Agent Credits or Not billed. Existing summary content is preserved. Agent text is HTML-escaped and displayed as preformatted text, not interpreted as HTML or Markdown.

The action uploads result.json in an artifact named macroscope-result-<run-id>-<unique-suffix>. The durable Macroscope run ID provides correlation; a per-invocation suffix prevents collisions when a run is rejoined. Download it from the workflow run's Artifacts section. Retention follows the repository's artifact retention policy.

The version 1 JSON contract is:

{
  "schemaVersion": 1,
  "runId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "succeeded",
  "reason": null,
  "verdict": "success",
  "summary": "Clean\nship it",
  "agentCredits": "3.579"
}

status is succeeded, failed, or cancelled; absent reason, verdict, and summary are represented as JSON null. Consumers should check schemaVersion before reading the result. agentCredits is an exact decimal string. Runs with no credits charged display Not billed in the job summary; the artifact records zero credits.

This is a terminal result artifact, not a canonical structured findings list. It contains only the documented fields, never internal findingsReference values, arbitrary API fields, or authentication tokens. It retains the original summary text in JSON without rendering it. Anyone with access to the workflow summary or artifact can read the agent's result; apply the same care to prompts and summaries as to workflow logs.

Runtime behavior

Polling is the execution lease. While the backend reports pending or running, each poll renews the lease; if the workflow is cancelled or the runner dies, polling stops and Macroscope lapses the run server-side. The action retries transport failures, server errors, 429, and rate-limited 403 responses within the remaining timeout budget.

fail-on maps the terminal result to the step exit status. failure fails only on a failed or absent verdict, neutral also fails on neutral, and never leaves the step green for agent outcomes and timeouts. Terminal outputs and the job summary are written before any fail-on failure. The artifact upload uses always() when a result file exists, so a failing verdict does not skip it or turn the failed action green. if: always() consumers can still inspect the existing outputs. Upload errors fail the action independently of fail-on. Timeouts, transport failures, and malformed responses do not fabricate a terminal summary or artifact; run-id remains available if start succeeded. Hard cancellation or runner loss can prevent publication or upload.

Versioning / pinning

Pin to a full commit SHA — uses: prassoai/macroscope-actions/run@<sha> — with a trailing # v1.x.y comment for readability. A mutable tag (@v1, @main) lets a retagged upstream run attacker-controlled code inside a job that can mint an OIDC token; an immutable SHA cannot move under you.

There is no container image in these actions. The run script uses curl, jq, and openssl (for random output delimiters). Result upload delegates to a full-SHA-pinned actions/upload-artifact v6, which uses Node.js 24; self-hosted runners require Actions Runner 2.327.1 or newer and access to GitHub's artifact service. This uploader does not support GitHub Enterprise Server (GHES). No additional GITHUB_TOKEN permission is needed for the upload.

License

MIT