Flamio Scout

.flamio.yml reference

Beta

Every key of .flamio.yml, the file that keeps your Flamio delivery rules in your repository — its type, what it does and each preset's value.

.flamio.yml keeps the rules of How Flamio runs your delivery in your repository, next to your code. It sits at the root of the repository, on the default branch. On a connected GitHub or Bitbucket repository, Flamio reads it from there by itself on every push; from any other host, your pipeline applies it with the flamio CLI. Flamio never commits to your repository. The tables below are built from the same schema Flamio checks the file against.

The file's first line points your editor at the schema, https://flamio.org/schemas/flamio-config/v1.json, so VS Code and JetBrains editors with a YAML plugin complete keys and flag mistakes as you type.

The smallest file

.flamio.yml
# yaml-language-server: $schema=https://flamio.org/schemas/flamio-config/v1.json
version: 1
project: 3f6c1d2e-8a41-4b7e-9c0d-5e2f7a9b1c34
extends: balanced

Every key you leave out takes its value from the preset in extends. project is your project's id: YAML > Download on Delivery > Rules writes it for you.

The whole file

Every key, each at its Balanced value, with one environment of each kind:

.flamio.yml
# yaml-language-server: $schema=https://flamio.org/schemas/flamio-config/v1.json
version: 1
project: 3f6c1d2e-8a41-4b7e-9c0d-5e2f7a9b1c34
extends: balanced
pull_requests:
  check:
    mode: on
    into: [ dev ]
    on: preview
    tasks: from_change
    stop_outdated: true
    scenarios: []
    width: desktop
    access: read_only
    budget_tokens: auto
    publish:
      status: true
      comment: true
  block_merges:
    mode: dry_run
    min_severity: critical
    pages: []
    when_not_checked: block
  skip_paths:
    mode: on
    paths: [ "**/*.md", docs/**, .github/** ]
staging:
  check:
    mode: on
    environments: [ staging ]
    audit: whole_site
    tasks: from_pull_requests
    scenarios: []
    width: desktop
    budget_tokens: auto
production:
  check:
    mode: on
    tasks: none
    compare_with: baseline
environments:
  preview:
    kind: preview
    names: [ preview ]
    url_pattern: "*-acme.vercel.app"
  staging:
    kind: staging
    names: [ staging ]
    branch: dev
    url: https://staging.shop.example.com
  production:
    kind: production
    names: [ production ]
    branch: main
    url: https://shop.example.com
    hosts: [ shop.example.com, www.shop.example.com ]
access:
  test_account: none
  preview_protection: none

The top of the file

Prop

Type

Pull requests

Check pull requests

Prop

Type

Block merges

Prop

Type

Skip docs-only changes

Prop

Type

Staging

Check staging

Prop

Type

Production

Check production

Prop

Type

Environments

Each key under environments is one environment. Leave the section out and Flamio keeps the environments it found in your deploys; name one and the file sets it: a deploy reported under one of its names, or a preview your pipeline reports at an address matching its url_pattern, lands in it, and its kind, address and hosts stay as the file says.

Prop

Type

Access

How Scout gets into your site. Leave the section out and access stays as it is.

Prop

Type

test_account names the project's test account; the login and password stay in Settings > Project. A preview_protection header needs its secret stored in Flamio, which is not available yet: until then, a file that names one is refused.

Check and apply your file

The flamio CLI reads .flamio.yml from the current directory and needs FLAMIO_CI_KEY:

CommandWhat it does
flamio config validateChecks the file.
flamio config plan [--detailed-exitcode]Shows what applying it would change.
flamio config applyApplies it. The key needs Can change delivery settings — see Apply the file from your pipeline.
flamio config pull [--full]Writes the rules as they run now; --full writes every key.

--file <path> reads another file, --ref <branch> names the branch it comes from (default: your CI's branch), and --expect-revision <n> makes apply refuse when someone changed the rules since revision n.

ExitMeans
0The file is valid; nothing to change, or applied.
1The file is invalid, or Flamio refused it.
2plan --detailed-exitcode only: applying it would change something.
4The step is set up wrong — no key, a revoked key, a key of another project, or one without Can change delivery settings.

Errors

An invalid file changes nothing: the rules keep running as they were. Each error names its line and column, the key and what is wrong:

.flamio.yml:7:19 pull_requests.block_merges.min_severity: min_severity: "low" — expected critical, high, medium

A key Flamio does not know is an error, not ignored, so a typo cannot pass silently. A key of a later version says it is not available yet. On Delivery > Rules, a file that failed shows its errors above the rules. On GitHub and Bitbucket, the commit's "Flamio config" check fails with each error on its line, and flamio config plan warns that the last file did not apply.

A repository holds one of .flamio.yml and .flamio.yaml: both at once is an error. The file's project must be a project the repository is connected to.