DeepSource GitHub Integration: Setup and Configuration Guide

What you will learn

This guide walks through every step of integrating DeepSource with GitHub - from creating your account and installing the GitHub App to configuring analyzers, transformers, and exclude patterns in .deepsource.toml. By the end, you will have DeepSource running automated static analysis on every push and pull request, posting inline comments with one-click Autofix suggestions directly on your GitHub PRs.

DeepSource is a static analysis platform with over 5,000 rules across 12+ languages, a sub-5% false positive rate, and automated code fixing capabilities. It integrates with GitHub through a native GitHub App - no CI/CD pipeline configuration, no GitHub Actions workflows, and no self-hosted infrastructure required. The integration takes under 10 minutes and works on both public and private repositories.

Whether you are an individual developer setting up DeepSource on a personal project or an engineering lead rolling it out across an organization, this guide covers the complete setup process, advanced configuration options, and troubleshooting steps for the most common issues.

For a broader overview of DeepSource’s features and capabilities, see our DeepSource review. For pricing details, check our DeepSource pricing breakdown.

Prerequisites

Before starting the integration, make sure you have the following in place.

• A GitHub account (personal or organization) with at least one repository you want to analyze
• Admin or owner permissions on the repositories where you plan to install DeepSource (required to authorize the GitHub App)
• Familiarity with the primary programming language used in your repository (you will need to select the right analyzer during configuration)
• A code editor for creating the .deepsource.toml configuration file

No additional infrastructure is needed. DeepSource runs entirely on its own cloud infrastructure. You do not need Docker, a CI/CD pipeline, API keys, or any local tooling beyond a text editor.

Step 1 - Sign up with GitHub

The fastest way to get started with DeepSource is to sign up directly with your GitHub account. This approach links your GitHub identity to your DeepSource account in a single step and avoids the need to manage separate credentials.

1. Navigate to deepsource.com in your browser
2. Click the “Sign Up” or “Get Started” button on the homepage
3. Select “Continue with GitHub” from the authentication options
4. GitHub will display an OAuth authorization page - review the permissions DeepSource is requesting:
   • Read access to your profile information and email address
   • Read access to your organization memberships (so DeepSource can show you repositories across your organizations)
5. Click “Authorize DeepSource” to grant access and complete the sign-up

After authorization, you land on the DeepSource dashboard. This is your control center for managing repositories, viewing analysis results, configuring team settings, and monitoring code health metrics across all connected projects.

If you belong to multiple GitHub organizations, DeepSource will display all of them in the dashboard. You can switch between organizations using the organization selector in the top navigation.

The sign-up process uses OAuth, which means DeepSource never receives or stores your GitHub password. You can revoke access at any time from your GitHub account settings under Applications.

Choosing the right plan

DeepSource offers several plans that affect what you can do after setup:

• Open Source plan (free) - covers public repositories with unlimited team members, 1,000 PR reviews per month, and 1,000 automated formatting runs per month
• Team plan ($24/user/month) - covers public and private repositories with unlimited analysis, unlimited Autofix, and bundled AI Review credits
• Enterprise plan (custom pricing) - adds self-hosted deployment, SSO/SCIM, IP restrictions, and dedicated support

For evaluation purposes, DeepSource offers a 14-day free trial of the Team plan with no credit card required. This gives you full access to all features including private repository analysis, so you can test the integration thoroughly before committing to a paid plan. See our DeepSource pricing guide for a detailed cost breakdown.

Step 2 - Activate your repository

After signing up, the next step is installing the DeepSource GitHub App and activating the repositories you want to analyze. The GitHub App is the mechanism that gives DeepSource access to your code and enables it to receive webhook events when you push commits or open pull requests.

1. From the DeepSource dashboard, click “Add Repository” or “Activate New Repository”
2. If this is your first time, DeepSource will prompt you to install the GitHub App. Click “Install GitHub App”
3. GitHub will display the App installation page showing the permissions DeepSource requires:
   • Read access to repository contents and metadata (so it can analyze your code)
   • Read and write access to pull requests and checks (so it can post review comments and status checks)
   • Webhook events for push, pull request, and check suite events (so it knows when to run analysis)
