Best practices

How to roll Atmos out on a real codebase, from the first local scan to the CI gate.

Scan where the work happens#

Findings get fixed when they appear while the code is still open. Run Atmos at every point where code changes:

• In the editor. The extension rescans on save and puts findings inline.
• After each agent turn. The coding agent hook checks the files the agent edited and sends the findings back to the agent.
• On every pull request. The CI gate below, plus the check and comment on the pull request with the GitHub App connected.

Rescans after an edit recheck only what changed and usually finish in under a second, so pass --incremental everywhere a tree is scanned repeatedly. In CI, a cold scan of the whole tree is usually right. See warm scans.

Gate every change in CI#

Run the same atmos scan . locally and in CI, and let the exit code decide the build. Fail the build on findings and on every error code. CI and pull requests has GitHub Actions and GitLab CI jobs that fail a pull request only on the findings it brings in.

Treat rules as code#

Project rules belong in .atmos/rules/, committed and reviewed like everything else. See the .atmos folder. A security decision expressed as a rule has a diff, an author, a review thread and a revert button. Encode the conventions that are yours alone: which middleware guards routes, which query builder is sanctioned, which directories may touch the filesystem.

Tune to zero false positives#

When a rule fires on code that is fine, fix the rule instead of teaching the team to ignore it. Exempt the approved case inside the rule or with a marker that is visible in the code, so the intent survives review. Testing and tuning shows the shapes. When one finding is wrong, or is a risk your team accepts, record that with a reason in .atmos-ignore.yaml or with triage on the Findings page. See ignoring findings.

Prioritize by reachability#

Most dependency alerts are about packages your code never reaches. Gate pull requests with --reachable-only, and tighten the gate further with --min-severity and --min-confidence. Pass these options only to the scan of a pull request or to a scan with --no-upload, as keep the Findings page complete explains. The scan of every push to the default branch runs without them and keeps the complete report on the Findings page, where EPSS scores sort the backlog.

Protect your credentials#

On your own machine, atmos login stores a sign-in that only that machine holds. Sign out with atmos logout before handing a machine on, and revoke any device you no longer recognize from the Tokens page. In CI, anyone holding your Workspace Token can scan against your workspace: keep it in ATMOS_TOKEN as a CI secret rather than on a command line, where it would land in shell history and process lists. Give each CI project a token of its own, so you can revoke one without touching the others, and rotate tokens freely. See sign-ins and the Workspace Token and what leaves your machine.