sam-doctor 0.7.7

Local, evidence-first diagnostics for AWS SAM and GitHub Actions deployment failures.

SAM Doctor

SAM Doctor is a local, evidence-first command-line tool for turning AWS SAM, CloudFormation, IAM, and GitHub Actions deployment failures into a concise diagnostic report.

See the project page | Use on GitHub Marketplace | Report a bad diagnosis | Request a rule | Join the feedback discussion

It does not access AWS, upload logs, change resources, or promise an authoritative root cause. It detects known patterns in the text you provide, redacts common identifiers, and gives safe verification steps and the relevant official documentation.

Current release: v0.7.7.

Current free core

• GitHub Actions OIDC errors: missing id-token: write, audience mismatch, trust-policy/subject mismatch, and AssumeRoleWithWebIdentity failures
• IAM AccessDenied failures
• CloudFormation failed-resource events and rollback states
• CloudFormation capability acknowledgement errors
• Lambda container-image failures caused by missing ECR image access
• API Gateway deployments created before methods exist
• SAM deployment/configuration errors, including conflicting artifact-bucket settings and missing esbuild dependencies
• Template shape, IAM trust-policy, Lambda packaging, and S3 artifact failures
• API Gateway CORS preflight conflicts
• Terminal, Markdown, and JSON reports
• Composite GitHub Action with opt-in redacted job summaries and CI gating
• Local redaction for account IDs, ARNs, email addresses, and common CI credentials

Try it in 60 seconds

python -m pip install sam-doctor
sam-doctor demo

This installs the latest stable release from PyPI. The bundled demo needs no AWS credentials and makes no network calls. To pin the tested release exactly, run python -m pip install sam-doctor==0.7.7. To install from the tagged source instead, run:

python -m pip install "sam-doctor @ git+https://github.com/jakegold1647/sam-doctor.git@v0.7.7"

If your shell cannot find sam-doctor after installation, activate the environment where it was installed or use python -m sam_doctor.cli in the commands below.

For more bundled examples, try sam-doctor demo --scenario cloudformation, sam-doctor demo --scenario api-gateway, or sam-doctor demo --scenario esbuild. Run sam-doctor rules --format json to inspect the exact set of supported diagnostic categories before sharing a log.

To save a report:

sam-doctor diagnose deployment.log --format markdown --output diagnosis.md

The input can also be read from standard input, which is useful for CI steps and shell pipelines:

kubectl logs deploy/my-api | sam-doctor diagnose -
sam-doctor diagnose deployment.log --format json --output diagnosis.json

The terminal format is intended for a quick local check, Markdown is convenient for a human-readable handoff, and JSON is stable enough for scripts and CI annotations. All three formats contain matched evidence rather than the full input log.

You can also process multiple files in batch mode:

sam-doctor batch logs/*.log logs/*.txt --format json > batch-results.json

For a shell-based CI gate, add --fail-on-findings. The command still writes the report, then exits with status 1 only when a supported finding is present:

sam-doctor diagnose deployment.log --format json \
  --output diagnosis.json --fail-on-findings

GitHub Actions

Use the included action when a workflow already saves a deployment log:

- name: Deploy
  shell: bash
  run: |
    set -o pipefail
    sam deploy --no-confirm-changeset 2>&1 | tee deployment.log

- name: Diagnose deployment log
  if: always()
  id: sam-doctor
  uses: jakegold1647/sam-doctor@v0.7.7
  with:
    log-file: deployment.log
    summary: "true"
    # Uncomment to fail this job when a supported finding is detected.
    # fail-on-findings: "true"

Put the diagnostic step after the command that writes the log and keep if: always(); otherwise GitHub Actions skips it when the deployment fails. The action exposes finding-count and has-findings outputs. Set fail-on-findings: "true" only when you want a supported diagnostic to fail the job; the commented line above shows the opt-in placement. The Markdown job summary is opt-in and contains only matched, redacted evidence; review it before sharing a workflow run outside your team.

What a report includes

SAM Doctor deliberately reports only what its rules can support:

1. A likely failure category and confidence level.
2. Up to three matched log lines, redacted before output.
3. Safe checks to validate the diagnosis before changing a policy or stack.
4. A link to the relevant official documentation.

It is most useful when you start with the first failure in a deployment log, not a later rollback message. When multiple supported patterns appear, SAM Doctor presents findings in the order of their first matching log line.

Example output

Likely cause: GitHub Actions cannot assume the configured AWS role through OIDC.
Confidence: high
Evidence: Not authorized to perform sts:AssumeRoleWithWebIdentity
Safe next step: Confirm the workflow grants `id-token: write` and that the
role trust policy's `sub` condition matches the repository, branch, or GitHub
Environment that ran the job.

Feedback and roadmap

The free core will stay useful for individual deployment failures. Please open an issue when a report is wrong, unclear, or missing a failure pattern. For a new rule, include only a sanitized error excerpt and the safe next check you expected to see. See CONTRIBUTING.md for the exact format.

Distribution and ethics

SAM Doctor is grown through practical conversations and feedback, not star incentives. If you run outreach, ask for one realistic use case first, then share the report and a short ask for permission to improve coverage.

Track progress with:

python scripts/check-launch.py \
  --append-csv artifacts/distribution.csv \
  --summary artifacts/distribution-summary.md \
  --print-trend

Before release tagging, run:

python scripts/check-launch.py --skip-outreach

For a lightweight outreach quality check, run:

python scripts/check-launch.py \
  --skip-distribution \
  --outreach-summary artifacts/outreach-summary.md \
  --outreach-log launch/outreach-log-template.csv

For a stricter organic-growth check:

python scripts/check-outreach.py launch/outreach-log-template.csv \
  --strict --min-feedback-ratio 100

For a combined snapshot, scripts/check-launch.py also writes artifacts/outreach-summary.md with an ethical_growth_score and concrete next_growth_actions to guide the next outreach batch.

For the ethical outreach loop, copy launch/outreach-log-template.csv into your tracking notes and fill one row per real contact.

After a release is published and channels are expected live, run the stricter combined gate:

python scripts/check-launch.py \
  --strict-distribution-during-release \
  --strict-ethical --min-feedback-ratio 100 \
  --outreach-log launch/outreach-log-template.csv \
  --outreach-summary artifacts/outreach-summary.md

On stable releases, the PyPI publish workflow also kicks off a strict distribution-check.yml run after package upload so the strict gate can be verified post-live without blocking on early warm-up timing.

Guides

• Diagnose a GitHub Actions to AWS OIDC deployment failure
• Find the first useful error in a CloudFormation rollback

Supported signals

Run sam-doctor rules for the current machine-readable catalog. Each rule is triggered by an explicit error signal, not by template inspection or AWS account access; the report is still a prompt to verify the cause, not an automatic fix.

Scope and safety

Run this only on logs you are authorized to inspect. Review every suggested command and policy change before applying it. SAM Doctor is diagnostic help, not security, legal, or production-operations advice.

Reports redact AWS account IDs, ARNs, email addresses, common AWS access key IDs, bearer tokens, JWT-style tokens, and common GitHub token formats before matched evidence or a displayed source name is shared. This is a helpful guardrail, not a secret scanner: review a report before sharing it.

Development

python -m pip install -e ".[dev]"
python -m pytest -q
python -m build

See CHANGELOG.md for release history, SECURITY.md for vulnerability reporting, SUPPORT.md for help boundaries, and docs/pypi-publishing.md for the stable-release publishing setup.