4. Choose your installation scope:
   • All repositories - DeepSource gets access to every repository in the account or organization, including repositories created in the future
   • Only select repositories - Choose specific repositories from a dropdown list. You can add more repositories later without reinstalling the app
5. Click “Install” to complete the GitHub App installation

After installation, return to the DeepSource dashboard. You will now see a list of all repositories the app has access to. Click “Activate” next to each repository you want DeepSource to analyze.

For organizations, the GitHub App installation may require approval from an organization owner. If you see a “Request” button instead of “Install,” the installation request will be sent to your organization administrators. Ask them to approve the request in the organization settings under Third-party access.

Once a repository is activated, DeepSource performs an initial full scan of the default branch. This baseline analysis identifies all existing issues in your codebase and establishes the starting point for tracking code health improvements over time.

Step 3 - Configure .deepsource.toml

The .deepsource.toml file is the heart of your DeepSource configuration. This file tells DeepSource which analyzers to run, which transformers to apply, and which files to exclude from analysis. Without this file, DeepSource cannot analyze your repository.

Create a file named .deepsource.toml in the root of your repository with the following structure:

version = 1

[[analyzers]]
name = "python"
enabled = true

  [analyzers.meta]
  runtime_version = "3.x"
  max_line_length = 100

[[analyzers]]
name = "javascript"
enabled = true

  [analyzers.meta]
  environment = ["nodejs"]

[[transformers]]
name = "black"
enabled = true

[[transformers]]
name = "prettier"
enabled = true

exclude_patterns = [
  "vendor/**",
  "**/generated/**",
  "**/migrations/**",
  "dist/**",
  "build/**",
  "**/node_modules/**",
  "**/*.min.js",
  "**/*.min.css"
]

Let me break down each section of this configuration.

Version

The version = 1 line is required and tells DeepSource which configuration schema version to use. Always set this to 1 - it is the current and only supported version.

Analyzers

Each [[analyzers]] block enables a specific language analyzer. The name field specifies the language, and enabled = true activates it. The optional [analyzers.meta] section provides language-specific settings.

Here are the available analyzers and their key meta options:

Analyzer	Name Value	Key Meta Options
Python	python	runtime_version, max_line_length
JavaScript	javascript	environment (nodejs, browser)
TypeScript	javascript	Same analyzer as JavaScript
Go	go	import_root
Ruby	ruby	No meta options
Java	java	runtime_version
Rust	rust	No meta options
C#	csharp	No meta options
Kotlin	kotlin	No meta options
PHP	php	No meta options
Scala	scala	No meta options
Swift	swift	No meta options

Note that TypeScript files are analyzed by the javascript analyzer - there is no separate TypeScript analyzer. The JavaScript analyzer automatically detects and analyzes both .js and .ts files.

Transformers

Transformers are automated code formatters. Each [[transformers]] block enables a specific formatter:

Transformer	Name Value	Languages
Black	black	Python
Prettier	prettier	JavaScript, TypeScript, CSS, HTML, JSON, Markdown
gofmt	gofmt	Go
gofumpt	gofumpt	Go (stricter than gofmt)
rustfmt	rustfmt	Rust
rubocop	rubocop	Ruby
standardrb	standardrb	Ruby
dotnet-format	dotnet-format	C#
Autopep8	autopep8	Python
isort	isort	Python (import sorting)
YAPF	yapf	Python
scalafmt	scalafmt	Scala
ktlint	ktlint	Kotlin
PHP CS Fixer	php-cs-fixer	PHP
Swift Format	swift-format	Swift

Transformers run as separate commits on your branches. When you trigger a transform run, DeepSource creates a commit with all formatting changes applied. This keeps formatting fixes separate from your feature work.

Exclude patterns

The exclude_patterns array uses glob syntax to skip files and directories from analysis. Common patterns to exclude include:

