> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macroscope.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Github actions

**Early preview**

Run Macroscope agents from your GitHub Actions workflows with `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](/setup-instructions) 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](#cost-controls).

The action authenticates with a short-lived **GitHub OIDC** token: grant the job `id-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`:

```markdown theme={null}
---
title: Release Audit
input: full_diff
tools: [browse_code, git_tools]
maxBudgetPerRun: 2
---
Review the supplied changes for release-blocking regressions.
Report actionable findings with file paths and explain their impact.
```

An agent definition with a nonempty Markdown instructions body is required. Keep definitions under **`.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](/check-run-agents/instructions#importing-files), 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.

```yaml theme={null}
name: Macroscope Review
on:
  pull_request:

jobs:
  release-audit:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - id: audit
        uses: prassoai/macroscope-actions/run@69f77549f71dadd393c8bed2e9f231edac51243f
        with:
          repository: ${{ github.repository }}
          agent: Release Audit
          commit: ${{ github.event.pull_request.head.sha }}
          base: ${{ github.event.pull_request.base.sha }}
          fail-on: failure
          additional-instructions: Focus on authentication and authorization changes.
```

This reviews the PR head against its base on Macroscope infrastructure. The GitHub runner waits for the result; no checkout is needed.

## 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:

| Agent configuration | Workflow equivalent |
| - | - |
| `autoRun`, `authors`, `labels`, `targets` | Event triggers and job `if` conditions. |
| `waitsFor`, `requires`, discovery/wait timeouts | Job `needs` and workflow timeouts. `needs` only sequences jobs in the same workflow. |
| `maxRuns` | Workflow frequency, concurrency, cancellation, and retries. |
| `maxBudgetPerPR` | [Workflow-run spend limit](#cost-controls). |
| `requiredStatusCheck`, `conclusion: failure` | Require the workflow job; use `fail-on: failure` without `continue-on-error`. |

`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 include **`pull_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.

| Task | Agent input mode | What to supply |
| - | - | - |
| Review changes between two commits, with or without a PR | `full_diff` (default) | Target `commit` and a valid `base` SHA. |
| Inspect PR metadata without including the diff in the prompt | `pr_metadata` | Target `commit` and `pull-request` number. No base is required. |

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](/pricing#agent). Three controls apply:

| Control | Where | Scope |
| - | - | - |
| **Workspace monthly limit** | **Settings → Billing** | Total workspace usage for the billing period, including GitHub Actions agents. |
| **GitHub Actions per-workflow-run limit** | **Settings → Billing** | Aggregate agent spend across all steps, matrix jobs, and rerun attempts in one GitHub workflow run. |
| **`maxBudgetPerRun`** | Agent Markdown frontmatter | US-dollar spend ceiling for one agent invocation. |

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-readable **`result.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.

## Action reference

The public [**macroscope-actions README**](https://github.com/prassoai/macroscope-actions#readme) is the reference for exact inputs and outputs, the artifact schema, polling and upload behavior (including failure and cancellation cases), version pinning, runner requirements, and detailed troubleshooting.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.