Integrations

Drift is easiest to adopt when teams do not have to invent a workflow around it.

This page collects the current integration surfaces that make drift useful in local checks, CI, code scanning, and machine-readable review flows.

GitHub Action

Drift ships a GitHub Action that supports report-only rollout, configurable severity gating, and SARIF upload for code scanning.

Use this when you want findings in pull requests before you enforce anything.

Key inputs:

• fail-on
• since
• format
• config
• upload-sarif

See CI Architecture Checks with SARIF for rollout posture.

CLI

The CLI is the fastest integration path for local analysis and simple automation.

Common entry points:

• drift analyze --repo .
• drift check --fail-on none
• drift check --fail-on high
• drift analyze --format json
• drift analyze --format sarif
• drift analyze --format pr-comment (Markdown summary for PR comments)
• drift analyze --format junit (JUnit XML for CI test dashboards)
• drift analyze --format llm (LLM-oriented compact output; deprecated, prefer drift mcp)
• drift trend --last 90

See Quick Start for first-run guidance.

pre-commit

Drift provides two pre-commit hooks so you can add architectural checks to any repository without installing drift globally.

Recommended: remote hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/mick-gsk/drift
    rev: v2.9.15
    hooks:
      - id: drift-check          # blocks on high-severity findings
      # - id: drift-report        # report-only (start here, then switch)

drift-check runs drift check --fail-on high and blocks the commit if any high-severity finding is detected.

drift-report runs drift check --fail-on none and prints findings without blocking. Use this during the first week, then switch to drift-check once the team is comfortable with the signal quality.

Alternative: local hook

Use this if drift is already installed in your environment:

repos:
  - repo: local
    hooks:
      - id: drift
        name: drift
        entry: drift check --fail-on high
        language: system
        pass_filenames: false
        always_run: true

Progressive rollout

1. Start with drift-report (report-only) to see findings without disruption
2. Review findings for 1–2 weeks alongside normal code review
3. Switch to drift-check (--fail-on high) once the team trusts the signal
4. Optionally tighten to --fail-on medium for stricter gating

SARIF and JSON outputs

Drift supports machine-readable outputs for review and automation:

• SARIF for GitHub code scanning and related workflows
• JSON for CI artifacts, downstream scripts, and historical comparison

See API and Outputs for the documented surfaces.

Python API

Teams that want to integrate drift programmatically can use the Python entry points already exposed by the project.

Current documented public analysis entry points include:

• analyze_repo(...)
• analyze_diff(...)

These are most useful when you want a custom orchestration layer without wrapping shell commands.

Microsoft Agent Framework

If you want to run drift inside a Python agent loop, prefer wrapping the stable drift.api functions as local function tools instead of parsing CLI output.

The repository now includes a minimal Microsoft Agent Framework example that composes a Drift specialist agent behind a coordinator agent:

• examples/agent-framework/drift_agent_framework.py
• examples/agent-framework/README.md

This path is the best fit when drift and the agent run in the same Python process. Use MCP instead when your host already discovers tools via .vscode/mcp.json or another MCP client.

VS Code Copilot Chat — recommended starting point for AI tool users

The Copilot Chat integration is the lowest-friction way to get drift value in AI coding sessions. It requires no MCP server, no extra dependencies, and no config beyond a one-time setup per repository.

One-time setup:

drift kit init

This creates .github/prompts/ with four slash commands and merges chat.promptFilesLocations into .vscode/settings.json. Run it once per repository — safe to re-run.

After any drift analyze run, open VS Code Copilot Chat and call:

• /drift-fix-plan — prioritized repair tasks from the latest findings
• /drift-export-report — shareable markdown report
• /drift-auto-fix-loop — guided one-finding-at-a-time fix loop
• /drift-feature-guardrails — compact pre-edit constraints for new feature work

No MCP server is required. This path works with any editor that supports Copilot Chat and prompt files.

See VS Code Copilot Chat Workflow for the full setup guide.

MCP server — advanced execution layer

