Overview
Autonomous agents integrate with Linear via OAuth. When a user @mentions or assigns the agent on a Linear issue, Linear sends a webhook to the portal, which instantly claims the issue, launches a workspace, and streams progress back to Linear. No polling and no labels are required for triggering. Linear is the currently supported project tracker. Jira and GitHub Issues integrations are planned.Connecting Linear
Authorize the agent
Authorize the Qovery agent in Linear’s consent screen. The agent requests access to issues, comments, workflow states, and teams.
How the Issue Flow Works
The following diagram shows the end-to-end flow from @mentioning or assigning the agent on an issue to receiving a pull request.Configuring Teams
Each agent blueprint monitors one Linear team. Only issues from the configured team are picked up by that blueprint. The team dropdown in the blueprint settings uses the OAuth connection to list all available teams. To monitor multiple teams, create separate agent blueprints - one per team.| Blueprint Setting | Value |
|---|---|
| Linear Team | Required. The team whose issues the agent monitors. |
Workflow State Mapping
Agent blueprints map three Linear workflow states to key moments in the run lifecycle. These state transitions keep your Linear board in sync with agent activity.In-Progress State (required)
Set when the agent claims the issue. This signals to the team that work has started and prevents the issue from being picked up by another agent or assigned manually. The blueprint cannot function without this state configured. If autonomous mode is enabled but no In-Progress state is set, the blueprint will not process issues.In-Review State (optional)
Set when the agent successfully opens a pull request. If not configured, the issue state is not changed on success - only a lifecycle comment with the PR URL is posted.Needs-Human State (optional)
Set when the agent fails or the run times out. If not configured, the issue state is not changed on failure - only a lifecycle comment with the failure reason is posted.| State | Required | When Set | Fallback if Not Configured |
|---|---|---|---|
| In-Progress | Yes | Agent claims the issue | Blueprint will not process issues |
| In-Review | No | Agent opens a PR | Comment posted, state unchanged |
| Needs-Human | No | Agent fails or times out | Comment posted, state unchanged |
Agent Activities in Linear
When a run starts, the agent posts structured activities directly in the Linear issue - visible inline to all team members.Agent Plan
A 4-step checklist appears in the Linear issue:- Analyzing issue
- Setting up workspace
- Running AI agent
- Opening pull request
Progress Updates
The agent streams live “thought” activities from the workspace. These appear as real-time status updates in the Linear issue thread, giving the team visibility into what the agent is doing at each moment.External URLs
The session sidebar in Linear shows direct links to:- The RDE dashboard for the current run
- The pull request (when available)
Final Result
On success, the agent posts a response activity containing the PR link. On failure, it posts an error activity with the failure details.Traditional comments are also posted on the issue for audit trail purposes.
Interacting with Agents from Linear
Bidirectional Messaging
While an agent is running, users can post follow-up instructions as comments on the Linear issue. The agent processes these messages and can adjust its approach. Messages are delivered to the workspace via a polling endpoint (approximately every 5 seconds).Stop Signal
Linear’s native stop button works. When pressed, the portal stops the workspace and marks the run as failed.Slash Commands
You can also control agents by posting a comment with one of these commands:| Command | Action |
|---|---|
/stop | Stop the agent and its workspace environment |
/restart | Restart the workspace environment |
/delete | Stop the agent and mark the run as done |
/status | Show the current agent status and workspace state |
Concurrency and Timing
Max Concurrent Runs
Each blueprint has a configurable concurrency cap (default: 3). When the number of active runs (statusclaimed, launching, or running) reaches this limit, incoming webhooks for that blueprint are queued until a slot opens.
Run Timeout
Each run has a maximum duration (default: 60 minutes). When the timeout is reached, the workspace is stopped, the run status is set totimed_out, and a lifecycle comment is posted on the Linear issue. If a Needs-Human state is configured, the issue transitions to that state.
Atomic Claiming
When the webhook fires, the session handler claims the issue atomically via a database unique constraint on(org_id, linear_issue_id). This prevents duplicate runs even if the agent is @mentioned multiple times on the same issue.
Disconnecting Linear
To disconnect, navigate to Admin > Settings and click the Disconnect link under the Autonomous Agent section. This revokes the OAuth tokens and removes the organization mapping. Existing runs are not affected, but no new runs can be triggered.Future Integrations
Jira and GitHub Issues integrations are planned. The agent blueprint configuration will be extended with additional project tracker options. If you need a specific integration, contact the Qovery team.
Next Steps
Agent Blueprints
Configure blueprints that define how agents run, including runtimes, repositories, and resource limits.
Managing Runs
Monitor active runs, review results, and troubleshoot failures.
Getting Started
Set up your first autonomous agent from scratch.