- Reference
- Version · 6.0
- Change Automation Reference
checks targeting
Last updated: September 29, 2026
Note: checks targeting requires Liquibase Secure 6.0 or later.
The checks targeting command manages persistent targeting rules that control how individual policy checks treat specific changesets during checks run. It has three subcommands:
Use
checks targeting addto add an exempt or restrict rule.Use
checks targeting listto show the current rules.Use
checks targeting removeto delete a rule.
For the concepts behind exempt and restrict rules, see What is Checks Targeting?. For the file these rules are written to, see Checks targeting file.
Uses
Use checks targeting to configure targeting rules from the command line instead of editing the targeting file by hand. Rules are written to the targeting file paired with your checks settings file, and they take effect on a checks run that names that file with --targeting-file.
checks targeting works against your changelog and targeting file only. It does not connect to a database.
Example scenario
Your team has a policy check that flags a pattern one application legitimately needs. Rather than disabling the check for everyone, you add an exempt rule so that only that application's changesets are exempt, with a reason and a review date:
liquibase checks targeting add --type=exempt --check-name=SqlGrantWarn --teams-filter=app01 --reason="Approved exception, see DevSecOps ticket 1234" --expiration=90dThe next checks run still inspects those changesets and lists them in the report, but they no longer fail the run. After 90 days the rule stops applying automatically.
Syntax
Run one of the following:
Command parameters
checks targeting add
Parameter | Description | Requirement |
|---|---|---|
| The rule type: | Optional |
| The short name of the policy check the rule applies to. | Required |
| A custom, stable ID for the rule, shown by | Optional |
| Match changesets by their | Optional |
| Match changesets by their | Optional |
| Match changesets by their | Optional |
| Match changesets by their | Optional |
| Match changesets by their | Optional |
| Match changesets by their | Optional |
| Free-text note stored with the rule and shown in | Optional |
| When the rule stops applying. Accepts a duration made of | Optional |
| Path to the checks settings file the rules are paired with. It determines the derived targeting file name. If omitted, the configured checks settings file is used. | Optional |
| Only needs to be specified when When the check name is unique across the package, Liquibase records the source file for you. When it is not, Liquibase reports an error that lists the files defining that check and asks you to set | Optional |
| Overrides the derived targeting file name and location. Defaults to the checks settings file name with its extension replaced by | Optional |
The check named by --check-name must already exist in the checks settings file. If it does not, add fails with Check '<name>' does not exist. and no rule is written.
Provide at least one filter to scope the rule. If you omit all filters, the rule matches every changeset for the named check, and add prints a warning:
For an
exemptrule with no filter, the rule exempts the check for every changeset. Liquibase suggestschecks bulk-set --severity=0orchecks customizeinstead, since a filter is usually the point of targeting.For a
restrictrule with no filter, the rule matches every changeset and narrows nothing, so the rule has no effect.checks targeting listalso flags such a rule (see Output).
Values within one filter are a comma-separated OR list, and separate filters combine with AND. --teams-filter=frontend --releases-filter=v1,v2 matches changesets on the frontend team that are in either release. A filter always matches strictly, so a leading @ on a value is accepted but does nothing.
--labels-filter and --contexts-filter compare plain words rather than boolean logic, so they do not behave like --label-filter and --context-filter do on update and checks run. A changeset with contexts="(dev or test) and !prod" matches --contexts-filter=test and --contexts-filter='!prod', because Checks Targeting compares the words in the value and discards and, or, not, parentheses, and !. A value made only of those reserved words can never be matched.
checks targeting list
Parameter | Description | Requirement |
|---|---|---|
| Limit output to | Optional |
| Limit output to rules for one check. | Optional |
| Limit output to rules with a matching filter. | Optional |
| Path to the checks settings file the rules are paired with. It determines the derived targeting file name. If omitted, the configured checks settings file is used. | Optional |
| Overrides the derived targeting file name and location. Defaults to the checks settings file name with its extension replaced by | Optional |
checks targeting remove
Parameter | Description | Requirement |
|---|---|---|
| The ID of the rule to remove, as shown in | Required |
| Path to the checks settings file the rules are paired with. It determines the derived targeting file name. If omitted, the configured checks settings file is used. | Optional |
| Overrides the derived targeting file name and location. Defaults to the checks settings file name with its extension replaced by | Optional |
Global parameters
checks targeting supports the standard global parameters (for example --log-level and --log-file). See Policy check and Flow commands and parameters and the global command parameters reference.
Syntax by configuration method
Like other commands, each parameter can be set on the CLI, in a Flow file, in liquibase.properties, as a JAVA_OPTS system property, or as an environment variable. The property and environment-variable forms are namespaced to the subcommand, for example:
Note: Property and environment-variable keys are namespaced by the subcommand you are configuring (add, list, or remove).
Output
checks targeting add
Added checks targeting exempt rule 'SqlGrantWarn' for check 'SqlGrantWarn' to 'liquibase.checks-settings.targeting.yaml'.If you set --expiration or --reason, they are appended to the same line:
Each checks targeting add appends one rule to the targeting file. To add more exceptions, run checks targeting add again for each one. There is no separate append flag, and you do not create a new file per rule.
checks targeting list
Rules are shown in two sections, EXEMPT and RESTRICT, each a table with the same columns. A filter you did not set shows as * (matches any value), and a rule with no expiration shows never.
If there are no rules to show, the command prints No checks targeting rules found. and reports where it looked, for example No checks targeting rules found. Looked in 'liquibase.checks-settings.targeting.yaml'. A --type or filter argument that excludes everything is noted too, for example No checks targeting rules found. (type=restrict) Looked in '...'.
A rule that cannot apply is annotated in the REASON column:
Annotation | Meaning |
|---|---|
| The rule's |
| A |
| The rule names a check that is not in the checks settings file. Because |
checks targeting remove
Removed checks targeting rule 'SqlGrantWarn' from 'liquibase.checks-settings.targeting.yaml'.