Use SAM Doctor in under 60 seconds

INSTALL

1) Install the CLI

python -m pip install sam-doctor

You can also use pipx install sam-doctor or uvx sam-doctor demo.

Optional bootstrap: sam-doctor init writes a starter GitHub Actions workflow that captures a deployment failure log and runs SAM Doctor.

# Non-blocking pilot workflow
sam-doctor init --deploy-command "sam deploy --no-confirm-changeset" --summary --annotations

# Gate on high-confidence findings after a few stable runs
sam-doctor init --deploy-command "sam deploy --no-confirm-changeset" --summary --annotations --fail-on-confidence high --force

# Strict mode once medium-confidence findings have proven out too
sam-doctor init --deploy-command "sam deploy --no-confirm-changeset" --summary --annotations --fail-on-findings --force

If you want one workflow file for both modes, copy github-actions-workflow-two-phase-gating.yml and switch to rollout-mode: strict on demand.

Use this in Slack/Discord:

I triaged a deploy failure with SAM Doctor:
sam-doctor diagnose deployment.log --format markdown
https://sam-doctor.jacobgoldstein.dev/quickstart.html?utm_source=share_copy&utm_medium=chat

FIRST RUN

2) Diagnose a real failure excerpt

Save the smallest authorized excerpt you are allowed to inspect:

cat > deployment-failure.log <<'EOF'
Not authorized to perform: sts:AssumeRoleWithWebIdentity
Error: status is not authorized
EOF

sam-doctor diagnose deployment-failure.log --format markdown

Share one finding and the first safe verification step with your teammate.

Use your command family directly:

# AWS SAM
sam-doctor diagnose deployment.log --format json --fail-on-findings

# AWS CDK
sam-doctor diagnose cdk-deploy.log --format json --fail-on-findings

# AWS CloudFormation
sam-doctor diagnose cloudformation-deploy.log --format json --fail-on-findings

CI INTEGRATION

3) Add one diagnostic step in GitHub Actions

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

- name: Diagnose deployment log
  if: always()
  uses: jakegold1647/sam-doctor@v0
  with:
    log-file: deployment.log
    summary: true
    annotations: true
    fail-on-findings: false

Keep this non-blocking initially. When your team is comfortable with the signal quality, flip on enforcement with --fail-on-findings: true (or run sam-doctor init --fail-on-findings --force to regenerate your workflow).

Keep the deployment command unchanged. SAM Doctor only reads the local log and suggests the next safe verification path.

ROUTING

Use outputs to route triage

Keep CI non-blocking while still surfacing real signals:

- name: Diagnose deployment log
  if: always()
  id: sam-doctor
  uses: jakegold1647/sam-doctor@v0
  with:
    log-file: deployment.log
    summary: true

- name: Open an incident thread only when needed
  if: steps.sam-doctor.outputs.has-findings == 'true'
  run: |
    echo "Findings: ${{ steps.sam-doctor.outputs.finding-count }}"

SEARCH-FIRST START

Start with your exact failure

• OIDC token failures: paste the first failing AssumeRoleWithWebIdentity block and run sam-doctor diagnose.
• Rollback noise: use the first full failure excerpt before ROLLBACK_COMPLETE messages.
• Capability requirement errors: run the first 20 lines around the CAPABILITY_IAM line through SAM Doctor.
• Container image pushes: include the registry auth and image pull failure lines in your excerpt.
• CDK/SAM package/build: point SAM Doctor at your `cdk deploy` or `sam package` excerpt for the first actionable finding.