PIPELINE STARTERS

Add the diagnosis. Keep the deploy result.

Pick the runner you already use, start advisory, and keep the AWS deployment command's original exit status. Every starter runs locally on the log you provide and needs no AWS credentials of its own.

CREDENTIAL-FREE CHECK

Verify one known result before touching a deployment

sam-doctor diagnose examples/oidc-assume-role-failure.txt --format markdown

The tracked sample returns one finding with rule ID github.oidc.assume-role-rejected.

Then verify the honest no-match path:

printf '%s\n' 'deployment finished with status 0' | sam-doctor diagnose - --format markdown

That command should report that no supported pattern was found.

CHOOSE A RUNNER

Copy the smallest starter that matches your pipeline

Replace only the marked deploy command and keep your existing authentication and environment setup in earlier steps.

GITHUB ACTIONS

Use the Action or a captured shell log

Keep if: always() on a diagnostic step after deploy so it can explain a failed run.

GITLAB CI

Save the report as a job artifact

Diagnose after a non-zero deploy, publish Markdown or JSON, then return the captured deployment status.

Open the GitLab CI starter

CIRCLECI

Keep the report beside the deployment log

Capture PIPESTATUS[0], diagnose the saved log on failure, and persist both files to the workspace.

Open the CircleCI starter

AZURE PIPELINES

Publish a reviewed pipeline artifact

Use the Bash step's captured deploy status and keep diagnosis advisory while the team evaluates the findings.

Open the Azure Pipelines starter

BITBUCKET PIPELINES

Keep the log and report as step artifacts

Run diagnosis only when deployment fails, then exit with the status captured from the deploy command.

Open the Bitbucket starter

CUSTOM RUNNER

Wrap any deployment command

The run command streams the deploy, saves the combined log, diagnoses on failure, and returns the deploy exit status.

sam-doctor run --log-file deployment.log --format markdown -- your-deploy-command

Browse every checked-in starter

CHOOSE AN OUTPUT

Send the report where your team will review it

Destination	Command
Terminal or ticket draft	`sam-doctor diagnose deployment.log --format markdown`
Script or later CI step	`sam-doctor diagnose deployment.log --format json --output diagnosis.json`
GitHub annotations	`sam-doctor diagnose deployment.log --format github`
GitHub code scanning	`sam-doctor diagnose deployment.log --format sarif --output sam-doctor.sarif`
Several logs	`sam-doctor batch logs/ --format json`

ROLLOUT CONTRACT

Start advisory. Enforce only after review.

Run the known-result and no-match checks without credentials.
Keep diagnosis non-blocking while you review expected, missed, and unclear findings.
Preserve the deployment command's exit status in every runner.
Gate findings only after the signal quality fits your workflow.

SAM Doctor reads text; it does not inspect or change an AWS stack. The first-deployment pilot gives a bounded review checklist.

SAFE SHARING

Remove account IDs, ARNs, request IDs, credentials, tokens, private paths, customer names, and private repository names. Built-in redaction helps, but it is not a substitute for your review.

A useful report includes the rule ID, one short redacted excerpt, the command, the expected result, and whether the suggested verification was read-only and useful.

Share a usage result Report an unmatched error safely