Docs

How issues work

Stackat opens one GitHub issue per tool that is behind its latest stable release. The issue is a to-do list for that upgrade, written for your files, not a generic changelog.

What Stackat finds#

Stackat reads your YAML, Terraform and HCL files (narrow that with scan) and records every pinned version with its file and line:

• Helm charts installed by helmfile, Argo CD Application and ApplicationSet, Flux HelmRelease, Kustomize helmCharts, and Terraform helm_release;
• Terraform providers in required_providers;
• Container images in Kubernetes objects with a pod template (Deployment, StatefulSet, DaemonSet, Job, CronJob, Pod, Argo Rollout and the like), Kustomize images: overrides and docker compose files;
• Custom resources a tool owns, and the Helm values each installation sets, including values files applied outside the repository's own references (see values).

Images of your own applications are found too, but match no tool Stackat follows and never appear anywhere. An image pinned to latest, or by digest only, names no version, so it gets no issue: see Troubleshooting.

What an issue says#

The title carries the versions and the verdict, for example Upgrade Cilium 1.14.5 → 1.20.3: 2 edits needed. The body, top to bottom:

1. The heading: where the tool is pinned (file and line), the latest stable release and the verdict in a sentence.
2. Before you upgrade: one line per thing to do, with the file it is in.
3. One line on everything else in the upgrade: how many releases, major versions crossed, installations, and security fixes told apart from dependency bumps.
4. Details per item: the release that brings it, what changes, and the exact lines in your repository it touches.
5. Folded sections for security fixes, other changes, the releases in between with links to their notes, and the commands you can reply with.

When an upgrade fixes vulnerabilities, the issue shows a patch urgency from 0 to 100 under the headline and a table of the CVEs fixed. When a tool is pulled through one of your registry mirrors, it says so and reminds you to mirror the target version first (see mirrors). With a cooldown, it lists the releases held back and the day each becomes eligible.

Release notes about a feature your values switch off everywhere (metrics.enabled: false for a change to metrics.serviceMonitor, say) go under Not affecting this repo and do not count toward the verdict.

Verdicts#

The verdict says what to do. It is plain text on the issue and the dashboard; only the risk has a colour.

The risk scale#

One scale on every issue, on the dashboard and in the Slack digest:

Labels#

Every issue Stackat opens carries:

• stackat, always;
• one of risk: high, risk: medium or risk: low;
• breaking-change when a breaking change on the way touches this repository's files;
• security when a release on the way fixes a vulnerability.

Stackat sets and removes only these labels. Labels your team adds are left alone.

Next up#

Next up is the dashboard's short list of what to do first: the five open items with the highest risk across your repositories. Within the same risk, Stackat ranks:

1. what you can do now before what still waits for release notes;
2. the most urgent security fix (highest patch urgency), then the most CVEs fixed;
3. the bigger verdict (migration, edits needed, review, safe);
4. the most releases behind.

The weekly Slack digest's Needs attention uses the same ranking and shows the top three.

Issues are records#

An issue is written once, when Stackat has read every release between your version and the latest. It is not edited afterwards, so it stays a dated record of the risk as it was known. To rewrite it from the latest data, reply /stackpaw reevaluate.

There is one issue per tool and repository. If a tool is installed in several places, the issue covers all of them and upgrades from the oldest version found.

When issues close#

Stackat closes its issues itself, with a comment, leaving the text as it was:

What happens next:

• Closed as completed counts as an upgrade delivered on the dashboard and in the audit evidence.
• Closed as not planned because of scan never counts as an upgrade. The evidence lists it as "No longer scanned (left out by .stackat.yml scan)". If the files are scanned again, the tool gets a new issue.
• Closed by a person stays closed for that release: Stackat does not reopen it. When a newer release comes out, a new issue is opened and the old one stays as it was.
• Behind again later: when the tool falls behind again after an upgrade, a new issue is opened.
• Cooldown: while every newer release is still inside your cooldown, an open issue stays open and no new one is opened.