Sourcery GitHub Integration: Automated PR Code Review Setup Guide

Why integrate Sourcery with GitHub

Manual code review is the biggest bottleneck in most development workflows. Pull requests sit in review queues for hours or days while senior engineers juggle their own feature work with the responsibility of reviewing other people’s code. When reviews finally happen, time pressure means reviewers skim the diff, approve with surface-level comments, and miss the subtle quality issues that compound into technical debt over months.

Sourcery addresses this by automating the initial review pass on every pull request. Once you install the Sourcery GitHub App, it analyzes each PR diff and posts inline review comments covering refactoring opportunities, readability improvements, code duplication, and potential bugs. For Python codebases specifically, Sourcery’s analysis goes deeper than most AI review tools - it understands idiomatic patterns like list comprehensions, context managers, generator expressions, and dataclasses, and suggests concrete transformations to make your code more Pythonic.

The Sourcery GitHub integration is the primary way most teams use Sourcery. While Sourcery also offers VS Code and PyCharm extensions for real-time analysis during development, the GitHub integration catches issues during the code review stage - the last checkpoint before code merges into your main branch. Teams that use both the IDE extension and the GitHub App get feedback at two stages of the workflow, which significantly reduces the number of quality issues that reach production.

This guide walks through every step of setting up the Sourcery GitHub integration - from installing the GitHub App to configuring custom rules, rolling out to your team, and troubleshooting common problems.

Prerequisites for Sourcery GitHub setup

Before you begin, make sure you have the following:

• A GitHub account (personal or organization) with at least one repository
• Admin or owner permissions on the repositories where you want to install Sourcery (required to authorize the GitHub App)
• At least one open pull request or the ability to create one for testing the integration
• A Sourcery account - you can sign up for free at sourcery.ai using your GitHub credentials

For private repositories, you will also need a paid Sourcery plan. The Pro plan at $10/user/month covers private repo PR reviews. The Team plan at $24/user/month adds security scanning and team analytics.

No CI/CD pipeline, Docker installation, or local tooling is required. Sourcery runs entirely on its own cloud infrastructure and connects to GitHub through its native App integration.

Step 1: Install the Sourcery GitHub App

The Sourcery GitHub App is the bridge between your repositories and Sourcery’s analysis engine. Installing it grants Sourcery the permissions it needs to read your code, listen for pull request events, and post review comments.

1. Navigate to github.com/apps/sourcery-ai in your browser
2. Click the green “Install” button
3. Select the GitHub account or organization where you want to install Sourcery
4. Choose your installation scope:
   • All repositories - Sourcery will have access to every repository in the account, including any repositories created in the future
   • Only select repositories - Choose specific repositories from a dropdown list; you can modify this selection later
5. Review the permissions Sourcery requests:
   • Read access to repository contents and metadata (to analyze your code)
   • Write access to pull request comments and checks (to post review feedback)
   • Webhook subscriptions for pull request events (to trigger reviews automatically)
6. Click “Install” to complete the process

For GitHub organizations, you may need an organization owner to approve the installation request. If you see a “Request” button instead of “Install,” the request is sent to your organization’s admin for approval. Coordinate with your admin to ensure the request is approved promptly.

After installation, verify it by going to your GitHub account settings. Navigate to Settings, then Applications, then Installed GitHub Apps. You should see Sourcery listed with the repositories you selected.

Step 2: Connect your Sourcery account

After the GitHub App is installed, link it to your Sourcery account to access the dashboard and configuration options.

1. Go to sourcery.ai and click “Sign In” or “Get Started”
2. Choose “Sign in with GitHub” to authenticate using the same GitHub account where you installed the App
3. Authorize Sourcery to access your GitHub identity when prompted by the OAuth screen
4. You land on the Sourcery dashboard, which shows your connected repositories and review activity

The dashboard is your central hub for managing the Sourcery GitHub integration. From here you can view recent review activity, check which repositories are active, access team analytics (on the Team plan), and manage billing. The dashboard also shows review statistics like the number of PRs reviewed, comments posted, and suggestions accepted by your team.

