Run and host / GitHub App

Run from a GitHub issue or pull request

Start a Platform run from an issue or pull-request conversation comment. The command selects an organization profile; that profile owns the graph, runtime settings, connections, and delivery behavior.

Before you comment

A Zeroshot organization owner or admin must install the GitHub App, include the repository, and finish linking the installation in Connections. The organization also needs a GitHub-compatible profile and every saved connection field declared by that profile's RuntimePlan.

`Repository`	The installed App must have access to the repository where the issue lives.
`Profile`	Use the organization default or name one organization profile in the command.
`Connections`	Store provider keys at organization scope so issue-triggered runs can resolve them.
`Commenter`	The commenter must currently have Write, Maintain, or Admin access to the repository.

Zeroshot checks the commenter’s current repository permission with GitHub before starting a run. Organization membership or a collaborator label alone is not enough. Read and Triage access cannot start runs; if GitHub cannot verify permission, no run starts.

Set up connections and profiles

Command forms

Issue comment

Zeroshot

@zeroshot-cloud run

@zeroshot-cloud run review

`@zeroshot-cloud run`	Uses the organization's default profile.
`@zeroshot-cloud run review`	Uses the organization profile whose exact name is review.

Exact matching rules

Zeroshot scans a newly created issue comment line by line. It trims whitespace at the start and end of each line, then looks for one exact lowercase command. Other prose may appear on separate lines.

Accepted comment

Zeroshot

Please keep the change limited to the API package.

  @zeroshot-cloud run review

The command above is on its own line.

Ignored lines

Zeroshot

Please @zeroshot-cloud run this issue
@zeroshot-cloud run review --ship
@zeroshot-cloud run org:review
@Zeroshot-cloud run

`Line position`	The command must occupy a line by itself.
`Case`	The @zeroshot-cloud mention and run keyword are case-sensitive.
`Profile token`	A named command accepts one token after run, separated by one space.
`Profile name`	Use 1–64 characters. Start with a letter or digit; the rest may also use period, `_`, or hyphen.
`Comment event`	Only a new issue comment triggers parsing. Editing an existing comment does not start a run.
`Issue type`	Issue and pull-request conversation comments can select a review profile. Inline review comments do not start runs.

Scope prefixes such as org:review are CLI syntax, not profile names. GitHub commands always resolve organization profiles, so use @zeroshot-cloud run review.

Make a profile work with issue input

Implementation profiles receive task and issueNumber as initialInput. These profiles declare both fields in their GraphSpec. Feedback fields belong to graph state, where the engine initializes them; do not include them ininitialInput.

A review profile instead requires url and prepared context. Choose the Issue review or PR review template in the shared profile editor and configure its runtime. The App fetches the discussion title and body before execution; for a PR it also pins the base and head revisions. The profile's instructions define the review, so no task field is required.

GitHub profile initialInput

Zeroshot

{
  "kind": "record",
  "fields": {
    "task": {"type": {"kind": "string"}, "required": true},
    "issueNumber": {"type": {"kind": "string"}, "required": false}
  }
}

`task`	Contains the issue number, URL, title, body, and complete trigger comment as one instruction string.
`issueNumber`	Optionally contains the decimal issue number encoded as a string.

A missing named profile, an incompatible input shape, or unresolved connection fields stops submission before a run starts. Check the profile in the Zeroshot console rather than adding more words to the GitHub command.

What the App fixes for the run

`Title`	Uses GitHub owner/repository#issue-number so the run is easy to find in the console.
`Source`	Issue runs pin the repository's default branch. Review profiles on a PR inspect its exact head and captured base revisions, including fork contributions.
`Graph and runtime`	Copies both documents from the selected organization profile at submission time.
`GitHub access`	Binds the App installation and repository to the run; no token belongs in the comment.
`Delivery`	Follows the profile's graph, including a final review comment. The command itself does not change delivery mode.

A new matching comment creates a new run. GitHub webhook retries for the same comment event return the original run instead of submitting a duplicate.

What appears on the issue

Zeroshot adds a rocket reaction to the command comment, then posts one lifecycle comment with a direct run link. That comment changes from queued to started; if the run fails, it changes again to include the recorded reason and any available detail.

Open the run link for terminal status and graph activity. A successful run does not add a lifecycle success comment. A review profile can post its report as native comment delivery; other delivery nodes may create or merge a pull request according to the selected profile.

If no run starts

Confirm that the command is one exact line in a newly created issue comment.
Check that the commenter currently has Write, Maintain, or Admin repository access.
Open the Org tab in Connections and verify that the App includes this repository.
Confirm that the organization profile declares either review URL/context input or implementation task/issueNumber input.
Save every provider connection declared by the profile at organization scope.
Use the run console for admission or connection errors when Zeroshot posted a run link.