Quality Checks Packages

You can create checks package files to organize your Checks Settings Files. Checks settings files specify custom behavior for your quality checks. A checks package is a central YAML file that serves as a collection of multiple checks settings files. Using a checks package makes it easy to apply policies from many different checks settings files all in one place.

You can group together different checks settings files in your package to control which conditions or environments those settings files are active in. Then you can apply multiple checks with a single checks run or checks show command.

This feature is available in Liquibase 4.25.0 and later.


This allows different teams to own, control, update, and automatically synchronize their checks with their dependent teams. Quality checks resources are easily centralized with checks packages. The checks packages file is the central hub that reaches out to the local and remote checks settings files needed for different jobs, pipelines, and teams. For example, if your Security team stores their checks in one place, the checks packages file that points to that security checks file will pick up the latest version. This allows your distinct teams to reproduce the same outcome even if files are located separately.


  • Checks packages only work with the run and show subcommands
  • Checks packages are a collection of checks settings files. This has the following implications:
    • Liquibase ensures that checks settings files are not duplicated in a package. However, there can be two checks with the same name in a package if they each have different checks-settings files.
  • You cannot use bulk-set, copy, create, customize, delete, disable, enable, or reset subcommands with the checks settings file that is part of a checks packages file.

Create a checks packages file

  1. To create a checks package, you must have at least one checks settings file. You can create one by running any quality check command and following the prompt instructions:
  2. liquibase checks show

    When successful, Liquibase displays the following message along with the output of the command you ran:

    liquibase.checks-settings.conf successfully created!
  3. Run the checks create command to create a new YAML checks package file. For example:
  4. liquibase checks create --package-contents=liquibase.checks-settings.conf --package-name=liquibase.package.conf --package-file=security-checks.pkg

    This results in:

    • A package file called security-checks.pkg
    • A package object inside the file called liquibase.package.conf
    • The contents of the package object, a checks settings file called liquibase.checks-settings.conf.

You can set the following properties for the checks package file in the CLI, liquibase.properties file, or as environment variables. In the example below the CLI input is used:

Attribute Description Requirement
--package-contents The file(s) or directory to include in the checks package object Required
--package-name The name of the checks package object inside the file to be created. Required
--package-file The file name of the YAML file to create. Default: liquibase.checks-package.yaml Optional

Use the checks package file

Once you've created your file, you can use it with the checks show and checks run commands:

liquibase checks show --checks-packages=security-checks.pkg
liquibase checks run --checks-packages=security-checks.pkg

You can specify multiple checks packages with a comma-separated list:

liquibase checks run --checks-packages=security-checks.pkg,qa-checks.pkg

Additional checks packages features

There is a column in the checks show table that displays the source check settings file. There is also a line in the console output for checks run that highlights the check settings file which holds the enabled checks and other check run console output. Learn how to Use the Checks Settings Configuration File here.

Checks Packages File Example

- name: "master-checks-Sept2023.pkg"
   - "./liquibase.checks-settings.conf"
   - "./liquibase.more.checks-settings.yaml"
   - hashicorp,secret/liquibase/ChecksSettingsFile,checksSettingsFile

Related links