prassoai/macroscope-actions/run. Your workflow controls when agents run, their sequencing, concurrency, and cancellation. Macroscope executes the agents and publishes their results in GitHub.
A pull request is not required. Use agents for PR reviews, post-push audits, scheduled checks, releases, or manually dispatched tasks. Macroscope does not create a separate Check Run for these invocations. If you need a required PR check, require your workflow’s job in branch protection.
Get started
Connect your repository to Macroscope and confirm that GitHub Actions agent runs is enabled in its Macroscope settings (it’s on by default). Have a workspace admin confirm the balance and spend limits. The action authenticates with a short-lived GitHub OIDC token: grant the jobid-token: write, with no Macroscope API key or stored secret. The authenticated repository must match the repository input. The production endpoint is https://actions.macroscope.com, which the action uses by default. No checks: write permission is needed.
Add agent instructions
Create.macroscope/check-run-agents/github-actions/release-audit.md:
.macroscope/check-run-agents/github-actions/ (subdirectories within this folder are fine). The action selects the agent by title and reads its definition at the target commit. These agents run only when your workflows invoke them, not automatically or through @macroscope mentions.
Shared Markdown guidance can live elsewhere in the repository and be imported, for example with @/CLAUDE.md. Keep triggering and sequencing in workflow YAML, not Check Run Agent orchestration fields.
Add a workflow
Create.github/workflows/macroscope-review.yml:
For optional run-specific guidance, set additional-instructions under the action step’s with: in workflow YAML, as shown below. It is not a field in the agent Markdown file or its frontmatter.
Migrating an automatic agent
Move its definition into.macroscope/check-run-agents/github-actions/ and invoke its title from workflow YAML. The target commit must contain the definition. To keep both automatic and workflow-triggered checks, use separate definitions with unique titles.
Keep model, tools, include, exclude, imports, and maxBudgetPerRun. Use explicit input: full_diff or input: pr_metadata. Move orchestration into GitHub Actions:
conclusion: failure is rejected on this path. conclusion: neutral is accepted as a compatibility no-op; remove it because it does not control the job result.
Rejected orchestration fields produce HTTP 422, naming the definition and fields. A missing agent title produces 404. Neither starts an agent. If invalid-definition diagnostics exceed discovery limits, unmatched titles return 422 with cleanup guidance; valid agents remain available.
Supported tasks
Supported triggers includepull_request, push, schedule, release, and workflow_dispatch. Fork PRs cannot use this authentication; the example gates the job to same-repository branches. pull_request_target and workflow_run are rejected. Run the agent in the source workflow instead, using needs for sequencing.
For non-PR workflows,
commit defaults to ${{ github.sha }}. On a push to an existing branch, ${{ github.event.before }} can supply the base; schedules, releases, and manual runs need a baseline you choose. An all-zero new-branch SHA is not a valid base. incremental and code_object inputs are not supported. Omitting base does not request a whole-repository audit.
Supply pull-request for PR-scoped tools, even in a diff review. Tools remain subject to workspace capabilities and connected integrations.
Cost controls
These runs use Agent credits. Three controls apply:
The workflow-run and per-invocation limits are best effort: work already in progress can exceed them, especially across concurrent jobs. Reruns do not reset the workflow-run limit. GitHub runner charges are separate; the action’s
timeout bounds waiting time, not agent spend.
There is no per-PR GitHub Actions limit. Check Run Agents’ per-PR spend and run-count limits do not apply, even when a workflow supplies a PR number.
Admins can see a breakdown of Agent credit usage (including the breakdown between Check Run Agents and agents invoked via GitHub Actions) in the billing section on Macroscope.
Results and auditability
The action automatically appends the verdict, run status, summary, run ID, and Agent Credits (or Not billed) to the job summary, with a reason when provided. Each valid terminal result also produces a versioned, machine-readableresult.json artifact, available from the workflow run’s Artifacts section. This is a terminal result, not a structured list of individual findings.
Use the run ID to correlate the result with Macroscope’s record of the agent definition, target commit, GitHub workflow run and attempt, actor, outcome, and associated credits. Definitions and workflows remain reviewable in your repository. Anyone with access to the workflow summary or artifact can read the result; treat it with the same care as workflow logs.