If you already had a Sourcery account from using the VS Code or PyCharm extension, your existing account automatically links to the GitHub App installation. There is no need to create a separate account or manage multiple logins.

Step 3: Configure repository settings

With the GitHub App installed and your account connected, configure how Sourcery reviews each repository. The primary configuration mechanism is the .sourcery.yaml file, which lives in the root of your repository.

Create a .sourcery.yaml file in your repository root with the following baseline configuration:

# .sourcery.yaml
refactor:
  skip: []

rules: []

metrics:
  quality_threshold: 25.0

github:
  labels: []
  ignore_labels:
    - sourcery-ignore
  request_review: author
  sourcery_branch: sourcery/{original_branch}

ignore:
  - .git
  - venv
  - .venv
  - node_modules
  - vendor
  - "*.min.js"
  - "*.lock"
  - "*.generated.*"
  - dist
  - build
  - coverage
  - __pycache__

Commit this file to your default branch (usually main or master). Sourcery reads this configuration file on every PR review and applies your settings immediately. No restart, reinstallation, or dashboard toggle is required after updating the config.

Understanding the configuration sections

refactor.skip lets you list specific refactoring rule IDs that Sourcery should not suggest. If you find certain refactoring suggestions irrelevant to your project, add their IDs here to suppress them permanently.

rules is where you define custom coding rules (covered in detail in the custom rules section below).

metrics.quality_threshold sets the minimum code quality score that Sourcery expects. Sourcery calculates a quality score for each function based on length, complexity, nesting depth, and working memory. Functions below this threshold receive review comments suggesting improvements.

github.ignore_labels allows you to skip Sourcery reviews on PRs that carry specific GitHub labels. Adding a label like sourcery-ignore to a PR tells Sourcery to skip it entirely. This is useful for automated PRs from dependency update bots where AI review adds no value.

github.request_review controls who Sourcery requests a review from when it finds issues. Setting it to author requests a review from the PR author. Setting it to none disables review requests.

ignore lists files and directories that Sourcery should skip during analysis. This reduces noise by preventing Sourcery from reviewing generated code, dependencies, build artifacts, and other files where automated suggestions are unhelpful.

Step 4: Trigger your first automated PR review

With the installation and configuration complete, it is time to see Sourcery in action on a real pull request.

1. Create a new branch in one of your enabled repositories
2. Make a code change - add a function, refactor existing logic, or fix a bug
3. Push the branch and open a pull request targeting your default branch
4. Wait one to three minutes for Sourcery to complete its analysis

Sourcery posts its feedback directly on the pull request as inline review comments. Each comment appears on the specific line of code it refers to, just like comments from a human reviewer. A typical Sourcery review includes:

• Refactoring suggestions with concrete code transformations showing the original code and the improved version side by side
• Code quality observations highlighting functions that exceed complexity thresholds or have deep nesting
• Readability improvements suggesting clearer variable names, simplified conditionals, or more idiomatic patterns
• Duplicate code detection flagging sections that share logic with other parts of the codebase

For Python files, Sourcery’s suggestions are particularly detailed. It detects opportunities to use list comprehensions instead of loops, replace manual resource handling with context managers, simplify conditional chains with early returns, and convert verbose class definitions to dataclasses. These are not generic AI suggestions - they are specific, compilable transformations based on Sourcery’s understanding of Python idioms.

If you do not see any review comments within five minutes, check the troubleshooting section at the end of this guide.

Step 5: Configure PR review behavior

Beyond the basic .sourcery.yaml settings, you can fine-tune how Sourcery behaves during PR reviews using several GitHub-specific configuration options.

Controlling review scope with labels

Use the github.ignore_labels setting to skip reviews on specific types of PRs:

github:
  ignore_labels:
    - sourcery-ignore
    - dependencies
    - automated
    - chore

This is particularly useful for dependency update PRs created by Dependabot or Renovate. These PRs typically change lock files and version numbers, and Sourcery’s code quality feedback is not relevant to them. Adding the appropriate label to your bot’s PR template ensures Sourcery skips them automatically.

