CI/CD Integration¶

behave-doctor is designed to run in CI pipelines. It is fast (typically under 1 second for medium projects), produces no side effects, and uses standard exit codes.

Exit codes¶

Code	Meaning
0	No errors or warnings found.
1	One or more errors or warnings found.
2	Scan failed (e.g. missing features directory).

Most CI systems treat exit code 1 as a failure, which is the desired behavior — issues in the Behave suite should block the pipeline.

GitHub Actions¶

Basic lint step¶

Add behave-doctor as a lint step in your CI workflow:

name: CI
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install behave-doctor
      - run: behave-doctor scan . --no-color

Fail on errors only¶

If you want the pipeline to fail only on errors (not warnings):

- run: behave-doctor scan . --severity error --no-color

Fail on errors and warnings¶

- run: behave-doctor scan . --severity warning --no-color

GitHub Code Scanning (SARIF)¶

Upload results to GitHub Code Scanning for inline annotations in pull requests:

name: behave-doctor
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install behave-doctor
      - run: behave-doctor scan . --format sarif -o behave-doctor.sarif
        continue-on-error: true
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: behave-doctor.sarif

The continue-on-error: true ensures the SARIF file is uploaded even when behave-doctor finds issues (exit code 1). The security-events: write permission is required for SARIF upload.

Full CI example¶

A complete CI workflow with lint, test, and behave-doctor:

name: CI
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install behave-doctor
      - run: behave-doctor scan . --no-color

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install -e ".[dev]"
      - run: pytest

  code-scanning:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install behave-doctor
      - run: behave-doctor scan . --format sarif -o behave-doctor.sarif
        continue-on-error: true
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: behave-doctor.sarif

Pre-commit hook¶

Add behave-doctor to your .pre-commit-config.yaml to run it on every commit:

repos:
  - repo: https://github.com/MathiasPaulenko/behave-doctor
    rev: v1.3.0
    hooks:
      - id: behave-doctor
        args: ["scan", "--severity", "warning", "--no-color"]

The hook scans .feature and .py files. It runs from the repository root so it can build the full dependency graph.

Configuration options for pre-commit¶

`args` value	Effect
`--severity error`	Only fail on errors (suppress warnings).
`--severity warning`	Fail on errors and warnings (recommended).
`--no-color`	Disable ANSI colors (recommended for CI logs).
`--exclude-rules BD101`	Skip specific rules.
`--format sarif -o out`	Write SARIF output to a file.

GitLab CI¶

behave-doctor:
  stage: lint
  image: python:3.13-slim
  script:
    - pip install behave-doctor
    - behave-doctor scan . --no-color
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

CircleCI¶

version: 2.1
jobs:
  behave-doctor:
    docker:
      - image: cimg/python:3.13
    steps:
      - checkout
      - run: pip install behave-doctor
      - run: behave-doctor scan . --no-color
workflows:
  version: 2
  lint:
    jobs:
      - behave-doctor

Jenkins¶

pipeline {
    agent any
    stages {
        stage('behave-doctor') {
            steps {
                sh 'pip install behave-doctor'
                sh 'behave-doctor scan . --no-color'
            }
        }
    }
}

Targeted test execution with impact analysis¶

Use behave-doctor impact to run only the tests affected by your changes instead of the full suite. This is especially useful in CI for pull requests where you know exactly which files changed.

GitHub Actions¶

name: Targeted Tests
on: [pull_request]

jobs:
  affected-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install behave-doctor
      - name: Get changed files
        id: changed
        run: |
          FILES=$(git diff --name-only origin/main...HEAD | tr '\n' ',')
          echo "files=$FILES" >> $GITHUB_OUTPUT
      - name: Run affected tests
        run: |
          behave-doctor impact . --changed-files "${{ steps.changed.outputs.files }}" --format names | xargs -I{} behave --name "{}"

GitLab CI¶

affected-tests:
  stage: test
  image: python:3.13-slim
  script:
    - pip install behave-doctor
    - FILES=$(git diff --name-only origin/main...HEAD | tr '\n' ',')
    - behave-doctor impact . --changed-files "$FILES" --format names | xargs -I{} behave --name "{}"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Other CI systems¶

behave-doctor is a standard CLI tool. In any CI system:

Install with pip install behave-doctor.
Run behave-doctor scan . --no-color.
Check the exit code: 0 = clean, 1 = issues found, 2 = scan error.

The --no-color flag is recommended for CI logs that don't support ANSI escape codes.

Caching¶

To speed up CI runs, cache the pip package:

GitHub Actions¶

- uses: actions/setup-python@v5
  with:
    python-version: "3.13"
    cache: pip
    cache-dependency-path: requirements.txt
- run: pip install behave-doctor

Pre-commit autoupdate¶

To keep the pre-commit hook version up to date:

pre-commit autoupdate

This updates rev: in .pre-commit-config.yaml to the latest tag.