How to Build an AI Agent for Linear and GitHub

The workflow problem

Modern engineering teams use Linear for project management and GitHub for code. In theory, every piece of work should start as a Linear issue and end when the corresponding code merges. In practice, these two systems drift apart constantly. Developers open pull requests without linking them to Linear issues. Issues sit in “In Progress” long after the PR was merged because nobody updated the status. Bug fixes get committed directly to main with no corresponding issue created, making sprint retrospectives incomplete.

The operational impact goes beyond messy project boards. Engineering managers rely on Linear’s cycle reports to measure velocity, identify blockers, and plan capacity. When issue statuses do not reflect reality, every planning decision is based on stale data. A cycle report might show fifteen issues “In Progress” when eight of them already have merged PRs. The team appears slower than it actually is, which leads to misguided conversations about productivity.

Pull request hygiene suffers too. Without a bidirectional link between Linear and GitHub, reviewers lack context about why a change is being made. They see a diff but not the product requirement, the user story, or the acceptance criteria. Code reviews become purely technical exercises disconnected from the business intent, which means reviewers catch syntax issues but miss cases where the implementation does not actually solve the problem described in the ticket.

Why an AI agent, not just automation

Simple integrations between Linear and GitHub exist. They can link a PR to an issue if the developer includes the issue ID in the branch name or commit message. But they require discipline, and they break down when developers forget the convention or when work does not follow a neat one-issue-to-one-PR mapping.

An AI agent does not depend on naming conventions. When a developer opens a PR without referencing a Linear issue, the agent reads the PR title, description, and diff to understand what the change does. It then searches Linear for related issues. If it finds a matching issue, it links them automatically. If no issue exists, it creates one in the correct team’s backlog with an appropriate title, description derived from the PR, and labels inferred from the code areas changed.

The agent also handles the complex reality that work is not always one-to-one. A single Linear issue might require multiple PRs (one for the API, one for the frontend, one for the migration). The agent tracks all related PRs and only moves the Linear issue to “Done” when every associated PR has merged. Conversely, a single PR might address multiple issues (a refactor that fixes three bugs). The agent identifies all relevant issues and updates each one.

Status transitions benefit from intelligence too. The agent does not just flip between “In Progress” and “Done.” It understands the full lifecycle: when a PR is opened, the issue moves to “In Progress.” When the PR is approved but not merged, the issue moves to “In Review.” When CI fails, the agent can add a comment on the Linear issue noting the failure. When the PR merges to a staging branch, the status changes to “Ready for QA.” When it merges to main, it moves to “Done.” This granularity is impossible with simple webhook automation.

How it works with ACP

ACP provides your agent with access to both Linear’s project management data and GitHub’s repository and PR lifecycle, enabling true bidirectional synchronization.

Linear tools available to the agent:

• Create, read, and update issues (title, description, status, assignee, labels, priority)
• Read and update cycle/sprint data
• Access project and team structures
• Read and create comments on issues
• Move issues between workflow states
• Query issues by filters (assignee, label, status, project)
• Read and update issue relationships (blocks, relates to, duplicates)

GitHub tools available to the agent:

• Read pull request details: title, description, diff, file changes, review status
• Read and create PR comments
• Access branch information and merge status
• Read CI/CD check results and workflow runs
• Read commit messages and history
• Access repository labels and milestones
• Read CODEOWNERS and contribution metadata

The agent maintains continuous alignment between your project tracker and your codebase. Here is a realistic workflow:

Event: Developer Kai opens a PR titled “Add rate limiting to public API endpoints” with no Linear issue reference in the branch name or description.

Agent reasoning: “This PR has no linked Linear issue. Let me analyze the changes: it modifies api/middleware/rate_limiter.py, adds tests in tests/api/test_rate_limiter.py, and updates config/api_limits.yaml. The PR description says ‘Implements rate limiting per API key with configurable thresholds.’ Let me search Linear for related issues.”