• vendor/** and **/node_modules/** - third-party dependencies
• **/generated/** and **/migrations/** - auto-generated code
• dist/** and build/** - build output
• **/*.min.js and **/*.min.css - minified assets
• **/fixtures/** and **/testdata/** - test data files

Excluding these paths reduces noise in your analysis results and speeds up scan times. DeepSource will not report issues in excluded files, and those files do not count toward your analysis usage limits.

Commit the .deepsource.toml file to your default branch (usually main or master) and push it to GitHub. DeepSource reads this file from the default branch and applies the configuration to all subsequent analysis runs.

Step 4 - Run the first analysis

Once the .deepsource.toml file is committed and pushed, DeepSource automatically triggers the first full analysis of your repository. You do not need to click anything or run any commands - the webhook from your push event tells DeepSource to start scanning.

Here is what happens during the first analysis:

1. DeepSource clones your repository into its analysis environment
2. It reads the .deepsource.toml configuration to determine which analyzers to run
3. Each enabled analyzer scans the relevant files in your codebase
4. Issues are categorized into five dimensions - bug risk, anti-pattern, performance, security, and style
5. Results appear on the DeepSource dashboard within a few minutes

The first analysis typically takes 2 to 5 minutes depending on the size of your codebase. Large repositories with hundreds of thousands of lines of code may take slightly longer, but DeepSource’s analysis engine is optimized for speed.

After the first analysis completes, visit the DeepSource dashboard and navigate to your repository. You will see:

• Issue count broken down by category (bug risk, anti-pattern, performance, security, style)
• Code health score calculated from the ratio of clean code to total code
• Issue details with file paths, line numbers, descriptions, and severity levels
• Autofix availability indicators showing which issues can be automatically fixed

Do not be alarmed if the first analysis reports a large number of issues. This is your baseline - it represents the accumulated technical debt in your codebase. From this point forward, DeepSource tracks trends and only flags new issues introduced in pull requests, so the noise drops significantly during daily development.

Step 5 - PR comments and Autofix

The real value of the DeepSource GitHub integration shows up in your pull request workflow. After the initial setup, every pull request you open or update triggers an incremental analysis that focuses specifically on the code you changed.

How PR analysis works

When you open a pull request or push new commits to an existing PR, the following sequence occurs:

1. GitHub sends a webhook event to DeepSource
2. DeepSource analyzes only the diff - the lines of code that changed in the PR
3. If new issues are detected, DeepSource posts inline comments directly on the affected lines in the GitHub PR interface
4. A summary check status appears on the PR showing whether the analysis passed or found new issues

Each inline comment includes:

• Issue category - bug risk, anti-pattern, performance, security, or style
• Issue description - a clear explanation of what the problem is and why it matters
• Severity level - critical, major, or minor
• Autofix button - when available, a one-click button that generates a fix commit

DeepSource only reports issues that are newly introduced in the PR. Pre-existing issues in untouched code are not flagged on the PR, which keeps the comments focused and actionable. This is a key difference from tools that dump all findings onto every PR regardless of what changed.

Using Autofix on pull requests

Autofix is one of DeepSource’s standout features. When DeepSource detects an issue that has a known automated fix, the inline comment includes an “Autofix” button. Clicking this button tells DeepSource to:

1. Generate the corrected code
2. Create a new commit on your PR branch with the fix applied
3. Push the commit to GitHub

The fix appears as a regular commit in your PR history. You can review the changes, approve them, or revert them just like any other commit. Autofix works for a wide range of issues across all supported languages, including unused imports, incorrect exception handling, missing type annotations, deprecated API usage, and common security patterns.

On the Team plan, Autofix usage is unlimited. On the Open Source plan, Autofix is available on a pay-as-you-go basis. For more details on Autofix capabilities, see our DeepSource Autofix guide.

Configuring check status behavior

DeepSource creates a GitHub check on each PR to indicate the analysis result. By default, the check reports success even if new issues are found - it serves as an informational signal rather than a blocking gate. You can configure this behavior in the DeepSource dashboard to make the check fail when new issues exceed a threshold, effectively creating a quality gate that prevents merging PRs that introduce too many problems.

Advanced configuration

Once you have the basic integration running, these advanced configuration options help you get more out of DeepSource.

Multiple analyzers for polyglot repositories

Most real-world repositories use more than one programming language. A typical web application might have a Python backend, a JavaScript frontend, and Go microservices. You can enable all the relevant analyzers in a single .deepsource.toml file:

version = 1

[[analyzers]]
name = "python"
enabled = true

  [analyzers.meta]
  runtime_version = "3.x"

[[analyzers]]
name = "javascript"
enabled = true

  [analyzers.meta]
  environment = ["nodejs", "browser"]

[[analyzers]]
name = "go"
enabled = true

  [analyzers.meta]
  import_root = "github.com/yourorg/yourrepo"

Each analyzer runs independently and only scans files matching its target language. Enabling multiple analyzers does not slow down analysis significantly because DeepSource parallelizes the work.

Transformer configuration for consistent formatting

Pair your analyzers with transformers to enforce consistent code formatting across your team. Transformers apply the same formatting that developers would get from running the formatter locally, but they ensure that no unformatted code ever lands on the default branch.

[[transformers]]
name = "black"
enabled = true

[[transformers]]
name = "prettier"
enabled = true

[[transformers]]
name = "gofmt"
enabled = true

When transformers are enabled, you can trigger a formatting run from the DeepSource dashboard or configure it to run automatically. The formatter creates a separate commit with all changes applied, keeping formatting noise out of your feature commits.

Fine-tuning exclude patterns

As your team uses DeepSource over time, you will discover files and directories that generate noise without providing value. Refine your exclude patterns iteratively:

exclude_patterns = [
  # Third-party code
  "vendor/**",
  "**/node_modules/**",
  "third_party/**",

  # Generated code
  "**/generated/**",
  "**/*.pb.go",
  "**/*_generated.go",
  "**/migrations/**",

  # Build artifacts
  "dist/**",
  "build/**",
  ".next/**",
  "out/**",

  # Minified assets
  "**/*.min.js",
  "**/*.min.css",

  # Test fixtures and snapshots
  "**/fixtures/**",
  "**/testdata/**",
  "**/__snapshots__/**",

  # Documentation
  "docs/**"
]