Setting quality thresholds

The metrics.quality_threshold value determines how aggressively Sourcery flags functions for improvement:

metrics:
  quality_threshold: 25.0

The quality score ranges from 0 to 100, with higher scores indicating better code. A threshold of 25.0 is the default and flags only the most problematic functions. Raising it to 40.0 or 50.0 increases the number of suggestions. Lowering it to 15.0 reduces comments to only severe quality issues.

Start with the default of 25.0 and adjust based on your team’s feedback. If developers find the comments too noisy, lower the threshold. If they want more thorough analysis, raise it.

Handling Sourcery’s branch suggestions

Sourcery can create branches with its suggested fixes applied, making it easy to accept refactoring suggestions with a single merge. The github.sourcery_branch setting controls the naming pattern for these branches:

github:
  sourcery_branch: sourcery/{original_branch}

When a developer accepts a Sourcery suggestion, Sourcery creates a branch named after the original branch with a sourcery/ prefix. The developer can then merge the Sourcery branch into their feature branch to apply the fix. This workflow keeps the original branch clean and gives developers full control over which suggestions to accept.

Step 6: Write custom rules

Custom rules are the most powerful feature of the Sourcery GitHub integration. They let you encode your team’s specific coding standards as automated checks that run on every PR.

Python AST-based rules

For Python projects, Sourcery supports pattern-based rules that match against the abstract syntax tree (AST). Here is an example that catches a common anti-pattern - using a bare except clause:

rules:
  - id: no-bare-except
    description: Do not use bare except clauses. Catch specific exceptions instead.
    pattern: |
      try:
        ...
      except:
        ...
    replacement: |
      try:
        ...
      except Exception:
        ...

And another example that enforces the use of pathlib instead of os.path:

rules:
  - id: use-pathlib
    description: Use pathlib.Path instead of os.path for file path operations.
    pattern: os.path.join(${args})

Natural language coding guidelines

For non-Python languages or for higher-level architectural guidelines, Sourcery supports natural language rules. These are instructions written in plain English that Sourcery’s LLM-powered layer interprets during review:

rules:
  - id: api-error-handling
    description: All API endpoint handlers must return structured error responses with HTTP status codes and error codes. Never return raw exception messages to the client.
    language: all
    tags:
      - security
      - api

  - id: require-type-annotations
    description: All public functions must include type annotations for parameters and return values. Use Optional for parameters that can be None.
    language: python
    tags:
      - quality

Natural language rules are less precise than AST-based pattern rules, but they cover scenarios that pattern matching cannot express - like architectural conventions, security policies, and domain-specific requirements.

Organizing rules for larger teams

As your rule set grows, keep the .sourcery.yaml file organized by grouping rules with tags and adding clear descriptions. Sourcery includes the rule description in its review comments, so developers understand not just what the rule flags but why it exists. This turns your .sourcery.yaml file into living documentation of your team’s coding standards.

For a deeper dive into Sourcery’s capabilities, see the full Sourcery review.

Step 7: Roll out Sourcery to your team

A successful team rollout requires communication and a gradual approach. Dropping an AI reviewer onto every repository without context leads to confusion, distrust, and developers ignoring or dismissing all automated feedback.

Start with a pilot

Install Sourcery on one or two repositories first. Choose repositories with active development and a team that is open to trying new tools. Let the pilot run for one to two weeks before expanding.

Communicate the purpose

Send a brief message to your team explaining what Sourcery does and setting expectations:

• Sourcery will post AI-generated review comments on pull requests
• The comments are advisory, not blocking - developers should use their judgment about which suggestions to accept
• Sourcery’s feedback complements human review rather than replacing it
• The team’s feedback on noisy or unhelpful comments is valuable and will be used to tune the configuration

Adjust configuration based on feedback

After the pilot period, review your team’s experience:

• Are developers finding the refactoring suggestions useful?
• Are there recurring suggestions that everyone dismisses? Add those to refactor.skip
• Is the quality threshold too aggressive or too lenient? Adjust metrics.quality_threshold
• Are certain files generating noise? Add them to the ignore list

