- Concept
- Version · 6.0.2
- Manage
Configure operation reporting
Last updated: November 17, 2026
Configure Liquibase Server environment variables.
The reporting extension reads its settings through Liquibase's standard configuration system. You can set each value in liquibase.properties, in a file passed with --defaults-file, as an environment variable prefixed with LIQUIBASE_PLATFORM_, or as a JVM system property (-D flag). Liquibase's normal precedence applies, so a system property overrides an environment variable, which overrides a properties file.
the server is disabled by default (opt-in).
Warning: Operation reporting is a Liquibase Secure feature and runs only on a licensed Liquibase Secure installation. On Liquibase Community the extension disables itself (your Liquibase command still runs, but no data is sent). Liquibase Community is not a supported configuration.
Configuration properties
These are the variables you need to connect to the server.
Env Variable | System Property | Default | Description |
|---|---|---|---|
|
|
| Enable/disable operation reporting (opt-in) |
|
| — | API root for your deployment, for example https:// |
|
| — | Access token for HTTP mode. Sending operation data needs the service token of a service principal, because the server refuses a personal access token. |
|
| — | The Identifier of a registered connection, shown on its details page in the dashboard (e.g., |
|
| — | The Identifier of a registered changelog, shown on its details page in the dashboard (e.g., |
Note: The environment name (dev, staging, prod, etc.) is resolved automatically from the connection's associated environment in the server API. There is no local environment variable to set.
Note: Set at least one identifier, because a service token must name a connection or changelog. If you set only one, the operation is linked to that record and not to the other. If you set an identifier that matches no record in the token's projects (for example, a typo), the server refuses the operation and Liquibase prints the refusal in its output, so a typo never links an operation to the wrong connection or changelog. Identifiers match ignoring case, so psql, PSQL and pSqL all name the same connection or changelog. An identifier keeps the casing you entered it with, but no two connections, or two active changelogs, in a workspace can have identifiers that differ only in case. An archived connection keeps its identifier, so a new connection can't reuse it in any case.
API root
liquibase.platform.apiUrl is the address of your server with /api on the end, not the address of a particular endpoint. Liquibase works out the rest of each URL it needs, so your value stops at /api. A trailing slash makes no difference.
Every Liquibase capability that talks to the platform reads this one setting, so enabling a second capability needs no new connection configuration.
Note: Do not end the root with a resource path such as /operations/ingest. Liquibase appends the resource path itself, so a root that already carries one produces a URL that does not exist.
Derive the root for a standard install
The server exposes its API under /api. Take the URL your team opens in a browser and add that prefix.
Derive the root behind a reverse proxy
If a proxy serves the platform under a path of its own, that path belongs to you and is part of your root. Keep it, then add the API prefix after it.
Minimal configuration
For most setups, you only need these variables:
Configuration methods
Environment variables
System properties
Pass as JVM -D flags (useful for Maven or Gradle builds):
Properties file
Set the values in liquibase.properties, or in any file you pass with --defaults-file:
liquibase.platform.enabled=true
liquibase.platform.apiUrl=http://localhost:3000/api
liquibase.platform.apiKey=your_api_keyNote: Older releases could not read these values from liquibase.properties, because Liquibase's LogService initialized before the defaults file was loaded. That is fixed, and a properties file is now a supported way to configure the server.
Disable operation reporting
To temporarily disable operation reporting:
$env:LIQUIBASE_PLATFORM_ENABLED = "false"Advanced properties
These variables control internal behavior and are not required for normal operation. They are available for troubleshooting or for environments that need non-default tuning.
Env Variable | System Property | Default | Description |
|
|
| Number of log entries batched per HTTP request |
|
|
| Recovery file for failed HTTP payloads. Retry or inspect later. |
|
|
| Capture and upload HTML reports as artifacts |
|
| auto-detect | Override path to look for HTML reports |
|
|
| Print verbose |
|
|
| When |
|
|
| When |
Note: The extension does not need its own report name or path. It reads whatever --report-name and --report-path resolved to for the command, so a renamed or relocated report is still uploaded. Set liquibase.platform.reportsPath only when the extension should look somewhere else. It wins over the path Liquibase resolved, and when neither is set the extension falls back to Liquibase's global report path and then to the working directory.
Read reports from Amazon S3 or Azure Storage
The report path can be an Amazon S3 location (s3://) or an Azure Storage location (az://) as well as a local directory. The extension reads the report back with the same credentials and settings Liquibase uses to write it, which you set up when you connect Liquibase to Amazon S3 or connect to Azure Blob Storage.
Liquibase has no credential setting of its own for either location. It uses each cloud provider's default credential chain and takes the first credentials it finds.
Amazon S3: Liquibase tries Java system properties (
aws.accessKeyIdandaws.secretAccessKey), then environment variables (AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY, andAWS_SESSION_TOKEN), then a web identity token (AWS_WEB_IDENTITY_TOKEN_FILEwithAWS_ROLE_ARN). After that it tries the shared config and credentials files forAWS_PROFILE, including SSO profiles, then container credentials from Amazon ECS or EKS Pod Identity, and finally the EC2 instance profile. The region comes from theaws.regionsystem property, thenAWS_REGION, then the profile's config file, then instance metadata. Reads also work when the bucket is in a different region.Azure Storage: Liquibase tries environment variables for a service principal, then workload identity, managed identity, IntelliJ, Visual Studio Code, the Azure CLI (
az login), Azure PowerShell, and the Azure Developer CLI (azd). For anaz://path, the storage account comes fromliquibase.azure.storageAccountorLIQUIBASE_AZURE_STORAGE_ACCOUNT. If the container in the path does not exist, Liquibase creates it when it writes the report. Connection strings, SAS tokens, and account keys are not supported.
Those credentials also need permission to list and read objects at the report location, not only to write them. On Amazon S3, that means s3:ListBucket and s3:GetObject.
Point the report path at a folder inside the bucket or container, such as s3://my-bucket/reports. The extension cannot search a bucket or container root for a default-named report, so a root path works only when you set --report-name.
Note: If several jobs write default-named reports to the same folder at the same time, a job can upload another job's report. Give each pipeline its own folder, or set --report-name.
What the extension sends
Each log entry the extension sends includes the host name of the machine that ran Liquibase and the Java version it ran on. The extension holds back two details:
Operating-system account: Sent only when you set
liquibase.platform.includeOsUsernametotrue. The operation's Run by value then shows that account. While the setting is off, Run by shows a dash (—).Working directory: The extension never sends its absolute path. Other local paths, such as changelog paths, are still sent.
The extension sends the connection URL with its host, port, database, and other parameters, and masks the credentials in it. The same masking applies to log messages, error messages, and stack traces. The extension masks these forms:
Parameter keys: Any parameter whose name contains
password,passwd,pwd,token,secret,apikey,api_key,api-key, orcredential, such asPWD=,apiKey=, oraccessToken=.URL user information: The secret in
scheme://user:secret@host, including a secret that contains@or/.Oracle thin URLs: The password in
jdbc:oracle:thin:user/password@host.
When a changeset fails, Liquibase also masks passwords in the failed SQL before the extension sends the error. That covers the password in an IDENTIFIED BY clause and the value in PASSWORD = '…' or SECRET = '…'.
Note: The uploaded HTML report shows the operating-system account and the host name regardless of the liquibase.platform.includeOsUsername setting. To stop the extension from uploading reports, set liquibase.platform.captureReports to false.
Output mode
The extension sends operation data directly to the server API via HTTP POST. Logs are batched and sent automatically after each command runs.
If the API is unreachable, logs are written to a local recovery file (configurable via
LIQUIBASE_PLATFORM_RECOVERY_FILE_PATH)The CLI command still succeeds regardless of API connectivity