Embed governance in CI/CD

How to use it

Below are some examples of how to use the Witboost CLI. Replace the <AUTH_BASE_URL>, <BASE_URL>, and <TOKEN> values with your information following the commands reference page. The other parameter values should be replaced based on your specific input data and test environment.

First, we'll consider using only the mandatory fields. You must run the following command:

witboost governance evaluate \
    --auth-base-url <AUTH_BASE_URL> \
    --base-url <BASE_URL> \
    --token <TOKEN> \
    --resource-type dataproduct \
    --env development \
    --descriptor-file ./test/resources/descriptor.yaml \
    --resource-id "urn:dmb:dp:sales:testdp:0"

An output table will be displayed containing information about the policies/metrics that have been tested against the input descriptor. The fields shown for each policy and metric are: type, id, name, version, description, outcome (which indicates the test status), and result (with additional information about the executed test, including any errors and policy/metric satisfaction status).

Output file option

You can also add additional options to generate an output file that summarizes the test results. In this case, you can simply add the following options to the command:

witboost governance evaluate \
    --auth-base-url <AUTH_BASE_URL> \
    --base-url <BASE_URL> \
    --token <TOKEN> \
    --resource-type dataproduct \
    --env development \
    --descriptor-file ./test/resources/descriptor.yaml \
    --resource-id "urn:dmb:dp:sales:testdp:0" \
    --output json \
    --output-file evaluation_report.json

The generated JSON report follows this API structure with three additional fields: governanceEntityName, governanceEntityVersion and governanceEntityDescription. Below is an example of the generated report:

{
  "id": "9ac9d948-1dd1-4ef6-be55-85bfc9a045ad",
  "environment": "development",
  "evaluationScope": "evaluation",
  "evaluationResults": [
    {
      "governanceEntityId": "740669e2-678f-41bd-9fd5-44ca59a92824",
      "governanceEntityStatus": "enabled",
      "governanceEntityType": "policy",
      "resource": {
        "id": "urn:dmb:dp:sales:testdp:0",
        "displayName": "sales:testdp:0.1.0-SNAPSHOT-2",
        "environment": "development",
        "resourceType": "dataproduct",
        "descriptor": "<resource descriptor will be shown here when available in the result>"
      },
      "outcome": "ok",
      "result": {
        "isError": false,
        "satisfiesPolicy": true,
        "errors": []
      },
      "creationTime": "2025-09-30T16:29:55.658096+02:00",
      "governanceEntityName": "qdpr check",
      "governanceEntityDescription": "qdpr check description",
      "governanceEntityVersion": "1"
    }
  ],
  "creationTime": "2025-09-30T16:29:55.658123+02:00",
  "updateTime": "2025-09-30T16:29:55.658126+02:00",
  "status": "completedWithSuccess"
}

In this case, you will obtain the following output, which includes a confirmation message about the JSON evaluation report generation.

Compact summary option

If you want to display a condensed version of the output table, you can add the --compact-summary option to show a more compact table. In this case, you will see only the following fields: type, name, version and outcome.

witboost governance evaluate \
    --auth-base-url <AUTH_BASE_URL> \
    --base-url <BASE_URL> \
    --token <TOKEN> \
    --resource-type dataproduct \
    --env development \
    --descriptor-file ./test/resources/descriptor.yaml \
    --resource-id "urn:dmb:dp:sales:testdp:0" \
    --compact-summary

Exit on failure option

If a test fails and you add the --exit-on-failure option, the CLI will exit with a non-zero status code and display detailed failure information with an error message after the result table instead of an info message.

witboost governance evaluate \
    --auth-base-url <AUTH_BASE_URL> \
    --base-url <BASE_URL> \
    --token <TOKEN> \
    --resource-type dataproduct \
    --env development \
    --descriptor-file ./test/resources/descriptor.yaml \
    --resource-id "urn:dmb:dp:sales:testdp:0" \
    --exit-on-failure

FAQs

What if I have JSON files?

If you have a JSON file, you can use the utils option to convert the input JSON to a YAML file. Then you can run the following command:

witboost utils json-to-yaml -i ./test/resources/descriptor.json

Can I pipe it with YQ?

If you have a YAML file, you can extract the --resource-id value using yq, which is a powerful command-line tool for parsing and manipulating YAML data. This allows you to dynamically extract the ID value from the descriptor file itself:

witboost governance evaluate \
    --auth-base-url <AUTH_BASE_URL> \
    --base-url <BASE_URL> \
    --token <TOKEN> \
    --resource-type dataproduct \
    --env development \
    --descriptor-file ./test/resources/descriptor.yaml \
    --resource-id "$(yq '.id' ./test/resources/descriptor.yaml)"

It's also possible to do similar things for the output options, and you can use it as follows:

witboost governance evaluate \
    --auth-base-url <AUTH_BASE_URL> \
    --base-url <BASE_URL> \
    --token <TOKEN> \
    --resource-type dataproduct \
    --env development \
    --descriptor-file ./test/resources/descriptor.yaml \
    --resource-id "$(yq '.id' ./test/resources/descriptor.yaml)" \
    --output json | yq -r '.evaluationResults[] | [.governanceEntityId, .outcome] | @tsv'

Can the output be saved?

You can save the CLI output using several methods:

Method 1: Shell redirection

Use the > operator followed by the output filename to save the complete output table:

witboost governance evaluate \
    --auth-base-url <AUTH_BASE_URL> \
    --base-url <BASE_URL> \
    --token <TOKEN> \
    --resource-type dataproduct \
    --env development \
    --descriptor-file ./test/resources/descriptor.yaml \
    --resource-id "urn:dmb:dp:sales:testdp:0" \
    > output.txt

To save only the compact summary table, add the --compact-summary option:

witboost governance evaluate \
    --auth-base-url <AUTH_BASE_URL> \
    --base-url <BASE_URL> \
    --token <TOKEN> \
    --resource-type dataproduct \
    --env development \
    --descriptor-file ./test/resources/descriptor.yaml \
    --resource-id "urn:dmb:dp:sales:testdp:0" \
    --compact-summary \
    > summary_output.txt

Method 2: Built-in output file option

Alternatively, use the --output-file parameter to save the output directly:

witboost governance evaluate \
    --auth-base-url <AUTH_BASE_URL> \
    --base-url <BASE_URL> \
    --token <TOKEN> \
    --resource-type dataproduct \
    --env development \
    --descriptor-file ./test/resources/descriptor.yaml \
    --resource-id "urn:dmb:dp:sales:testdp:0" \
    --output-file output.txt