Skip to content

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 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.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/mick-gsk/drift
    rev: v2.6.0
    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.

MCP server

Drift also exposes an MCP (Model Context Protocol) server for agent-native integration in tools like VS Code Copilot Chat.

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

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
  1. CLI locally
  2. report-only CI
  3. SARIF visibility in pull requests
  4. selective gating on high
  5. deeper automation with JSON or Python API only where justified

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"