Run and host / GitHub App

Run from a GitHub issue

Start a Cloud run from an issue 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`	GitHub must report the author as OWNER, MEMBER, or COLLABORATOR for that repository.

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`	Commands on pull-request conversations are ignored, even though GitHub exposes them through the issues API.

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

The App supplies task and issueNumber as initialInput. A profile used from GitHub must declare both fields in its GraphSpec. Feedback fields belong to graph state, where the engine initializes them; do not include them ininitialInput.

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`	Checks out the repository's default branch at the revision current when the comment arrives.
`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. The command itself cannot switch between no delivery, pull request, or merge.

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 separate success comment, while a delivery node 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 GitHub marks the commenter as an owner, member, or collaborator.
Open the Org tab in Connections and verify that the App includes this repository.
Confirm that the named organization profile accepts task and issueNumber as 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.