Linear search: The agent finds issue ENG-342: “Implement API rate limiting” in the “Backlog” state, assigned to the Platform team with priority “High.”

Agent actions:

• Links the PR to ENG-342 by adding a comment on the PR: “Linked to Linear issue ENG-342: Implement API rate limiting”
• Updates ENG-342’s status from “Backlog” to “In Progress”
• Adds a comment on the Linear issue: “PR opened: ‘Add rate limiting to public API endpoints’ – 4 files changed, 312 lines added. CI running.”

Later: PR gets approved. The agent updates ENG-342 to “In Review.”

Later: PR merges to main. The agent moves ENG-342 to “Done,” adds a comment with the merge commit SHA, and updates the issue’s completion date. If ENG-342 had sub-issues or related issues, the agent checks whether those also have merged PRs before marking parent issues complete.

Governance and security

Linking project management data with source code requires careful access control. ACP enforces precise boundaries.

Linear OAuth scopes: The agent uses Linear’s OAuth integration with scopes for reading and writing issues, comments, and project data. It cannot modify workspace settings, manage team memberships, or access billing information. Write access is limited to issue status transitions, comments, and issue creation. The agent cannot delete issues or modify workflow state definitions.

GitHub OAuth scopes: The agent uses repo scope for reading PR data, diffs, and CI status, and for posting PR comments. It does not have admin:org or delete_repo permissions. If you want the agent to be read-only on GitHub (only reading PRs without commenting), you can restrict the scope to repo:status and read:org. The agent never accesses GitHub Secrets, deploy keys, or webhook configurations.

Repository boundaries: You can configure the agent to monitor only specific repositories rather than all repos in your GitHub organization. Linear teams can be mapped to specific repositories, so the agent only creates issues in the correct team’s board. For example, changes to the frontend repo only create issues for the Frontend team in Linear.

Audit trail: Every issue creation, status change, and PR comment is logged with the agent’s identity, the source event that triggered the action, and timestamps. If a Linear issue was incorrectly moved to “Done,” the audit trail shows exactly which GitHub event caused the transition and when. This traceability is essential for teams that need to reconstruct decision chains during incident reviews.

Preventing loops: ACP includes circuit-breaker logic to prevent the agent from creating infinite loops (for example, agent updates Linear, which triggers a webhook to GitHub, which triggers the agent again). Each action is tagged with the agent’s identity, and the agent ignores events it generated itself.

Example use cases

• Automatic issue linking: PRs that reference code areas matching open Linear issues are automatically linked. Developers no longer need to remember issue IDs or follow branch naming conventions. The agent uses code context and semantic matching to find the right issue.

• Status synchronization: Linear issue statuses reflect the true state of the code. “In Progress” means a PR is open. “In Review” means the PR is approved but not merged. “Done” means the code is in production. No manual status updates required.

• Issue creation from unlinked PRs: When a developer opens a PR that does not match any existing issue, the agent creates a new Linear issue with a description derived from the PR, assigns it to the developer, and places it in the current cycle. This ensures all code changes are trackable.

• Stale issue detection: The agent identifies Linear issues marked “In Progress” that have no associated open PR and no code activity in the past week. It flags these for the engineering manager as potentially stalled work.

• Release note generation: When a release branch is cut or a tag is created, the agent compiles all Linear issues whose associated PRs are included in the release and generates a structured list of changes categorized by team and priority.

Getting started

Connect your project tracker to your codebase in minutes:

1. Sign up at cloud.agenticcontrolplane.com. The free tier has everything you need.

2. Connect Linear and GitHub. Authorize both tools on the Data Sources page via OAuth. Select which GitHub repositories and Linear teams the agent should monitor.

3. Describe your agent. Tell ACP: “Monitor all PRs in our repositories. Link them to matching Linear issues automatically. Update issue status based on PR lifecycle: In Progress when opened, In Review when approved, Done when merged. Create new issues for unlinked PRs.” Your project tracking is now synchronized with reality.