Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ona.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Available on the Free and Core plans. Contact sales to enable it for Enterprise.
Mention @ona-agent in a pull request comment to start an Ona agent on that PR. The agent reads the PR diff and recent comments, then works on the task you describe. For installation, see GitHub App.

​
How it works

  • The agent runs under your identity, mapped from your linked GitHub login. It uses your organization role and project permissions. Commits and PRs the agent opens are attributed to you.
  • The Ona GitHub App posts the reactions and reply comments. Your account needs no extra permissions for that.
  • The agent sees the PR title, body, diff, and recent comments. Its access to the rest of the repository is governed by the project at runtime.
  • Pull requests from forks are ignored. Fork PRs can carry untrusted code, and anyone with a GitHub account can comment on them.
  • Per-organization rate limits apply.

​
Prerequisites

  • The Ona GitHub App is installed on the GitHub organization that owns the repository.
  • The repository is in the App’s selected repositories.
  • An Ona project exists for the repository. If one does not, the agent prompts you to create one.

​
Where you can mention

The agent responds to mentions in three places on a pull request:
SurfaceWhere it appears
PR commentThe main conversation tab. Triggered by issue_comment events.
Inline review commentA comment attached to a specific line in the diff. Triggered by pull_request_review_comment events.
Review submissionThe body of a submitted review (Approve, Request changes, Comment). Triggered by pull_request_review events.
Mentions in regular issues and on fork PRs are ignored.

​
Supported handles

Use @ona-agent to trigger the agent. Mentions inside fenced code blocks, inline code spans, blockquotes, HTML comments, and image syntax are ignored, so you can write about the handle without triggering it.

​
Examples

​
Request a code review

A comment with only the handle starts a review: 
@ona-agent
The agent runs with the prompt Review this PR and help with any issues.

​
Mention with a task

Anything after the handle becomes the agent’s prompt: 
@ona-agent please add unit tests for the new pricing function

@ona-agent the snapshot test on line 42 is failing, figure out why and fix it

​
Reply on a review thread

If you mention the agent in a reply to an inline review comment, the agent receives the surrounding thread as context.

​
Commands

@ona-agent retry replays the last failed agent start on this PR. Use it after fixing the cause (for example, after creating a missing project). The command must be the whole prompt. @ona-agent retry the deploy runs as a normal prompt.

​
What you’ll see

  1. The agent reacts to your comment with an emoji to confirm the trigger.
  2. It posts one reply with the running session and a link to the Ona session view.
  3. The same reply updates in place as the agent works.

​
Cancelling

To cancel a running session from GitHub:
  • Delete your trigger comment. Cancels the session and posts a confirmation.
  • Delete the PR’s head branch. Cancels the session.
You can also cancel from the Ona session view.

​
Limitations

  • The agent reads the PR diff and the most recent comments. Older comments are not included.
  • Fork PRs are not supported. See How it works.
  • Editing a comment after the agent starts does not change the prompt. To change direction, post a new @ona-agent comment.
  • Posting a second @ona-agent mention while the first session is still running is not guaranteed to queue. Wait for the first reply, or cancel the running session by deleting the trigger comment.
  • Available on the Free and Core plans. Contact sales to enable it for Enterprise.

​
Troubleshooting

​
The agent didn’t respond

Check, in order:
  1. Is the Ona GitHub App installed on the repository’s owner?
  2. Is the repository in the App’s selected repositories?
  3. Is your Ona organization on the Free or Core plan?
  4. Did you spell the handle correctly (@ona-agent)?
  5. Are you commenting on a pull request, not a regular issue?
  6. Is the PR from the same repository, not a fork?
If all six check out and the agent stays silent for a minute or two, contact support.

​
Missing GitHub permissions

The agent posted a [!CAUTION] comment because the App is missing a required permission. Ask an admin to update the App install. See Permissions.

​
No project matches this repo

No Ona project is configured for this repository. The agent posts a link to create one. Once you create it, the agent resumes the original mention. If you do not create the project within a few minutes, the watcher times out and you’ll need to mention the agent again.

​
Next steps