Expand gradually

Once the configuration is tuned and the pilot team is comfortable, expand to additional repositories. Avoid enabling all repositories at once. Roll out in batches of five to ten repositories, monitoring each batch for unexpected issues before proceeding.

For teams evaluating Sourcery pricing at scale, the Team plan at $24/user/month is typically the right choice because it includes analytics that help you measure the impact of automated review across your organization.

Refactoring suggestions in practice

Sourcery’s refactoring engine is what distinguishes it from generic AI code review tools. Instead of posting vague advice like “consider simplifying this function,” Sourcery shows you the exact transformation with before and after code.

Example: Loop to list comprehension

Sourcery detects loops that build lists and suggests list comprehensions:

# Before
results = []
for item in data:
    if item.is_valid():
        results.append(item.value)

# After (Sourcery suggestion)
results = [item.value for item in data if item.is_valid()]

Example: Nested conditionals to guard clauses

Sourcery identifies deeply nested conditionals and suggests early returns:

# Before
def process(user):
    if user is not None:
        if user.is_active:
            if user.has_permission("admin"):
                return perform_action(user)
    return None

# After (Sourcery suggestion)
def process(user):
    if user is None:
        return None
    if not user.is_active:
        return None
    if not user.has_permission("admin"):
        return None
    return perform_action(user)

Example: Context manager usage

Sourcery suggests replacing manual resource management with context managers:

# Before
f = open("data.txt", "r")
content = f.read()
f.close()

# After (Sourcery suggestion)
with open("data.txt", "r") as f:
    content = f.read()

These suggestions are not just stylistic preferences. List comprehensions are faster than equivalent loops in CPython. Guard clauses reduce cognitive complexity and make functions easier to test. Context managers prevent resource leaks when exceptions occur. Sourcery’s suggestions improve both readability and correctness.

For a comparison of how Sourcery’s suggestions stack up against traditional linters, see Sourcery alternatives.

Integrating Sourcery with your existing workflow

Sourcery works alongside your existing development tools without conflicts. Here are common integration patterns:

Alongside linters and formatters

Sourcery complements deterministic linters like Ruff, Pylint, and ESLint. Linters enforce coding standards with fixed rules - line length, import ordering, naming conventions. Sourcery provides higher-level analysis - refactoring opportunities, complexity reduction, idiomatic patterns. Running both gives you comprehensive coverage without overlap because they operate at different abstraction levels.

Alongside other AI review tools

If you are already using a tool like CodeRabbit or GitHub Copilot for PR review, Sourcery can run alongside it. Each tool posts its own comments independently. Teams often find that Sourcery’s Python-specific suggestions complement the broader language coverage of general-purpose AI reviewers. There are no webhook conflicts or performance issues from running multiple review apps simultaneously.

With branch protection rules

You can add Sourcery as a required status check in your GitHub branch protection rules. This ensures that Sourcery has reviewed every PR before it can be merged. To set this up, go to your repository settings, navigate to Branches, select your protected branch rule, and add the Sourcery check to the list of required status checks.

Be cautious with this approach - making Sourcery a blocking check means PRs cannot merge if Sourcery’s service experiences downtime. Most teams use Sourcery as an advisory check rather than a required one.

Considering alternatives

While Sourcery is an excellent choice for Python-focused teams, it is worth knowing what else is available in the automated code review space.

CodeAnt AI ($24-40/user/month) is a strong alternative that bundles AI code review with static analysis, secret detection, infrastructure-as-code scanning, and DORA metrics in a single platform. CodeAnt supports GitHub, GitLab, Bitbucket, and Azure DevOps - broader platform coverage than Sourcery’s GitHub and GitLab support. For teams that want a single tool covering code quality, security, and engineering metrics rather than assembling a tool chain, CodeAnt AI is worth evaluating.

The key trade-off is specialization versus breadth. Sourcery provides deeper Python refactoring suggestions than CodeAnt AI or most other competitors. CodeAnt AI provides broader coverage across languages, security dimensions, and platform integrations. Your choice depends on whether Python depth or cross-cutting breadth matters more to your team.

