Integrations

Optio integrates with external services for task sourcing, notifications, and event delivery. This page covers all supported integrations and how to configure them.

GitHub Issues

GitHub Issues is the most common task source. Optio can browse issues from connected repos and turn them into tasks, either manually or automatically.

Prerequisites

• A GITHUB_TOKEN secret configured in Optio (requires repo scope for private repos)
• At least one repository connected

Browsing Issues

The Issues view in the dashboard lists open issues across all connected repositories. You can browse, filter, and assign issues to Optio with a single click.

GET /api/issues

# Returns issues across all connected repos
# Requires GITHUB_TOKEN secret

Manual Assignment

Assign a specific issue to Optio, creating a task with the issue title and body as the prompt:

POST /api/issues/assign
{
  "issueUrl": "https://github.com/acme/webapp/issues/42",
  "repoUrl": "https://github.com/acme/webapp"
}

Automatic Sync

Set up a GitHub Issues ticket provider to automatically sync issues into tasks. The ticket sync worker polls periodically for new issues matching your filter.

1. Go to Settings and add a ticket provider
2. Select GitHub Issues as the source
3. Configure the sync scope (specific labels, assignees, or all issues)
4. Enable the provider

POST /api/tickets/providers
{
  "source": "github",
  "config": {
    "repos": ["https://github.com/acme/webapp"],
    "labels": ["optio", "ai-task"],
    "assignee": null
  },
  "enabled": true
}

Linear

Optio integrates with Linear as a ticket provider, syncing Linear issues into Optio tasks.

Setup

1. Generate a Linear API key from your Linear workspace settings
2. Add the API key as a secret in Optio
3. Create a Linear ticket provider in Settings
4. Configure the team and project scope

POST /api/tickets/providers
{
  "source": "linear",
  "config": {
    "apiKey": "lin_api_...",
    "teamId": "TEAM_ID",
    "projectId": "PROJECT_ID"
  },
  "enabled": true
}

How Sync Works

• The ticket sync worker runs periodically and polls each enabled provider
• New issues matching the filter criteria are created as Optio tasks
• The issue title becomes the task title, and the issue description becomes the prompt
• Tasks track their source via ticketSource and ticketExternalId fields
• Duplicate issues are not re-synced (deduplication by external ID)

Slack

Optio can send Slack notifications for task events. Configure Slack per repository to get notified when tasks complete, fail, or need attention.

Setup

1. Create an Incoming Webhook in your Slack workspace
2. Navigate to Repos → (select repo) → Settings
3. Enable slackEnabled
4. Paste the webhook URL in slackWebhookUrl

Testing

Send a test notification to verify the webhook is working:

POST /api/slack/test
{
  "webhookUrl": "https://hooks.slack.com/services/T.../B.../..."
}

Notification Events

Slack notifications are sent for key task lifecycle events:

• Task completed (PR merged)
• Task failed
• Task needs attention (CI failure or review changes requested)
• PR opened

Webhooks

Webhooks let you push Optio events to any HTTP endpoint in real time. This is the most flexible integration option, enabling custom workflows, dashboards, and third-party integrations.

Creating a Webhook

POST /api/webhooks
{
  "url": "https://your-app.example.com/optio-events",
  "events": ["task.completed", "task.failed", "task.pr_opened"],
  "secret": "your-webhook-secret"
}

Event Types

Payload Format

{
  "event": "task.completed",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "taskId": "abc123",
    "title": "Add email validation",
    "repoUrl": "https://github.com/acme/webapp",
    "state": "completed",
    "prUrl": "https://github.com/acme/webapp/pull/42",
    "costUsd": "0.35"
  }
}

Webhook Security

If you provide a secret when creating a webhook, Optio signs each delivery with an HMAC-SHA256 signature in the request headers. Verify this signature on your server to ensure payloads are authentic.

Delivery Tracking

Every webhook delivery is recorded in the webhook_deliveries table with the HTTP status code and success/failure status. The webhook worker handles delivery asynchronously via BullMQ.

WebSocket Events

For real-time browser-based integrations, Optio provides WebSocket endpoints. Events are published to Redis pub/sub and relayed to connected clients.

WebSocket connections authenticate via the ?token= query parameter using the same session token as the REST API.

MCP Servers

Optio supports configuring Model Context Protocol (MCP) servers that extend the agent's capabilities. MCP servers can be configured globally or per repository.

POST /api/mcp-servers
{
  "name": "GitHub Tools",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": { "GITHUB_TOKEN": "{{GITHUB_TOKEN}}" },
  "repoUrl": null
}

Set repoUrl to scope the MCP server to a specific repo, or leave it null for global availability.

Next Steps