Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jonwiggins/optio/llms.txt

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

Optio integrates with GitHub in two directions: it can pull issues in from your repositories so the agent can work on them, and it opens and manages pull requests once a task is underway.

​
Prerequisites

You need a GitHub personal access token (classic) or a fine-grained token with the following permissions:
  • Issues: read and write
  • Pull requests: read and write
  • Contents: read and write (for pushing branches)
  • Metadata: read
Store the token as a secret named GITHUB_TOKEN in Settings → Secrets before connecting any repository.

​
Browsing GitHub Issues

Once GITHUB_TOKEN is set and you have at least one repository added to Optio, open the Issues view from the sidebar. Optio fetches open issues from every connected repository and displays them in a unified list, sorted with unassigned issues first.Each issue card shows:
  • Issue title, number, and repository
  • Current GitHub labels
  • Whether the issue already has an Optio task linked to it
You can filter by repository using the repo selector at the top of the list.

​
Assigning an issue to Optio

When you assign an issue, Optio creates a task, queues it for the agent, and links it back to the GitHub issue.
1

Open the Issues view

Navigate to the Issues tab in the sidebar. You will see all open issues across your connected repositories.
2

Click Assign

Find the issue you want to work on and click the Assign to Optio button on the issue card. The issue title and body are used as the task title and prompt automatically.
3

Confirm

Optio creates the task, transitions it to queued, and posts a comment on the GitHub issue confirming that the agent is working on it. The issue is also labeled optio (a purple label is created if it does not already exist).
You can also trigger assignment programmatically:
POST /api/issues/assign
Content-Type: application/json

{
  "issueNumber": 42,
  "repoId": "<repo-uuid>",
  "title": "Fix the login redirect",
  "body": "When a user logs in from /checkout they should return to /checkout...",
  "agentType": "claude-code"
}

​
What happens next

After assignment:
  1. The task appears in the Tasks view with its state progressing through queued → provisioning → running.
  2. The agent works on the issue and opens a pull request when done.
  3. The task transitions to pr_opened and the PR URL is recorded on the task.
  4. When the PR is merged, the task completes automatically and Optio can update the issue state to closed.
Issues that already have an Optio task linked show their current task state on the issue card. Clicking Assign again on an already-assigned issue is a no-op — Optio will not create a duplicate task.

​
GitHub webhook (optional)

By default, Optio polls the GitHub API every 30 seconds to detect PR state changes. You can configure GitHub to push events to Optio directly for faster updates.
1

Set a webhook secret

In your Optio deployment, set the GITHUB_WEBHOOK_SECRET environment variable to a random string. This is used to verify that incoming webhook payloads are genuinely from GitHub.
2

Register the webhook in GitHub

Go to your GitHub repository → Settings → Webhooks → Add webhook and fill in:
  • Payload URL: https://<your-optio-domain>/api/webhooks/github
  • Content type: application/json
  • Secret: the same value you set for GITHUB_WEBHOOK_SECRET
  • Events: select Issues and Pull requests
3

Verify delivery

GitHub will send a ping event immediately after you save the webhook. You should see a green checkmark in the Recent deliveries list confirming Optio received it successfully.
With the webhook active, Optio will:
  • Trigger an immediate ticket sync when an issue is labeled optio
  • Transition the corresponding task to completed as soon as a PR merge event arrives — without waiting for the 30-second polling interval
The GitHub webhook is optional. Optio works correctly without it; the webhook only reduces the latency between a GitHub event and the task state update in Optio.

Build docs developers (and LLMs) love

Get started for freeTalk to us