• Reference
  • Version · 6.0
  • Change Automation Reference

Checks targeting file

Last updated: September 29, 2026

Note: The checks targeting file requires Liquibase Secure 6.0 or later.

A checks targeting file is a YAML file. Each rule in it lets one policy check treat certain changesets differently, either exempting them from failing the run or restricting the check to only those changesets. Liquibase creates the file for you the first time you run checks targeting add, and applies its rules on a checks run that names the file with --targeting-file. For the concepts behind the rules, see What is Checks Targeting?.

Naming and location

The targeting file is paired with your checks settings file. Liquibase takes the checks settings file name, replaces its extension with .targeting.yaml, and creates that file next to it the first time you add a rule. You do not need to create or name the file yourself, but you can. Follow the pattern in a generated example if you do.

Checks settings file

Targeting file

my-security-checks.yaml

my-security-checks.targeting.yaml

liquibase.checks-settings.conf

liquibase.checks-settings.targeting.yaml

If your checks settings file is a checks package, the targeting file pairs with the package's own file name, not with any of the files the package aggregates. This keeps rules for the same check separate when several settings files define it.

To use a different name or location, pass --targeting-file to checks targeting add, list, remove, and checks run. This is useful when separate teams or jobs need their own rules. A bare file name resolves next to the checks settings file's own directory; a path that includes its own directory is used exactly as given.

Important: Rules apply only when you pass --targeting-file. If you omit it on checks run, Liquibase applies no targeting rules and does not warn you, so a run can look clean while every rule you configured sits inactive.

How it is applied

checks run applies targeting rules only when the run names the targeting file with --targeting-file. There is no enable flag, and the paired file is not picked up just because it exists. Leave the parameter off and checks run behaves exactly as it did before you added any rules.

Structure

The file has two rule sections, exempt and restrict, each a list of rules. A rule names the check it applies to, the filter that selects changesets, and optional reason and expiration values. Liquibase also records a version (currently '1.0') and a file-level created date, and it writes a leading comment block that explains how the rules work. Keys are stored in alphabetical order, so version appears at the end of the file. You normally do not edit the file by hand; use checks targeting add, list, and remove.

loading

Each time you run checks targeting add, Liquibase appends another rule to the appropriate section of this same file.

Rule fields

Field

Description

checkName

The short name of the policy check the rule applies to. Required.

filter

One or more of teams, releases, keywords, conditions, labels, contexts, with the value to match. Matching is case-insensitive. Values within one filter are a comma-separated OR list, and separate filters combine with AND, so a rule with two filters matches only changesets that satisfy both. A filter always matches strictly, so a leading @ on a value is accepted but does nothing. labels and contexts compare plain words rather than boolean logic, so and, or, not, parentheses, and ! in a changeset's value are discarded rather than evaluated. A rule with no filter matches every changeset for the check.

reason

Optional free-text note explaining why the rule exists. Shown in checks targeting list.

expiration

Optional date, date-time, or duration after which the rule stops applying. See the --expiration parameter on checks targeting for accepted formats. Expiration is measured in UTC and a bare date stays active through the end of that day, regardless of the time zone of the computer running checks run.

id

Optional stable identifier for the rule, used by checks targeting list and remove. Written to the file only when you set a custom --id; if omitted, the id defaults to the check name at runtime and is not stored.

created

Set automatically when the rule is added (a yyyy-MM-dd date).

The filter values correspond to the changeset attributes documented under Changelog attributes. Set those attributes on your changesets (directly or with Apply changeset attributes in bulk with modifyChangeSets) so targeting rules can match them.

Related pages

Previouschecks targetingNextcheck-name