Each excluded path reduces the total issues reported and makes the remaining findings more relevant. Review your exclude patterns monthly and add new patterns when you notice recurring false positives from specific directories.

Monorepo support

For monorepo setups where multiple services or packages live in a single repository, DeepSource analyzes the entire repository as one unit. The exclude patterns become especially important in monorepos - you can exclude individual services from analysis if they use a language that DeepSource does not support, or if they have their own separate analysis pipeline.

If different parts of your monorepo use different language versions or settings, use the analyzer meta configuration to set the broadest compatible settings. For example, set runtime_version = "3.x" for Python to cover all Python 3.x code in the repository.

Troubleshooting

If your DeepSource GitHub integration is not working as expected, work through these common issues in order.

DeepSource is not analyzing your repository

1. Check the GitHub App installation. Navigate to your GitHub organization or personal account settings, then to Applications and Installed GitHub Apps. Verify that DeepSource is listed and has access to the target repository.
2. Check repository activation. Log in to the DeepSource dashboard and verify that the repository shows as activated. A repository can have the GitHub App installed but not be activated for analysis.
3. Check the .deepsource.toml file. The file must exist in the repository root on the default branch (usually main). If it is only on a feature branch, DeepSource will not detect it.
4. Validate the TOML syntax. A single syntax error in .deepsource.toml prevents DeepSource from reading the configuration. Use a TOML validator to check for indentation errors, missing quotes, or incorrect bracket nesting.
5. Verify at least one analyzer is enabled. The .deepsource.toml file must contain at least one [[analyzers]] block with enabled = true. Without an enabled analyzer, DeepSource has nothing to run.
6. Check webhook deliveries. In your GitHub repository settings, navigate to Webhooks and check the recent deliveries for the DeepSource webhook. Failed deliveries with 4xx or 5xx response codes indicate a connectivity issue.

DeepSource reports too many issues

