Guide

How to Have AI Agents Automatically Pick Up GitHub Issues

Name: Fleet
Author: Fleet

The most labor-intensive part of running an AI dev team is task dispatch — deciding which agent should work on which issue and manually starting a session for each one. Fleet automates this through GitHub label watching: when a maintainer adds the ready label to an issue, the watcher detects it and dispatches the right agent without any additional action.

This guide shows how to configure Fleet's label watcher so that labeling a GitHub issue is the only human step required to put work into the agent's queue.

Before you start

Fleet initialized in your repository with `fleet init`
GitHub repository with write access to create and apply labels
At least one developer agent configured in `.fleet/config.yaml`
GitHub CLI (`gh`) authenticated

1

Create the required GitHub labels

Fleet's reactive chain relies on specific GitHub labels. Create them in your repository if they do not already exist. The critical ones are ready (work is ready to start), needs-review (PR is ready for review), approved (PR is approved), and shipped (work is merged and deployed).

gh label create ready --color 0075ca --description "Ready for agent pickup"
gh label create needs-review --color e4e669 --description "PR ready for review"
gh label create approved --color 0e8a16 --description "PR approved"
gh label create shipped --color 5319e7 --description "Shipped to production"

2

Configure a developer agent with ticket_ready subscription

The developer agent needs a ticket_ready subscription so the watcher knows to dispatch it when a ready label is detected. The watcher translates the GitHub ready label into a ticket_ready fabric event.

agents:
  - name: dev-1
    role: backend-developer
    department: engineering
    reports_to: tech-lead
    model: claude-sonnet-4-5
    subscribes_to: ticket_ready

3

Start the watcher to activate label monitoring

The watcher must be running for label changes to trigger agents. Start it with --supervised so it restarts automatically if it crashes. The watcher polls GitHub labels every 2 minutes.

fleet watcher start --supervised

# Verify it is running:
fleet watcher status

4

Label an issue to test the dispatch

Add the ready label to an issue. Wait up to 2 minutes for the watcher's next polling cycle. The watcher publishes a ticket_ready event, the subscription processor matches it to your developer agent, and the agent starts with the issue context in its environment.

# Label issue #23 as ready:
gh issue edit 23 --add-label ready

# Watch for the agent to start:
fleet status
# Then check the log:
fleet log --type decision --since 10m

5

Verify the agent received the task context

When Fleet starts an agent via subscription, it sets FLEET_TRIGGER_EVENT and FLEET_TRIGGER_PAYLOAD environment variables in the tmux session. The agent's handbook prompt instructs it to read these variables to understand what triggered it and what issue to work on.

# Attach to the agent's session to inspect env:
fleet agent attach dev-1
# In the session, the agent has access to:
# $FLEET_TRIGGER_EVENT = "ticket_ready"
# $FLEET_TRIGGER_PAYLOAD = {"issue": 23, "title": "...", ...}

6

Handle the label requirement gate

By default, some Fleet configurations require a fleet label in addition to ready before an issue enters the agent queue. This prevents every labeled issue from being picked up if you use ready for other purposes. Check your config's required_label setting and add the fleet label to issues you want agents to handle.

# If your config requires a fleet label:
gh issue edit 23 --add-label fleet
gh issue edit 23 --add-label ready

# Or configure the watcher to watch only one label:
# (check your .fleet/config.yaml watcher settings)

Common pitfalls

The watcher polls every 2 minutes. There will always be a delay between adding a label and the agent starting. This is by design — polling avoids GitHub webhook infrastructure complexity. If you need sub-minute dispatch, use `fleet task assign` directly.
Work-in-progress labels use a 15-minute dedup window to prevent duplicate dispatch. If you remove and re-add `ready` on the same issue within 15 minutes, the second label may be silently ignored. Wait for the window to expire before retrying.
If you add the `ready` label to issues that are not fully specified (no description, no acceptance criteria), the agent will start but may produce poor output or get stuck. Front-load the issue with enough context for the agent to proceed without asking questions.
Issues assigned to a specific agent via GitHub's assignee field do not automatically route to that Fleet agent. Fleet's routing is purely label and event driven. Use `fleet task assign` for targeted dispatch by agent name.

When Fleet is the right tool

Label-driven agent dispatch is the right pattern when your team already uses GitHub issues as the primary work queue and you want to minimize the overhead of operating the AI layer. It works best when issues are well-specified enough that an agent can start without clarification. If your issues are high-level epics that require decomposition before coding can start, add a planning agent to the chain that decomposes the issue before dispatching the developer.

Frequently asked questions

Can I assign specific issues to specific agents?

Not through labels alone. Labels trigger agents by role, not by name. For targeted dispatch — sending a specific issue to a specific named agent — use `fleet task assign <agent-name> "<task description>"`. You can also use team-specific subscriptions to route by department.

What happens if two issues get the ready label at the same time?

Fleet processes them in order. If you have concurrency limits set, the second issue waits in the subscription queue until the first agent finishes or a second agent slot opens. If you have multiple developer agents, both can be dispatched simultaneously.

Run your first agent fleet

One binary. Five minutes. See every agent, coordinate every handoff, and keep a full audit trail of what your fleet did.

See how it works Install Fleet