GitHub Integration

Overview

The GitHub integration allows customers to:

1. Reduce time to resolution by easily checking potentially relevant pull requests in the context of an incident via PRs overlaid on incident charts. See more under Pull requests documentation.

2. Prevent bad data changes before they reach production using MC Prevent — Monte Carlo's suite of agents that surfaces data observability context at every stage of the development lifecycle.

3. Get context on tables via reviewing recent pull request history on the asset page (requires dbt integration).

GitHub Integration Setup

You can set up the integration by installing an instance of the official MC GitHub App for your organization. If you manage multiple GitHub organizations with code relevant to data collected by MC, you need to install the app for each organization.

Permissions required:

• Read access to administration and metadata
• Read and write access to issues and pull requests
• Read and write access to repository checks
• Read-only access to repository contents

Write access to issues and pull requests is limited to pull request comments and check runs, used by the PR Agent and CI Agent. Read access to contents is required to read the PR diff.

Steps:

1. In Monte Carlo, go to Settings → Integrations
2. Click Add
3. Under the Code Repositories section, select GitHub
4. In the GitHub UI, select:
   • The organization
   • Optionally, the specific repositories accessible to MC
5. Click Install and Authorize
6. You will be redirected back to Monte Carlo

If you have the owner role in GitHub, the integration will appear immediately in Settings → Integrations → Notifications and Collaborations.

If you are not the owner, a request is sent to the GitHub account owner for approval. The integration will appear once they approve.

Once set up, MC will start collecting pull requests that merged after the integration setup time. MC does not have access to historical PRs.

The PR Agent is enabled automatically when you install the GitHub App. See the Repo allowlist section below to control which repos it comments on.

dbt Integrations

Note: Having a dbt integration configured is no longer required for the GitHub integration, but having both provides information for mapping between dbt models and assets for code changes. The PR Agent's validation notebook generation also requires a dbt integration.

Follow docs here to set up your dbt integration.

dbt Cloud

The setup should be automatic. Follow the GitHub Integration Setup steps below to enable.

For legacy data collector customers before v14050, the remote location of dbt projects needs to be configured manually (see dbt Core below).

dbt Core

For dbt Core integrations, the remote location of each dbt project needs to be provided. Go to the Integrations settings page once you have completed the GitHub Integration setup. Under Notifications and Collaboration, the GitHub integration row will show an alert requiring more GitHub information. Click into the editing drawer via the alert or pen icon to input the missing remote URL.

Alternatively, configure the remote location of each dbt project using the GraphQL API:

mutation updateDbtProjectInfo($uuid: UUID!, $remoteUrl: String, $subdirectory: String) {
    updateDbtProjectInfo(uuid: $uuid, remoteUrl: $remoteUrl, subdirectory: $subdirectory) {
        project {
            uuid
        }
    }
}

Parameters:

PR Agent

The PR Agent reviews every pull request in your allowlisted repos and posts a risk assessment comment. It is enabled automatically when you install the GitHub App — no feature flag required.

The PR Agent evaluates:

• Which Monte Carlo-monitored tables are affected by the PR's file changes
• Downstream lineage and blast radius, including Key Assets
• Active alerts on impacted tables (filtered to open alerts only)
• Monitor coverage gaps

Triggers:

• Automatically when a PR is opened or updated in an allowlisted repo
• On demand by commenting mc review on any PR (case-insensitive)

Enabling and disabling the PR Agent

The PR Agent is enabled automatically when you install the GitHub App. To enable or disable it later for your account, go to Settings → AI Agents and toggle PR Agent.

When the PR Agent is disabled, Monte Carlo will fall back to the legacy impact assessment comment (if that feature is enabled on your account) instead of the PR Agent comment.

Repo allowlist

You control which repos the PR Agent comments on via a per-installation allowlist. By default, existing customers have their allowlist seeded with the repos that already have dbt projects connected to Monte Carlo.

To view or change the allowlist:

1. Go to Settings → Integrations → GitHub
2. Click into the organization you want to configure
3. In the Edit connection drawer, open the Settings tab
4. Add or remove repos under Enable PR Agent for these repos

If the allowlist is empty, the PR Agent will not post on any PR in that installation — by design. Commenting mc review on a non-allowlisted repo has no effect.

Programmatic access is available via the experimental getPrAgentConfig query and updatePrAgentConfig mutation on the GraphQL API.