MCP is an optional upgrade for agents that need deterministic, programmatic tool invocations — for example Cursor, Claude Code, and Copilot in agentic mode. Most users should start with drift kit init above and only add MCP when the session-loop pattern becomes the bottleneck.

Install with optional extras:

pip install drift-analyzer[mcp]

Run the server:

drift mcp --serve

Register in VS Code using .vscode/mcp.json:

{
  "servers": {
    "drift": {
      "type": "stdio",
      "command": "drift",
      "args": ["mcp", "--serve"]
    }
  }
}

If you want drift to scaffold the file for you, run drift init --mcp. Drift prefers the drift console script when available and otherwise falls back to the current Python interpreter with -m drift, so the generated config usually works without manual edits.

This auto-fallback currently applies only to the generated MCP configs. The generated pre-push hook still expects drift on PATH.

Register in Claude Desktop using claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

If you want drift to scaffold a merge-ready snippet in your repository first, run drift init --claude. It uses the same launcher auto-detection as --mcp to avoid PATH-related setup friction.

Claude Desktop currently supports this path on Windows and macOS. If you already have other MCP servers configured, merge the drift entry into the existing mcpServers object instead of replacing the full file.

{
  "mcpServers": {
    "drift": {
      "command": "drift",
      "args": ["mcp", "--serve"]
    }
  }
}

Typical commands called through MCP-backed agent flows:

• scan for full repository architectural checks
• diff for pre-commit or staged-change analysis
• validate for config and environment readiness
• fix-plan for prioritized remediation tasks

Cursor

Cursor uses the same MCP protocol and config format. Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "drift": {
      "type": "stdio",
      "command": "drift",
      "args": ["mcp", "--serve"]
    }
  }
}

Or use drift init --mcp to auto-generate. Cursor reads .vscode/mcp.json too, so a single config works for both editors.

For setup details, tool catalog, and workflow examples, see the Cursor MCP Setup Guide.

Example workflow assets in the repository

• action.yml for the GitHub Action implementation
• examples/drift-check.yml for a ready-to-copy workflow
• examples/demo-project/ for an intentionally drifted demo repository

Recommended adoption order

1. CLI locally (drift analyze --repo .)
2. Copilot Chat slash commands (drift kit init — no MCP needed)
3. report-only CI
4. SARIF visibility in pull requests
5. selective gating on high
6. MCP server for deterministic agent execution loops (advanced)
7. deeper automation with JSON or Python API only where justified

Related pages

• Quick Start
• Team Rollout
• CI Architecture Checks with SARIF
• Drift Bot — GitHub App — automatic PR comments, no workflow files needed
• Trust and Evidence

GitLab CI

Drift works in any CI environment that supports Python. Here is a minimal GitLab CI template:

drift-check:
  image: python:3.12-slim
  stage: test
  script:
    - pip install -q drift-analyzer
    - drift check --fail-on none --format json > drift-report.json
    - drift check --fail-on high
  artifacts:
    paths:
      - drift-report.json
    when: always
    expire_in: 30 days
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Progressive rollout in GitLab

1. Report-only (first week): --fail-on none — collect artifacts, no pipeline failures
2. Gate on critical: change to --fail-on critical after reviewing initial findings
3. Gate on high: tighten to --fail-on high when the team is confident in signal quality

SARIF output for GitLab

GitLab does not natively consume SARIF, but you can archive it as an artifact or convert it using third-party tools:

drift-sarif:
  image: python:3.12-slim
  stage: test
  script:
    - pip install -q drift-analyzer
    - drift analyze --format sarif > gl-code-quality-report.sarif
  artifacts:
    paths:
      - gl-code-quality-report.sarif
    when: always

Diff-only analysis

For merge request pipelines, use diff mode for fast incremental checks:

drift-check:
  image: python:3.12-slim
  stage: test
  script:
    - pip install -q drift-analyzer
    - git fetch origin $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
    - drift check --diff origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME --fail-on high
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"