- Task
- Version · 6.0.2
- Govern
Run checks with a policy assignment
Last updated: November 17, 2026
Run the policy checks an assignment maps from your pipeline with a service token, or from your own machine with a personal access token, so every run enforces the same policies.
Before you begin
Create an assignment that maps the packages you want enforced and covers the database and changelog this pipeline works on.
Connect the CLI to your Liquibase Secure server. Set
liquibase.platform.apiUrlto your server's ingest URL andliquibase.platform.apiKeyto an access token whose owner can read the assignment. In a pipeline, use the service token of a service principal that has access to the assignment. On your own machine, use a personal access token, which runs the checks with your own access. Without both settings,checks runstops withLB-CHK-0008.A changelog for the checks to run against. Set
changelogFilein your defaults file, or pass--changelog-filewhen you run the command. Without one,checks runstops withLB-CHK-0001.
Know which check scopes your assignment covers. By default, checks run includes only changelog checks, so a database-scoped check that is out of scope passes without ever running.
Procedure
Copy the assignment ID
Open your assignment under Assignments in the Govern section. The ID sits at the top of its detail page with a control to copy it. That ID is what connects the assignment to your pipeline.
Run the checks
In your pipeline, or locally to test, run checks run with the assignment’s ID:
Be sure to:
Replace
your_assignment_idwith the ID you copied in step 1.
liquibase checks run --assignment-id=your_assignment_idThe server resolves the ID to the set of checks the assignment currently maps, and those are the checks that run. The command in your pipeline never names a check, so you change what it enforces by editing the assignment in the web application, and the next run picks that up.
Note: --assignment-id takes precedence over --checks-settings-file. If you pass both, the local file is ignored and never read, and the run tells you so.
To include database-scoped checks, add --checks-scope=changelog,database. The checks run command reference lists every parameter the command takes.
Troubleshooting
When checks run cannot use your personal access token, it stops before any check runs and exits with code 1. The error is LB-CHK-0025, or LB-CMD-0072 when the run also reports operations. The error identifies the token by its name and prefix, never by its full value.
The personal access token has expired
The error names the token, its prefix and the date it expired. An expired token never works again, so create a new personal access token and replace the value of liquibase.platform.apiKey with it.
The personal access token was revoked
The error names the token, its prefix and the date it was revoked, and says that it cannot be used again. Create a new personal access token and replace the value of liquibase.platform.apiKey with it.
If the token was revoked because your account was deactivated, the error says so and names the workspace. A new token cannot help while the account is deactivated, so ask an administrator of that workspace to reactivate your account, and then create a new token.
Personal access tokens are turned off
The error names the workspace and says that personal access tokens are turned off there. Your token is suspended, not revoked, and it works again as soon as an administrator turns the setting back on. Its expiry date keeps counting down while it is suspended.
You do not have access to the assignment
The error names the assignment, and no checks run. The run never falls back to running without the assignment's policies. Ask the assignment's owner or an administrator to give you access to it. Check the assignment ID as well, because the error may not distinguish an assignment that does not exist from one you cannot read.
The token is the wrong type
The error names the credential type the request needs and the type you supplied. Use a personal access token to run checks with your own access, and a service token in a pipeline, where operation data is sent to the server.
Note: An error about a token the server does not recognize never names a token. Check that liquibase.platform.apiKey holds the whole value you copied when you created the token.
What to do next
You have a run you can read, and with every check at its default severity it reported and blocked nothing. Tune your policy checks to decide which checks to switch on or off and to set their parameters. When a check has earned your trust, set its severity so the pipeline stops on it.