Skip to main content
A Check Run Agent runs only if the event selects it and the applicable settings, filters, and limits allow it. Check the GitHub check details for skip and configuration messages.

​
Events

​
Run a check manually

Comment on the PR, mention @macroscope-app, and name the check by its title, for example @macroscope-app run Security Review. The title match ignores case. Macroscope replies “Review triggered”, or, if no check has that name, lists the checks that do exist. A manual run bypasses repository skip settings and run limits. The check’s own labels, authors, targets, and file filters still apply, so a check they exclude does not appear.

​
Settings

In repository settings, Check Run Agents is set to Always run, Manual invocation only, or Never run. Each person can override it for their own PRs in personal settings: Always on, Always off, or Repo default. Nothing overrides Never run. Three more pull request settings decide which PRs are eligible. Review Draft PRs controls drafts, and a person’s Review my draft PRs overrides it for their own PRs. Review Cross-Repo PRs controls PRs from forks and other repositories, and Skip Dependabot controls Dependabot PRs. A blocked draft gets no check. A blocked cross-repo or Dependabot PR gets a skipped check.

​
Order of checks

Macroscope checks these in order and stops at the first one that blocks:
  1. Selection: did the event select this check?
  2. Check Run Agents setting: personal setting first, then the repository setting.
  3. Definition: is there a valid file in .macroscope/check-run-agents/?
  4. Applicability: front matter authors, labels, and targets, or the repository’s Skip PRs by Author, Skip PRs by Labels, and Skip PRs by Target Branches when an axis is not set.
  5. File scope: include, exclude, and .macroscope/ignore.md.
  6. Limits: workspace balance and monthly limit, then the workspace Check Run Agents per-PR limit, then maxBudgetPerPR, then maxRuns.
  7. Prerequisites: waitsFor and requires.
While the agent runs, maxBudgetPerRun and the model’s context window can still stop it.

​
Overrides

Front matter authors, labels, and targets replace the matching repository Skip PRs by rule for that check. They still apply to manual runs.

​
Diagnose the outcome

For a check required by branch protection, requiredStatusCheck: true reports a skip when filters exclude an already selected check. It cannot create a check for an event that never selected it, or when Check Run Agents is set to Never run.

​
Definition source

Definitions and their imports come from the latest PR commit, except external fork PRs, which use the default branch. Other open PRs need to include an updated definition before it applies to them. Use .macroscope/check-run-agents/ for automatic Check Run Agents. Files under its github-actions/ subdirectory run only through GitHub Actions.