What the PR comment looks like

The PR Agent posts a structured comment with the following sections:

1. Risk title — PR Impact Assessment — High | Medium | Low Risk, with a one-line summary of what changed and how much is at risk.
2. Change groups — the PR is split into groups of related changes. Related dbt models and their downstream children are merged along lineage; the same model in multiple schemas (e.g. prod/staging) is merged into one group. Groups are sorted by downstream impact within each risk tier.
3. Per-group details — each group shows:
   • Change type (column added, column dropped, query/filter change, etc.)
   • Directly impacted assets (first 5 visible, the rest in a collapsible section)
   • Downstream assets (first 5 visible, up to 30 in a collapsible section)
   • Active alerts grouped by type (e.g. "6 alerts — 3 freshness, 2 schema, 1 volume")
   • A ⭐ marker next to any Key Asset
   • A (diff) link anchored to the relevant file in the PR
4. Validation Notebook — for PRs that modify dbt model SQL files, the PR Agent generates a SQL Notebook with parameterized validation queries (NULL-rate checks, before/after comparisons, data profiling for new models). The comment includes a model count, query count, and a change-type-aware summary alongside the link.
5. Before merging checklist — a PR-specific list of concrete actions to verify before merging.
6. Feedback prompt — react with 👍 or 👎 on the bot comment to send feedback to Monte Carlo. Reactions are collected when the PR closes.

Note: For very large PRs (diffs over roughly 150K tokens / 600K characters), the diff is truncated before analysis. The PR Agent notes this in the comment when it happens.

Missing permissions

If the GitHub App is missing the required contents:read permission on a repo, the PR Agent posts a "missing permissions" comment with a link back to these docs. Re-authorize the app in GitHub → Settings → Applications → Monte Carlo to grant the permission.

CI Agent

The CI Agent is an optional step you add to your CI pipeline (GitHub Actions or CircleCI). It evaluates the PR Agent's risk assessment and returns a pass, warn, or fail verdict as a GitHub Check Run.

When combined with GitHub branch protection rules, the CI Agent can block high-risk PRs from merging until they are reviewed or overridden.

PR Agent vs. CI Agent

The PR Agent runs automatically once the GitHub integration is installed — you get AI risk assessment comments on every PR with no extra configuration.

The CI Agent is the optional next step: add it to your CI pipeline if you want a formal check that can block merges based on the PR Agent's assessment. The PR Agent is a prerequisite — the CI Agent reads its assessment to produce a verdict.

Setup

Choose your CI platform:

• GitHub Actions — monte-carlo-data/mc-prevent-action
• CircleCI — monte-carlo-data/mc-prevent-orb

Each repository has full setup instructions, examples, and parameter documentation.

How it works

1. The CI Agent triggers on PR events (draft PRs are skipped).
2. It polls for the PR Agent's risk assessment (up to 5 minutes by default). If a cached verdict from a previous commit exists, it reuses it immediately.
3. It calls Monte Carlo's /ci/assess API with the PR metadata and any policy configuration.
4. Monte Carlo evaluates each assessed asset against a decision matrix and returns a per-asset verdict with an explanation.
5. The verdict is posted as an MC Prevent CI Gate Result GitHub Check Run (with a per-asset breakdown table) and a workflow step summary.

Decision matrix

Each data asset affected by the PR is evaluated against these rules (top-to-bottom, first match wins):

When a PR affects multiple assets, each is evaluated independently. The final verdict is the worst across all assets.

The CI Agent explains its verdict per-asset — what changed, downstream exposure, and what to verify — ending with a clear justification of the overall conclusion. The same explanation appears in both the CI job output and the Check Run.

Verdicts

Check runs vs. the CI job

The CI job can only report green or red. The MC Prevent CI Gate Result check run posted on the PR shows the full three-way state (green/grey/red) along with a per-asset breakdown table showing each asset's verdict and reason.

If you're configuring branch protection to gate merges, require the check run — not the CI job — so that warn can be distinguished from fail.

Configuration

The CI Agent's gate policy is controlled by the fail-on setting, which determines which verdicts cause the CI step to exit non-zero.

You can set this in two ways:

1. Monte Carlo UI (Settings > Integrations > CI Gate) — applies to all CI pipelines for the installation. This is the default when fail-on is not set in the CI configuration.
2. CI configuration (fail-on parameter) — overrides the UI setting for a specific pipeline.

