`.stackat.yml`

On this page

Where the file lives
How the two files merge
Every option
When the file has a problem
A complete example

Stackat is configured in git, where settings are reviewed and versioned like the rest of your platform code, and where an auditor can see them. Every key is optional: without a file, Stackat uses the defaults below.

Where the file lives#

Per repository. .stackat.yml in the repository's top folder, on its default branch. Stackat reads it at the commit it scans. .stackat.yaml works too, and so do the old names .semapi.yml and .semapi.yaml. Only one file is read, the first found in that order, so if you have both .stackat.yml and .semapi.yml, the old one is ignored: delete it.

For the whole organisation. .stackat.yml (or .stackat.yaml) in a repository of your organisation named .github, .gitlab or stackat-config, read from its default branch. It applies to every repository Stackat scans in the organisation, so a platform team sets a cooldown, mirrors or who may use commands once.

The app must be able to read the organisation's repository: install it on all repositories, or include .github (or stackat-config) in the selection. If the app was given selected repositories only and cannot see <org>/.github, the dashboard's Settings tab shows a tip: "org-wide .stackat.yml in acme/.github is not visible to the app: add that repository to the installation if your organisation keeps one there".

Changes take effect at the next scan of each repository (once a day), or straight away for a repository where someone replies with a command. The dashboard's Settings tab shows what each repository's settings change from the defaults, which files they were read from, and any problems.

How the two files merge#

The repository's file wins, key by key. Keys it does not set keep the organisation's value, then the default.

Option	Organisation and repository both set it
`auto_pr`, `cooldown`, `critical_skips_cooldown`, `jira`	The repository's value replaces the organisation's.
`mirrors`	`rules` from both apply, the repository's first. `detect`: the repository's value replaces the organisation's.
`values`	Repository file only. In the organisation's file it is ignored.
`scan`	`paths` and `file_types`: the repository's replace the organisation's. `exclude`: the repository's add to the organisation's; a repository cannot drop them.
`commands`	Per command: the repository's list for `pr`, say, replaces the organisation's list for `pr`. Commands the repository does not mention keep the organisation's list.
`up_to_date`	The repository's `releases_behind` replaces the organisation's.

Every option#

Option	What it does	Default
`auto_pr`	Open pull requests automatically	Off: issues only
`cooldown`	Days a release must be out before an issue or pull request targets it	`0`
`critical_skips_cooldown`	Critical security patches skip the cooldown	`true`
`mirrors`	Map your registry mirrors back to public images and charts	`detect: true`, no rules
`values`	Extra Helm values files per chart	None
`scan`	Which files Stackat reads	Every YAML, Terraform and HCL file
`commands`	Who may use `/stackpaw pr`, `ignore`/`track` and `reevaluate`	Everyone with a role in the repository
`up_to_date`	When a tool counts as up to date on the dashboard and in the digest	`releases_behind: 0`
`jira`	A "Create a Jira ticket" link in each issue	None

cooldown can also be written cooldown_days or minimum_release_age.

When the file has a problem#

Stackat never stops a scan because of its settings. What it cannot read is reported on the dashboard's Settings tab, under Problems, with the file it is in:

A bad value is a problem and that setting is ignored; the rest of the file applies. For example: .stackat.yml: cooldown must be between 0 and 365 days, not 400.
An unknown key is ignored without a problem. Check the Settings tab shows the setting you meant: a misspelled cooldwn does nothing.
A file that is not valid YAML, or not a mapping of settings, is ignored as a whole: .stackat.yml: not valid YAML (…) or .stackat.yml: expected a mapping of settings.

Warning: one exception keeps a broken file from letting everyone in. If a file that cannot be read contains a commands: key, nobody can use /stackpaw pr, ignore/track or reevaluate until it is fixed: ".stackat.yml: not valid YAML (…); it has a commands: block, so nobody can use /stackpaw pr, ignore, reevaluate until it is fixed".

If GitHub does not answer when Stackat reads the settings, that repository's scan waits for the next run rather than scanning without them.

A complete example#

Every option, annotated. Copy what you need: anything you leave out keeps its default.

.stackat.ymlyaml

# Pull requests: one per tool and release, ready when nothing needs changing, a draft otherwise.
auto_pr: true

# Wait until a release has been out 14 days ("14d" and "2w" work too)...
cooldown: 14
# ...except a critical security patch (patch urgency 90+, or exploited now): proposed right away.
critical_skips_cooldown: true

# Images and charts pulled through your own registries.
mirrors:
  detect: true                      # recognise common mirror layouts automatically
  rules:                            # your prefix -> the public one; the longest matching `from` wins
    - from: harbor.acme.internal/dockerhub
      to: docker.io
    - from: https://acme.jfrog.io/artifactory/api/helm/helm-remote
      to: https://kyverno.github.io/kyverno

# Values files nothing in the repository points to (applied with helm -f in CI). Repository file only.
values:
  cloudflare-tunnel: [ops/cloudflare-tunnel/*.yaml]

# What Stackat reads. Default: every YAML, Terraform and HCL file.
scan:
  paths: [infra/, deploy/]          # only these files or folders; globs work
  exclude: ["**/examples/**"]       # never these, even inside paths
  file_types: [yaml, terraform]     # yaml (.yaml, .yml) and/or terraform (.tf, .hcl)

# Who may use the commands that change something. Default: everyone with a role in the repository.
commands:
  pr: ["@alice", maintain]          # people, teams of this organisation, or a role and higher
  ignore: ["@acme/platform-team"]   # covers /stackpaw track too
  reevaluate: [write]

# When the dashboard and the weekly digest count a tool as up to date.
up_to_date:
  releases_behind: 1                # at most one stable release behind its latest (0-20)

# A "Create a Jira ticket" link in every new issue. Jira Cloud; no credentials.
jira:
  site: acme.atlassian.net
  project_id: 10042
  issue_type_id: 10001
  labels: [platform]