1. Add exclude patterns for vendor directories, generated code, build output, and other files that should not be analyzed
2. Focus on one analyzer at a time - if you enabled all 12 analyzers, start by enabling only the primary language analyzer and add others gradually
3. Use the dashboard filters to focus on high-severity issues (critical and major) and temporarily hide minor style violations
4. Remember that the first analysis is the baseline - the daily noise is much lower because DeepSource only flags new issues on PRs

PR comments are not appearing

1. Check that the GitHub App has write access to pull requests. If the app was installed with restricted permissions, it may not be able to post comments.
2. Verify the PR changes files covered by an enabled analyzer. If you changed only Markdown files but only have a Python analyzer enabled, DeepSource has nothing to analyze.
3. Check whether the PR introduced new issues. DeepSource only comments on newly introduced issues. If all the code in the PR is clean, there will be no comments - which is the expected behavior.
4. Look at the check status on the PR. Even if there are no inline comments, DeepSource should create a check status indicating that analysis completed successfully.

TOML configuration errors

The most common .deepsource.toml mistakes include:

• Wrong file name - it must be exactly .deepsource.toml, not deepsource.toml or .deepsource.yaml
• Missing version field - the version = 1 line is required at the top of the file
• Incorrect analyzer names - use lowercase names like python, javascript, go - not Python, JavaScript, or Golang
• Wrong bracket syntax - analyzers use double brackets [[analyzers]] for the array-of-tables syntax; single brackets [analyzers] will cause a parse error
• Invalid exclude patterns - glob patterns must use forward slashes even on Windows; backslashes cause parse failures

Alternatives to DeepSource for GitHub integration

If DeepSource does not fit your requirements, several alternatives provide similar GitHub integration with different strengths.

CodeAnt AI at $24-40/user/month offers AI-powered code review that goes beyond static analysis rules. CodeAnt AI provides natural language feedback on pull requests, catching logical errors and design issues that rule-based tools miss. It integrates with GitHub through a native app and provides contextual suggestions based on your codebase’s patterns and conventions.

SonarQube is the industry standard for code quality with over 6,500 rules across 35+ languages. SonarQube’s GitHub integration works through GitHub Actions or its own CI scanner, and it provides quality gate enforcement that can block PR merges when quality thresholds are not met. The Community Build is free for self-hosting. For a detailed comparison, see our best code quality tools roundup.

Codacy supports 40+ languages with multi-engine analysis. Its GitHub integration is similar to DeepSource - install the GitHub App, select repositories, and receive PR comments. Codacy’s Team plan starts at $18/dev/month, making it slightly cheaper than DeepSource for straightforward code quality analysis.

Semgrep focuses on security analysis with custom rule authoring. Its GitHub integration works through the Semgrep GitHub App and CI pipeline integration, posting inline PR comments for security findings. The open-source engine is completely free, and the cloud platform is free for teams up to 10 contributors.

For a comprehensive comparison of all options, see our DeepSource alternatives guide.

Conclusion

Integrating DeepSource with GitHub gives your team automated static analysis on every commit and pull request without any CI/CD configuration overhead. The setup process follows a straightforward path - sign up with GitHub, install the GitHub App, activate your repositories, and commit a .deepsource.toml configuration file. From that point forward, DeepSource analyzes every code change and posts actionable inline comments with one-click Autofix directly in your GitHub PR workflow.

The key to getting maximum value from the integration is investing time in the configuration. Start with a single analyzer for your primary language, add exclude patterns for directories that generate noise, and expand to additional analyzers and transformers as your team gets comfortable with the tool. Review the reported issues weekly during the first month to identify patterns - if certain issue categories are consistently irrelevant to your codebase, adjust your configuration accordingly.

For teams that need broader capabilities than static analysis alone, combining DeepSource with an AI-powered review tool like CodeAnt AI provides both deterministic rule-based checking and contextual AI feedback. The two layers complement each other - DeepSource catches the issues that rules can detect reliably, while AI review catches the logical errors, design problems, and edge cases that no rule can cover.

Whether you are a solo developer improving code quality on personal projects or an engineering lead establishing quality standards across an organization, the DeepSource GitHub integration provides a solid foundation for automated code analysis that scales with your team.