When fail-on is not set in the CI configuration, the UI setting applies automatically. This means teams can change the policy from the Monte Carlo UI without modifying CI configuration files.

Other parameters

Migrating from fail-on-error: fail-on-error: false is equivalent to fail-on: none. fail-on-error: true is a no-op (defers to fail-on). The fail-on-error parameter still works for backward compatibility.

Override

Add the mc-override label to a PR to bypass the CI Agent. The verdict returns pass with a note that an override is active. The check run on the PR immediately flips to green — no commit or re-run needed. All overrides are logged for audit.

Progressive adoption

MC Prevent is designed so it never blocks your CI due to incomplete setup:

Limitations

• MC only collects PRs that merged after the integration setup time. Historical PRs are not available.
• Schema change monitors do not display GitHub pull requests.
• Pull request history on the asset page requires a dbt integration.
• Organizations using IP allowlists must add Monte Carlo's SaaS public IP address (see Account Information).
• Very large PRs (diffs over ~150K tokens / ~600K characters) are truncated before analysis; the PR Agent notes this in the comment when it happens.
• The PR Agent currently runs on GitHub only. GitLab and Azure DevOps PRs are supported for incident-chart PR overlays, but not for PR Agent reviews or the CI Agent gate.

FAQ

Q: I have a dbt Core integration and I'm not sure my remote URL and subdirectory are correct. What's the right format?

Remote URL should be one of:

• https://github.com/<org>/<repo>
• git://github.com/<org>/<repo>.git

Subdirectory should be the root directory of the dbt models within the repo, and is only needed if the dbt project is in a subdirectory. For example:

• Model path analytics/models/foo/bar.sql → subdirectory is analytics
• Model path models/foo/bar.sql → leave subdirectory empty

Q: I just set up the integration. Why don't I see pull requests showing up yet?

MC only collects PRs that merged after the integration setup time. It does not have access to historical PRs, so it may take a few hours or days for PRs to start appearing depending on how frequently your team merges.

Q: The PR Agent isn't commenting on one of my repos. Why?

Check the repo allowlist: Settings → Integrations → GitHub → (org) → Edit connection → Settings tab → Enable PR Agent for these repos. If the repo isn't in the list, add it. The allowlist applies to both auto-triggered reviews and manual mc review comments.

Q: Why can't I see pull requests for schema change alerts?

Schema change monitors don't use machine learning or GitHub integration. They compare table schema hour-over-hour and identify differences — they will not show GitHub pull requests.

Q: Why can't I see pull requests in the asset summary page?

dbt integration is required to see pull request history on the asset page.

Q: My PRs are not showing up in Monte Carlo and my GitHub organization uses an IP allowlist. Do I need to allowlist any Monte Carlo IPs?

Yes. Add Monte Carlo's SaaS public IP address to your GitHub organization's IP allowlist. You can find the IP address on the Account Information page.

Q: The CI Agent action is waiting but never getting an assessment. What's happening?

The most common cause is that the PR is opened in a repo that isn't in the PR Agent allowlist — the CI Agent requires the PR Agent to run first. Add the repo to the allowlist (see the repo allowlist FAQ above) and re-run the job, or comment mc review on the PR to retrigger.

Other causes:

• The PR diff exceeds the size limit and failed analysis — the PR Agent posts a truncation note in the comment when this happens.
• The PR Agent runs asynchronously and the CI Agent polls every 30 seconds for up to 5 minutes by default. If no assessment is found within that window, the action defaults to pass. Increase the max-wait input if your PRs consistently take longer.

Q: Can I trigger the PR Agent manually?

Yes. Comment mc review on any PR in an allowlisted repo to trigger a new assessment. This is useful after making changes to address a prior risk finding.

Q: I set up the GitHub integration but didn't add the CI Agent GitHub Action/CircleCI. Will I still get risk assessments?

Yes. You will receive a PR Agent risk assessment comment on every PR in your allowlisted repos. The CI Agent GitHub Action/CircleCI is only needed if you want a pipeline gate that can block merges based on that assessment.

Q: How do I turn the PR Agent off?

Two options:

• For a specific repo: remove it from the allowlist at Settings → Integrations → GitHub → (org) → Edit connection → Settings tab.
• For the whole account: go to Settings → AI Agents and toggle PR Agent off. You will fall back to the legacy impact assessment comment if that feature is enabled on your account.