Issue to Pull Request Automation

Use Issue to Pull Request automations when you want Agent Canvas to watch your issue tracker for implementation-ready issues and automatically create pull requests with the requested changes.

​

What It Does

Issue to Pull Request automations monitor your issue tracker (GitHub Issues, GitLab Issues, Jira, or Linear) for issues marked as ready for implementation. When an issue is labeled or moved to an implementation-ready state, the automation:

1. Reads the issue — Fetches the issue title, description, acceptance criteria, and any linked dependencies
2. Starts an agent conversation — Launches an independent OpenHands agent that implements the requested change
3. Creates a branch — The agent clones the repository, creates a feature branch, and implements the change
4. Tests the changes — Runs tests to verify the implementation works
5. Opens a pull request — Creates a PR with a summary of changes and links back to the original issue
6. Updates the issue — Posts progress updates and the PR link back to the issue tracker

​

Available Combinations

Issue to Pull Request automations are available for the following combinations:

​

GitHub Issues → Source Control

​

GitLab Issues → Source Control

​

Jira → Source Control

​

Linear → Source Control

​

Common Setup Steps

All Issue to Pull Request automations follow a similar setup pattern:

​

Prerequisites

Before setting up an Issue to Pull Request automation, make sure you have:

• Agent Canvas installed and running with a configured backend
• LLM configured for the backend that will run the automation
• Issue tracker access — API token or OAuth connection to your issue tracker
• Source control access — Personal access token or SSH keys for your code repository
• Agent profile (recommended) — A saved agent profile with appropriate secrets and tools
• Git available in the automation runtime environment

​

General Setup Process

1. Connect integrations
   • Set up MCP servers or save API tokens for your issue tracker (GitHub, GitLab, Jira, or Linear)
   • Set up MCP servers or save API tokens for your source control system
   • Ensure tokens have the required permissions (see Permissions below)
2. Configure the automation
   • Navigate to Automate in Agent Canvas
   • Find the appropriate Issue to PR workflow for your combination
   • Configure the automation settings:
     • Repositories — Select which repositories to monitor
     • Trigger label or state — Define what marks an issue as implementation-ready
     • Branch prefix — Set how feature branches should be named (e.g., openhands/issue)
     • Pull request mode — Choose whether PRs open as drafts or ready for review
     • Schedule — Set how often to check for new issues (default: every 15 minutes)
3. Select an agent profile
   • Choose a saved agent profile that has access to the necessary secrets
   • The profile should include the tokens needed for both the issue tracker and source control
4. Review and deploy
   • Review the automation configuration
   • Deploy the automation
5. Test the automation
   • Apply the trigger label to a test issue
   • Verify the agent starts working on the issue
   • Check that a pull request is created successfully
   • Confirm the issue is updated with progress and the PR link

​

Permissions

​

Issue Tracker Permissions

​

Source Control Permissions

​

How It Works

​

Polling and State Management

Issue to Pull Request automations run on a schedule (typically every 15 minutes, configurable). Each run:

1. Polls the issue tracker — Queries for issues with the configured trigger label or state
2. Deduplicates — Tracks which issues have already been processed using persistent state
3. Dispatches conversations — Starts one independent agent conversation per new issue
4. Caps parallel work — Limits how many conversations start per poll to prevent overwhelming the system

​

Agent Conversation Flow

For each issue, the automation starts a fresh agent conversation that:

1. Fetches issue details — Reads the full issue description and any discussion
2. Clones the repository — Creates a local copy of the default branch
3. Creates a feature branch — Names it using the configured prefix and issue number (e.g., openhands/issue-42)
4. Implements the change — Writes or modifies code based on the issue requirements
5. Runs tests — Verifies the implementation with the project’s test suite
6. Commits and pushes — Creates commits with descriptive messages and pushes to the feature branch
7. Opens a pull request — Creates a PR titled [#42] <issue title> with a summary and Closes #42 in the body
8. Posts to the issue — Adds a comment with the PR link

The agent conversation has access to:

• The issue tracker API (to read issues and post comments)
• The source control API (to push branches and create PRs)
• Only the secrets explicitly included in the agent profile (principle of least privilege)

​

Re-running Failed Attempts

To re-run an automation on an issue:

1. Remove the trigger label from the issue
2. Re-apply the trigger label

The automation will treat it as a new request and create a fresh branch and conversation.

​

Security Considerations

Issue to Pull Request automations handle content from external sources (issue descriptions, comments) and execute code changes. Keep these security practices in mind:

• Use agent profiles — Explicitly define which secrets the spawned conversation can access
• Limit token scope — Grant tokens only the minimum permissions needed
• Review PRs before merging — Open PRs as drafts by default so they undergo code review
• Monitor automation runs — Check the automation activity regularly for unexpected behavior

​

Verification

After the automation is deployed:

1. Open Automate in Agent Canvas
2. Verify the automation appears and is enabled
3. Check the automation details for correct configuration
4. Apply the trigger label to a test issue
5. Monitor the automation run in the activity log
6. Verify:
   • The agent conversation starts
   • A feature branch is created
   • Tests pass (if applicable)
   • A pull request is opened
   • The issue is updated with progress and the PR link

​

Troubleshooting

​

Common Issues

​

Customization Options

When setting up an Issue to Pull Request automation, you can customize:

• Trigger label — The label that marks issues as ready for implementation (default: openhands)
• Branch prefix — How feature branches are named (default: openhands/issue)
• Pull request mode — Whether PRs open as drafts or ready for review (default: draft)
• Check frequency — How often to poll for new issues (default: every 15 minutes)
• Repository selection — Which repositories to monitor (can monitor multiple repos)
• Agent profile — Which saved profile runs the implementation conversations

​

Related Guides

• Setup a Pre-built Automation
• GitHub PR Review Assistant
• GitHub Repository Monitor
• Managing Automations
• Agent Profiles
• Customize and Settings