For a comprehensive comparison of all available options, see our guide to the best AI code review tools.

Troubleshooting common issues

Sourcery is not posting review comments

If Sourcery does not review a pull request after installation, check the following:

1. App installation scope - Go to GitHub Settings, then Applications, then Installed GitHub Apps, and verify Sourcery has access to the specific repository. If you chose “Only select repositories” during installation, the repository may not be included.
2. Repository visibility - If the repository is private and you are on the free plan, Sourcery will not review it. Upgrade to Pro ($10/user/month) or Team ($24/user/month) for private repo support.
3. PR labels - If your PR carries a label listed in github.ignore_labels in your .sourcery.yaml, Sourcery skips the review intentionally.
4. File exclusions - If every file changed in the PR matches a pattern in your ignore list, Sourcery has nothing to review.
5. Webhook delivery - Check GitHub’s webhook delivery logs at Settings, then Webhooks for the Sourcery App. Failed deliveries indicate a connectivity issue between GitHub and Sourcery’s servers.

Sourcery comments are too noisy

If Sourcery posts too many low-value comments:

1. Lower the metrics.quality_threshold to reduce the number of functions flagged
2. Add overly chatty rule IDs to refactor.skip
3. Add generated files, test fixtures, and vendor directories to the ignore list
4. Sourcery learns from dismissed comments over time - consistently dismissing a specific type of suggestion trains it to deprioritize that pattern

Sourcery conflicts with other tools

Sourcery does not conflict with other GitHub Apps or CI checks at a technical level. If you see duplicate or contradictory comments from Sourcery and another tool, it is because both tools independently flagged the same code. This is not a conflict - it is redundancy. You can reduce it by configuring one tool’s scope to focus on areas where the other is weaker.

Configuration changes are not taking effect

Ensure your .sourcery.yaml file is committed to the default branch (usually main). Sourcery reads the configuration from the default branch, not from the PR’s feature branch. If you add a .sourcery.yaml in a PR, it will not take effect until that PR is merged.

Advanced configuration tips

Per-directory configuration

For monorepos or projects with distinct subsystems, you can place separate .sourcery.yaml files in subdirectories. Sourcery uses the nearest .sourcery.yaml file relative to each changed file. This lets you apply different quality thresholds, rules, and ignore patterns to different parts of your codebase.

Combining GitHub and IDE integration

For maximum coverage, use both the Sourcery GitHub App and the Sourcery VS Code extension. The VS Code extension catches issues in real time as you write code, reducing the number of issues that reach the PR stage. The GitHub integration serves as a safety net, catching anything missed during development and providing a second opinion in the context of the full PR diff.

This two-layer approach means developers get feedback at the earliest possible moment (during coding) and have a final quality check before merge (during review). Teams that use both layers report fewer review cycles and faster PR merge times compared to using either layer alone.

Automating configuration with templates

If you manage many repositories across an organization, create a template .sourcery.yaml file and use a script or GitHub Actions workflow to distribute it across repositories. This ensures consistent Sourcery configuration without manually updating each repo. When you change your team’s coding standards, update the template and redeploy.

Summary

Setting up the Sourcery GitHub integration takes under ten minutes and delivers immediate value on your next pull request. The process involves installing the GitHub App, connecting your Sourcery account, creating a .sourcery.yaml configuration file, and tuning the settings based on your team’s feedback.

Sourcery’s strength is its Python-specific refactoring engine, which provides concrete code transformations rather than vague suggestions. For teams writing primarily Python, the $10/user/month Pro plan is one of the best values in the AI code review space. For teams needing broader language coverage or additional capabilities like security scanning and DORA metrics, CodeAnt AI ($24-40/user/month) is worth evaluating as an alternative or complement.

The key to a successful rollout is starting small, communicating clearly with your team, and iterating on the configuration based on real feedback. Install Sourcery on one or two repositories, let it run for a week, adjust the settings, and then expand gradually. This approach builds developer trust and ensures the tool adds value rather than noise.