Buildkite Agentic Pipeline Example: Linear Issue Handler

A Buildkite pipeline that uses Claude Code and Buildkite model providers to diagnose and fix Linear issues.

Setting up

Step 1: Start with an existing Linear workspace

Make sure you have access to a Linear workspace that allows you to create and manage webhooks.

Step 2: Prepare your agentic pipeline

1. Create a new GitHub repository using this repository as a template.
2. Create a new Buildkite pipeline for your newly templated repository with a Linux hosted agents cluster.
3. Create a new pipeline trigger for the pipeline, then copy the generated webhook URL to your clipboard.
4. On the Settings > API page of your Linear workspace, add a new Linear webhook, paste your Buildkite webhook URL into the URL field, choose Issues (under Data change events), and save.
5. Create three new Buildkite secrets with the following names:
   1. GITHUB_TOKEN: A GitHub personal access token with repo and pull_request read/write scopes.
   2. LINEAR_API_TOKEN: A Linear API key with "Read" permissions.
   3. API_TOKEN_BUILDKITE: A Buildkite API access token with read_builds, read_build_logs, and read_pipelines permissions.

Step 3: Trigger the pipeline

1. Create a new issue Linear describing the work to be done. Label the issue with buildkite-analyze. (This label is configurable in .buildkite/pipeline.yml.)
2. In a few moments, you should see a new comment appear on the issue confirming the agent's picked up the task. Follow the link to the Buildkite dashboard to have a look.
3. Once the agent determines a fix, you should see a new PR submitted on the associated GitHub repository explaining what was done. Have a look at that PR, and if it looks good, approve and merge.

That's it! Your issue should now be addressed. 🎉

How it works

The pipeline listens for webhooks originating from Linear issue events. When a new issue is detected, the pipeline runs the handler script, which adds a step to the running pipeline that uses Claude to diagnose and fix the issue, annotating the Buildkite build as it goes. When the work is complete, Claude commits the changes to a new feature branch on the associated GitHub repository, submits a new PR, and reports back on the Linear issue with a summary.

The following diagram shows the high-level flow, beginning with the Linear issue label:

sequenceDiagram
    participant User
    participant Linear
    participant Buildkite
    participant Agent as AI Agent
    participant GitHub

    User->>Linear: Apply label to issue
    Linear->>Buildkite: Send webhook with issue details
    Buildkite->>Buildkite: Validate payload and generate pipeline
    Buildkite->>Agent: Start agent in Docker container
    Agent->>Linear: Acknowledge issue with build link
    Agent->>Linear: Read issue details
    Agent->>GitHub: Analyze codebase
    Agent->>Agent: Determine complexity

    alt Low/medium complexity
        Agent->>GitHub: Create PR with fix
        Agent->>Linear: Post PR link
        User->>GitHub: Review and merge PR
    else Higher complexity
        Agent->>Linear: Post detailed analysis
        User->>Linear: Review findings
        User->>GitHub: Implement fix manually
    end

Loading

Step summary

1. User applies a buildkite-analyze label to a Linear issue.
2. Linear sends a webhook notification to Buildkite with issue details, triggering the pipeline.
3. Pipeline evaluates the webhook payload and conditionally adds a step to the running pipeline to launch Claude. pipeline dynamically.
4. In a Docker containerm Claude reads the issue, analyzes the codebase, and determines a course of action:
   • For simpler issues, it creates a fix and submits a PR to GitHub.
   • For more complex issues, it documents its findings and posts an analysis back to Linear.