Policy Checks Packages

You can create a YAML checks package file to organize your checks settings files. Using a checks package makes it easy to specify policies for different workflows all in one place. Then you can apply all your checks with a single checks run or checks show command, just like you would when running checks from a single settings file.

A package file contains one or more package objects, such as for DEV, QA, and PROD environments; or for security-checks and code-standardization-checks workflows. Each package object contains one or more checks settings files. Checks settings files specify which policy checks are enabled (ready to run) as well as any custom check behavior. The checks settings file can have the .conf or .yaml extensions.

Checks packages are available in Liquibase 4.25.0 and later.

Uses

Checks packages allow different teams to own, control, update, and automatically synchronize their checks with their dependent teams. 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 package 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.

Rules

  • Checks packages are supported for the run and show commands.
  • Checks packages are not supported for the bulk-set, copy, create, customize, delete, disable, enable, or reset commands.
    • This means that if you specify a package file as the value of --checks-settings-file while running any of these unsupported commands, Liquibase returns an error. To use a settings file with these commands, you must specify it directly instead of specifying a package file containing it.
  • Checks package objects are collections of checks settings files. This means that:
    • Liquibase ensures that checks are not duplicated in a particular package. However, there can be two checks with the same name in a particular package if they appear in different checks settings files.
    • If you include the same checks settings file multiple times in a particular package, Liquibase only runs it once.

Create a checks package file

If you don't yet have any checks settings files, follow each of these steps starting at Step 1.

If you already have a collection of related checks settings files, skip directly to Step 4 to put them into a package.

  1. Create a template checks settings file. You will use this to create custom settings files to put in your package file.

    2. Run any policy check command:

    liquibase checks show

    Enter 1 to use the default checks settings file (liquibase.checks-settings.conf). When successful, Liquibase displays a list of checks enabled by default plus the following message:

    liquibase.checks-settings.conf successfully created!
  2. Prepare a custom checks settings file based on the template:
    1. Use the shell cp command (or copy on Windows) to create a duplicate settings file with a custom name, in this case oracle-checks.yaml.
      2. cp liquibase.checks-settings.conf oracle-checks.yaml
    2. Use checks bulk-set to disable all checks within the custom settings file you just created.
      3. liquibase checks bulk-set --disable
    3. Use checks enable to enable only the checks you want to include (see a list of checks to choose from):
      4. liquibase checks enable --check-name=<checkName1>
      liquibase checks enable --check-name=<checkName2>
    4. Use checks show to verify that you've enabled all the checks you want:
      5. liquibase checks show

    Now you've created a custom checks settings file! Later, you will add it to a package.

  3. Repeat Step 2 for as many checks settings files as you want to create, such as another settings file for postgres-checks.yaml and sqlserver-checks.yaml.
  4. Run the checks create command to create a new YAML checks package file:
    • For --package-file, specify any file name ending with .yaml. If you specify a file that does not exist, Liquibase will create it.
    • For --package-name, specify any descriptive name for a package object to be listed in the file.
    • For --package-contents, specify all the settings files you just created. If you specify a directory, all files within the directory will be added to the --package-name object, but not recursively.

    5. For example:

    liquibase checks create \
  --package-file=liquibase.security-checks.yaml \
  --package-name=platform-checks \
  --package-contents=oracle-checks.yaml,postgres-checks.yaml,sqlserver-checks.yaml
    liquibase checks create ^
  --package-file=liquibase.security-checks.yaml ^
  --package-name=platform-checks ^
  --package-contents=oracle-checks.yaml,postgres-checks.yaml,sqlserver-checks.yaml

    This creates a package file called liquibase.security-checks.yaml. The file contains one package object (platform-checks), which contains three checks settings files for different databases:

    checksPackages:
  - name: platform-checks
    files:
      - oracle-checks.yaml
      - postgres-checks.yaml
      - sqlserver-checks.yaml
  5. Repeat Steps 2–4 for as many settings files and packages you want to create.
    • You can reuse checks settings files across multiple packages, or you can keep them all completely separate.
    • You can also add an additional settings file to an existing package by running checks create again and specifying the settings file and package to add it to.

Now you've successfully created a checks package file!

Note: To remove checks settings files from an existing package object or to remove a package object altogether, you must open your YAML file and make the changes manually.

Use the checks package file

Once you've created your file, you can use it with the checks show and checks run commands. Specify the name of your file with --checks-settings-file and the name of your package object(s) with --checks-packages.

Show a list of checks associated with your package:

liquibase checks show --checks-settings-file=liquibase.security-checks.yaml --checks-packages=platform-checks

Run all checks in your package:

liquibase checks run --checks-settings-file=liquibase.security-checks.yaml --checks-packages=platform-checks

Specify multiple specific checks packages in your package file with a comma-separated list:

liquibase checks run --checks-settings-file=liquibase.security-checks.yaml --checks-packages=platform-checks,qa-checks

Run all checks packages in your package file by omitting the --checks-packages parameter:

liquibase checks run --checks-settings-file=liquibase.security-checks.yaml

Note: If the checks package file is named liquibase.checks-settings.conf, you do not need to specify the file name in --checks-settings-file. However, if you use a custom name for your package file, you must specify it.

Output information

The checks show output table contains a column that displays the source checks settings file of each check. There is also a line in the output of checks run that highlights the checks settings file which holds the enabled checks. For more information, see Use the Checks Settings Configuration File.

Checks Packages File Example

This is an example of a checks package file containing multiple packages for different purposes:

checksPackages:

## packages by pipeline node
  - name: "dev-checks-files"
    files:
      - "./liquibase.checks-settings.conf"
      - "./liquibase.dev-checks.yaml"

  - name: "uat-checks-files"
    files:
      - "./liquibase.checks-settings.conf"
      - "./liquibase.uat-checks.yaml"

  - name: "prod-checks-files"
    files:
      - "./liquibase.checks-settings.conf"
      - "./liquibase.prod-checks.yaml"
      - "./liquibase.prod-checks-v2.yaml"


## packages by appteam
  - name: "appteam1-files"
    files:
      - "s3://allteams/liquibase.checks-settings.conf"
      - "s3://allteams/liquibase.securityrelease.conf"      
      - "./liquibase.appteam1.us-dev.yaml"

  - name: "appteam2-files"
    files:
      - "s3://allteams/liquibase.checks-settings.conf"
      - "s3://allteams/liquibase.securityrelease.conf"
      - "./liquibase.appteam2.us-dev.yaml"

      
## packages by db platform
  - name: "oracle"
    files:
      - "./platformchecks/liquibase.checks-oracle.yaml"

  - name: "postgres"
    files:
      - "./platformchecks/liquibase.checks-postgres.yaml"
      - "./platformchecks/liquibase.checks-postgres-older-versions.yaml"

  - name: "sqlserver"
    files:
      - "./platformchecks/liquibase.checks-sqlserver.yaml"

Related links