How to Configure Sweep to Turn GitHub Issues into Automated Bug Fix Pull Requests

Turning bug reports into production-ready pull requests is one of the highest-friction bottlenecks for software engineering teams. Routine bug fixes—such as handling null pointer checks, updating deprecations, correcting regex patterns, and adding missing regression tests—often sit in backlogs for weeks because senior engineers are occupied with high-leverage product features.

Sweep was created to bridge this exact gap as an autonomous AI software developer. Installed as a GitHub App, Sweep monitors your issue tracker, understands the repository through semantic and lexical code indexing, generates multi-file code modifications, and submits structured pull requests. Furthermore, it closes the loop by parsing CI test failures and reacting to inline human code reviews.

This guide provides a comprehensive, production-ready walkthrough on configuring Sweep within a software engineering workflow, crafting optimal issue prompts, tailoring sweep.yaml, enabling CI self-correction loops, and establishing engineering guardrails.

1. How the Sweep Issue-to-PR Workflow Operates

Before deploying configuration files, engineering teams must understand the lifecycle of an automated ticket:

1. Trigger Event: A developer or triage engineer opens a GitHub issue titled with the Sweep: prefix (e.g., Sweep: Fix KeyError when user metadata payload is missing), applies the sweep label, or mentions @sweepai.
2. Repository Context Retrieval: The Sweep webhook (on_ticket) queries the repository. It uses vector embeddings and abstract syntax tree (AST) chunking across tracked files to identify relevant functions, modules, and tests.
3. Execution Plan: Sweep posts an interactive comment outlining its proposed plan, listing specific files to modify, and detailing implementation logic.
4. Code Generation & Commits: Operating in an isolated branch (sweep/fix-...), Sweep writes the modifications according to repository rules.
5. Pull Request Submission: Sweep opens a Pull Request with an issue link (Fixes #<id>), a technical summary, and a checklist of changes.
6. Continuous Feedback:
   • CI Feedback Loop: If GitHub Actions integration is enabled (gha_enabled: true), Sweep inspects failing test logs and commits automated fixes.
   • Code Review: Engineers leave inline comments on the PR diff; Sweep interprets the feedback and pushes subsequent commits.

2. Installing and Connecting Sweep to GitHub

To configure Sweep for your organization:

1. Install the GitHub App: Navigate to the Sweep GitHub App installation page and select the repositories you want Sweep to access.
2. Grant Necessary Permissions:
   • Repository Contents (Read & Write): Required to read code and push branches.
   • Issues (Read & Write): Required to read issue descriptions, update issue labels, and post progress comments.
   • Pull Requests (Read & Write): Required to open PRs, read diffs, and respond to review comments.
   • Actions / Checks (Read): Required to inspect GitHub Actions logs when builds or tests fail.
3. Draft Status: Decide whether Sweep should initially post PRs as Draft PRs (draft: true) to prevent automated notification noise on team channels before a triage engineer approves the direction.

3. Configuring Repository Rules with sweep.yaml

Sweep reads repository-level instructions from sweep.yaml (or .sweep/config.yaml) located in your repository root. A well-configured sweep.yaml prevents hallucinated imports, enforces styling and testing conventions, and protects critical files.

Production sweep.yaml Template

# sweep.yaml - Configuration for automated issue resolution

# Target branch that Sweep branches from and creates PRs against
branch: 'main'

# Open PRs as drafts (recommended for new team onboarding)
draft: false

# Enable Sweep to read GitHub Actions workflow failures and self-correct
gha_enabled: true

# Project overview to guide codebase understanding and context retrieval
description: >
  Backend REST API built with Python 3.10 and FastAPI.
  Database operations use SQLAlchemy 2.0 with PostgreSQL.
  All business logic resides in services/, models in models/, and endpoints in api/v1/.
  All imports must be absolute (e.g., `from services.auth import verify_token`).

# Directories and files Sweep must NEVER read or modify
blocked_dirs:
  - "deploy/"
  - "terraform/"
  - ".github/workflows/"
  - "migrations/"
  - "*.env*"
  - "security/"

# Sandbox commands executed in Sweep's isolated runner prior to PR creation
sandbox:
  install:
    - "poetry install --no-root"
  check:
    - "poetry run ruff check {file_path}"
    - "poetry run pytest tests/unit"

# Explicit coding guidelines injected into the agent's prompt
rules:
  - "Always add or update pytest unit tests for every bug fix in tests/."
  - "Never use wildcard imports (`from module import *`)."
  - "Use Pydantic v2 schemas for all request validation."
  - "Use structured logging via loguru; include exception tracebacks using logger.exception()."
  - "Do not alter database schema or create alembic migrations without explicit instructions."
  - "Maintain full type annotations across all function signatures."

Key Configuration Directives Explained

• branch: Defines the base branch for branch creation and PR targeting. If your team works on develop or a release branch, update this accordingly.
• blocked_dirs: Critical guardrail. Any path matching these substrings or globs is excluded from Sweep's file modifications. Protect CI configurations, secrets, infrastructure code, and database migrations.
• gha_enabled: When set to true, Sweep listens to GitHub Actions webhook events. If a unit test fails on Sweep's branch, Sweep analyzes the CI failure log, locates the failing assertion, and pushes a patch commit.
• rules: A list of strict instructions Sweep injects into its context. Rules ensure code consistency with your existing conventions, such as linting rules, preferred libraries, error handling patterns, and test frameworks.
• sandbox: If configured, Sweep runs dependency installation (install) and verification checks (check) in an isolated container to ensure code builds and passes linting before publishing a PR.

4. Writing Issue Descriptions That Yield High-Quality PRs

The quality of Sweep's pull request is directly proportional to the clarity and detail in the GitHub issue. While human developers can ask clarifying questions across Slack, an AI agent relies entirely on the repository index and the issue prompt.

The Anatomy of an Ideal Bug Report Issue

To get a one-shot fix from Sweep, structure the issue description with the following sections:

Title: Sweep: Fix 400 Bad Request on empty user metadata payload in /api/v1/profile

### Bug Description
When updating a user profile via `PUT /api/v1/profile`, submitting an empty `metadata` dictionary raises a ValidationError instead of setting default empty values.

### Steps to Reproduce
1. Send a PUT request to `/api/v1/profile` with body `{"metadata": {}}`.
2. Notice the API responds with HTTP 400 and detail `Value error, metadata must contain required fields`.

### Expected Behavior
Empty `metadata` should be accepted, initialized with default values (`{"theme": "light", "notifications": true}`), and saved cleanly.

### Relevant Code & Files
- `api/v1/profile.py`: `update_profile` endpoint handler.
- `schemas/profile.py`: `UserProfileUpdate` Pydantic model.
- `services/profile_service.py`: `save_profile_metadata` helper.

### Acceptance Criteria
- Fix validation in `schemas/profile.py` so empty dictionaries pass with default fallbacks.
- Add a unit test in `tests/unit/test_profile_api.py` testing an empty payload.
- Ensure all existing unit tests in `tests/unit/` pass.

Issue Title Triggers & Execution Modes

Sweep's issue parser (strip_sweep) recognizes specific title prefixes to alter execution behavior:

• Sweep: <title>: Standard issue processing.
• Sweep(sandbox): <title>: Forces isolated sandbox verification before opening the PR.
• Sweep(fast): <title>: Prioritizes rapid turnaround using faster LLM inference.
• Sweep(slow): <title>: Directs the agent to spend more iterations exploring dependencies and edge cases.
• Sweep(lint): <title>: Executes strict formatting and linting sweeps across modified files.
• Sweep(subissues): <title>: Instructs Sweep to decompose complex tickets into discrete sub-issues.

5. The Review and Iteration Loop

Once Sweep opens a pull request, the human engineering workflow begins:

[GitHub Issue] ──> Sweep triggers ──> PR Created ──> CI (GitHub Actions)
                                                           │
                        ┌──────────────────────────────────┴─────┐
                        ▼                                        ▼
                  CI Fails (gha_enabled)                    CI Passes
                        │                                        │
                        ▼                                        ▼
               Sweep auto-commits fix                      Human Code Review
                        │                                        │
                        └─────────► PR Updated ◄─────────────────┘
                                         │
                               (Developer comments:
                             "@sweepai refactor to use
                                helper function")

Inline PR Comments

Engineers do not need to pull the branch locally to make minor corrections. By commenting directly on PR lines:

@sweepai Use our existing DateUtils.formatIso() helper here instead of creating a new datetime formatter.

Sweep detects the comment webhook, parses the suggested change against the referenced diff line, applies the update, and pushes a new commit to the pull request.

Issue Regeneration

If the original issue description was flawed or the solution deviated from the intended design, developers can simply update the GitHub issue's title or description. Sweep recognizes issue updates and automatically regenerates the branch and pull request.

6. Engineering Guardrails and Production Best Practices

To integrate Sweep safely into professional software engineering pipelines, implement the following guardrails:

1. Mandatory Human Approval: Never configure auto-merge on pull requests created by Sweep. Maintain branch protection rules requiring at least one senior code review and passing CI checks.
2. Strict Blocked Directories: Block infrastructure-as-code directories (terraform/, k8s/), workflow definitions (.github/), database migration files (alembic/), and package lockfiles (package-lock.json, poetry.lock).
3. Scoped Task Sizing: Restrict Sweep tasks to bounded bug fixes, test coverage additions, and isolated refactorings. Avoid assigning architectural redesigns or vague business feature requests without precise specifications.
4. Comprehensive Test Suites: Sweep's self-healing loop depends entirely on test feedback. The stronger your unit and integration test coverage, the more effective Sweep is at catching regressions before human review.

References

• GitHub - sweepai/sweep: Sweep: AI coding assistant for JetBrains
• GitHub - sweepai/sweep: sweep.yaml configuration file
• GitHub - sweepai/sweep: sweepai/config/client.py
• GitHub - sweepai/sweep: sweepai/handlers/on_ticket.py
• GitHub - sweepai/sweep: sweepai/utils/str_utils.py
• sweepai · PyPI
• Launch YC: Sweep: JetBrains AI Coding Assistant | Y Combinator