# triagebot-action

> A GitHub Action that reproduces, diagnoses and fixes reported bugs through a label-driven state machine, then asks the reporter to verify

- Category: AI Coding / AI SDLC Automation
- Language: TypeScript
- Repository: https://github.com/withastro/triagebot-action
- Canonical page: https://ai-tldr.dev/tools/triagebot-action/
- Updated: 2026-08-04

## In short

triagebot-action is an AI-powered issue triage bot for GitHub repositories, built by the Astro team with Cloudflare. It sits in the AI SDLC Automation category of the AI Coding tools and is open-source, written in TypeScript. To get started: create the workflow.

## Overview

triagebot-action is an AI-powered issue triage bot for GitHub repositories, built by the Astro team with Cloudflare. It runs as a GitHub Action on issue and comment events and works through a label-driven state machine: it tries to reproduce the reported bug, diagnoses the root cause, attempts a fix, and asks the reporter to verify the result before a pull request is opened. Because state lives in labels, the whole pipeline is visible in the issue tracker rather than hidden in a service.

The states it moves an issue through are needs_triage, not_actionable, needs_reproduction, skipped, unable_to_reproduce, unable_to_fix, fix_pending, fix_rejected, fix_verified and failed. An issue that cannot be reproduced or fixed lands in an explicit state instead of silently stalling, which is what makes the bot's output auditable by a maintainer.

It is model-agnostic: the action accepts Anthropic, OpenAI, or Cloudflare Workers AI credentials, defaulting to Claude Opus 4.6 for triage and Sonnet 4.6 for verification when the Anthropic key is used. The triage behaviour itself is supplied as a skill directory in your own repository, so each project can teach the bot how its bugs are usually reproduced. In production on Astro's repository the maintainers report the open-issue count fell from over 200 to about 30.

## What it does

- Label-driven state machine with ten explicit states, so triage progress is visible on the issue itself
- Reproduces the bug, diagnoses the root cause, attempts a fix and asks the reporter to verify it
- Provider-agnostic: Anthropic, OpenAI or Cloudflare Workers AI credentials
- Triage behaviour supplied as a skill directory in your own repository
- Split read and write tokens, so the bot commits under a separate identity
- Optional build command, custom labels and an auto-PR mode

## Getting started

Add the action to a workflow that listens for issue events, give it a read token, a write token and one model provider key, and point it at your triage skill.

1. Create the workflow

   The README's example triggers on issue and comment events and keeps one concurrency group per issue number.

```yaml
# .github/workflows/triage.yml
name: Issue Triage

on:
  issues:
    types: [opened, reopened, closed]
  issue_comment:
    types: [created]

permissions: {}

concurrency:
  group: triage-${{ github.event.issue.number }}
  cancel-in-progress: false
```

2. Add the action step

   Check the repository out first, then call the action with your tokens and skill path.

```yaml
jobs:
  triage:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    permissions:
      contents: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false

      - uses: withastro/triagebot-action@v1
        with:
          read-token: ${{ secrets.GITHUB_TOKEN }}
          write-token: ${{ secrets.BOT_GITHUB_TOKEN }}
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          triage-skill: .agents/skills/triage
          bot-logins: my-bot-username
```

3. Choose a provider

   Exactly one provider credential is required: anthropic-api-key, openai-api-key, or cloudflare-api-key together with cloudflare-account-id.

```text
# anthropic-api-key | openai-api-key | cloudflare-api-key + cloudflare-account-id
```

4. Write the triage skill

   The triage-skill input points at a directory in your repository describing how issues in this project should be reproduced and judged. That is where project-specific knowledge lives.

```text
.agents/skills/triage
```

## When to use it

- Work down a large open-issue backlog on a busy open-source repository
- Ask for a reproduction and close out issues that cannot be reproduced, without a maintainer doing it by hand
- Turn a verified fix into a pull request only after the original reporter confirms it
- Keep triage state auditable in labels rather than in an external service

## Version history

- 2026-08-04: Cloudflare and Astro open-sourced triagebot-action. On Astro's own repository it cut the open-issue count from more than 200 to about 30.