configdoctor

configdoctor scans a repository for configuration drift before CI, deploys, and runtime failures.

Current MVP scope:

• compare env var usage in code against .env.example
• compare docker-compose env references against .env and .env.example
• compare GitHub Actions env and secret references against .env.example
• compare ports detected from env files, Dockerfile, docker-compose, and Kubernetes manifests
• emit pretty terminal output, JSON, or SARIF

Scanned inputs:

• .env
• .env.example
• Dockerfile
• docker-compose.yml / compose.yml
• .github/workflows/*.yml
• Kubernetes YAML manifests
• source code env usage in JavaScript, TypeScript, Python, Go, and shell scripts

Why it matters

Configuration drift is easy to miss:

• code starts using a new env var but .env.example stays stale
• GitHub Actions references a secret nobody documented
• compose ports differ from container ports and manifests
• Dockerfile exposes the wrong port after a refactor

configdoctor catches those mismatches early.

Install

Go

go install github.com/CodeWithAmeer/configdoctor@latest

Build locally

make build
./bin/configdoctor version

Quick start

configdoctor init
configdoctor scan
configdoctor scan --format json .
configdoctor scan --format sarif --quiet .

Commands

configdoctor scan [path]

Scan a repository. The path defaults to the current directory.

Flags:

• --format pretty|json|sarif
• --config PATH
• --fail-on info|warning|error
• --quiet
• --no-color

Path is positional only in this MVP.

configdoctor init

Create a starter .configdoctor.yml in the current directory.

Flags:

• --dir PATH

configdoctor version

Print build version metadata.

Help

configdoctor --help
configdoctor scan --help

Config

Create .configdoctor.yml:

exclude_paths:
  - .git
  - node_modules
  - vendor
  - dist
  - build
  - coverage

disabled_rules:
  - EXAMPLE_ENV_UNUSED

env_files:
  - .env
  - .env.example
  - .env.local

fail_threshold: error

Supported config keys

• exclude_paths: extra directories or paths to skip
• disabled_rules: rule IDs to disable
• env_files: env-style files to scan
• fail_threshold: info, warning, or error

Rules in this MVP

• CODE_ENV_MISSING_EXAMPLE
• EXAMPLE_ENV_UNUSED
• COMPOSE_ENV_UNDOCUMENTED
• GITHUB_ACTIONS_ENV_UNDOCUMENTED
• DOCKERFILE_EXPOSE_PORT_MISMATCH
• COMPOSE_PORT_MISMATCH
• K8S_CONTAINER_PORT_MISMATCH
• MISSING_ENV_EXAMPLE

Env var detection

configdoctor scans these patterns conservatively:

JavaScript / TypeScript

• process.env.NAME
• process.env["NAME"]
• process.env['NAME']

Python

• os.getenv("NAME")
• os.environ["NAME"]
• os.environ.get("NAME")

Go

• os.Getenv("NAME")
• os.LookupEnv("NAME")

Shell

• ${NAME}
• $NAME

GitHub Action usage

Use an exact release tag when referencing the published action.

name: configdoctor
on:
  pull_request:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: CodeWithAmeer/configdoctor@v1.0.0
        with:
          path: .
          format: pretty
          fail-on: error

Action inputs

• path: repository path to scan
• format: pretty, json, or sarif
• config: optional path to .configdoctor.yml
• fail-on: failure threshold override
• quiet: true or false
• no-color: true or false

Sample output

configdoctor found 3 issue(s)

[ERROR] CODE_ENV_MISSING_EXAMPLE
  src/index.js:2
  environment variable "JWT_SECRET" is used in code but missing from .env.example

[WARNING] GITHUB_ACTIONS_ENV_UNDOCUMENTED
  .github/workflows/ci.yml:8
  GitHub Actions reference "DEPLOY_TOKEN" is not documented in .env.example

[WARNING] DOCKERFILE_EXPOSE_PORT_MISMATCH
  Dockerfile:4
  Dockerfile exposes port 7000, but detected ports are 3000, 8080

Summary: 1 error(s), 2 warning(s), 0 info

Output formats

• pretty: human-readable terminal output
• json: machine-readable structured output
• sarif: SARIF 2.1.0 for code scanning platforms

Development

make test
make build

See examples/demo for a small sample repository.

License

MIT