Your plan knows.
Your team doesn’t.

Four questions nobody’s answering

On Azure DevOps

Drops into the pipeline you already run

Terraform already reports drift and deprecations. It puts them at line 8,000 of a job log, after a green check, where nobody looks again. Retirements it never mentions at all. tf-snag writes all three to the places people already look: the tf-snag tab, the team’s Teams channel, the board, the project wiki. One step produces them all.

Try it outside CI first

# linux/amd64 (tf-snag) or windows/amd64 (tf-snag.exe)
curl -sSL https://github.com/wes-key/tf-snag/releases/latest/download/tf-snag \
  -o tf-snag && chmod +x tf-snag

terraform plan -out tfplan
terraform show -json tfplan | ./tf-snag -check drift

The extension

Optional, but it’s where this data looks its best. Install it once and every run gets:

The tf-snag tab

A purpose-built view of the run: drift, deprecations, retirements and pending changes on their own tabs, each finding badged new or dated by when it was first seen, and the ignored findings with their reasons. The clearest surface for this by a distance.

− + Full size →

Teams alerts

An Adaptive Card posted to a channel through a Power Automate Workflows webhook: a coloured verdict banner, the counts, and drift and deprecations folded into groups that expand in place, with new findings sorted to the top.

By default it only posts when something is new against the baseline, so a nightly run doesn’t re-announce the same drift every morning.

Azure Boards work items

One work item per finding, tagged with the finding’s stable id, so Azure DevOps itself is the record of what’s been raised and no run opens a duplicate. By default only new findings get one, so day one isn’t fifty items. Items close when their finding goes away.

Ignoring a finding doesn’t close its item: tf-snag comments on it and leaves that call to a person. Start with dry-run, which checks the token and permissions and writes nothing.

An exceptions register

A generated wiki page listing every ignore rule: what it waives, why, whether it lives in the ignore file or inline in the .tf, and what it’s suppressing right now. Rules that have stopped suppressing anything get their own table, so stale waivers get removed instead of living forever.

It only commits when something has changed, so the page history stays meaningful.

− + Full size →

The pipeline

With the extension it’s two tasks: one installs the binary, one does everything else:

- script: |
    terraform -chdir=terraform plan -out tfplan -json | tee plan.jsonl
    terraform -chdir=terraform show -json tfplan > plan.json
  displayName: terraform plan

- task: tf-snag-install@0           # latest release, onto PATH

- task: tf-snag@0
  inputs:
    checks: all,retirements        # all is drift + deprecations
    planLogDir: terraform           # plan ran with -chdir=terraform
    retirementsFailWithin: 90       # only fail on what is close
    teamsWebhook: $(teamsWebhook)   # secret variable
    teamsNotify: new                # only when something appears
    workItems: dry-run              # off | dry-run | on
    adoType: Bug
    adoArea: Platform\Terraform
    wikiPage: /tf-snag/Exceptions   # the exceptions register

The baseline is the previous run’s tf-snag artifact, which the task publishes for you. Download it into $(Pipeline.Workspace)/prev and findings are tracked across runs. Publishing the register needs the pipeline to reference the wiki’s repository, and the build service needs Contribute on it.

Without it, a script step and a published artifact do the same job:

variables:
  TF_SNAG_VERSION: v0.1.0

steps:
- script: |
    # public repo, so gh needs no token; a curl to the
    # release asset URL works just as well
    gh release download "$(TF_SNAG_VERSION)" --repo wes-key/tf-snag \
      --pattern tf-snag --output tf-snag
    chmod +x tf-snag
  displayName: Get tf-snag

- script: |
    terraform -chdir=terraform plan -out tfplan -json | tee plan.jsonl
    terraform -chdir=terraform show -json tfplan > plan.json
    ./tf-snag -check all,retirements \
      -plan plan.json -plan-log plan.jsonl -plan-log-dir terraform \
      -source "$(Build.SourcesDirectory)" \
      -format sarif -exit-code=false > tf-snag.sarif
  displayName: tf-snag drift check

- task: PublishBuildArtifacts@1
  inputs:
    PathtoPublish: tf-snag.sarif
    ArtifactName: CodeAnalysisLogs   # the Scans tab reads this

What lands where

The flags that matter

-plan

Path to terraform show -json output, or - to read stdin.

-plan-log  /  -plan-log-dir

The terraform plan -json log and the directory its paths resolve against. This is what makes deprecation findings point at real files instead of nothing.

-source

Repo root. Turns SARIF locations into links to the exact .tf line, and picks up inline # tf-snag:ignore comments.

-baseline

Last run’s tf-snag.sarif. Diffs against it so each finding is stamped new / updated / absent with a first-seen date. That is the movement the tf-snag tab shows.

-ignore

A .tf-snag-ignore.yml (auto-discovered in the repo root) of accepted findings. Matched findings — drift, deprecations and retirements alike — stay in the report but don’t trip the exit code.

-teams-webhook  /  -teams-notify

Post the Adaptive Card to a Workflows URL (or set $TF_SNAG_TEAMS_WEBHOOK, which keeps it off the command line), on new, findings or always.

-ado-url  /  -ado-raise  /  -ado-close

Raise one work item per finding in that project, for new findings or all of them, and close the ones that have cleared. -ado-dry-run shows what would change.

-wiki-page

Publish the exceptions register to this wiki path, e.g. /tf-snag/Exceptions. -wiki-dry-run prints the page instead.

-retirements  /  -retirements-fail-within

Use your own catalogue instead of the built-in one, and narrow what fails the build to deadlines inside a window (90d). Everything outside it is still reported, marked as beyond the window.

-check  /  -format

drift | deprecations | retirements | all, and text | json | markdown | junit | sarif. all is drift and deprecations; retirements are asked for by name (-check all,retirements), because they lean on a shipped catalogue rather than the plan alone.

-exit-code

Default true: exit 2 on un-suppressed findings. Set false in CI when you want a warning, not a failed stage.

Hosted or self-hosted agents both work; the binary is linux-amd64 or windows-amd64.