Viewing OPA Policy Evaluation Results Outside the HCP Terraform UI – HashiCorp Help Center

What is this article about and what problem does it solve?

This article explains why OPA policy evaluation error descriptions are not visible in the Terraform CLI or third-party automation tools, and how to retrieve them programmatically.

Customers using OPA policies in HCP Terraform may notice that:

When a policy fails, the CLI output does not show the detailed error description.
Automation platforms (e.g., CI/CD tools such as GitHub Actions, Gitlab, Jenkins, Harness) also do not display the OPA policy failure details.
The detailed evaluation results are only visible in the HCP Terraform UI.

This article provides a suggestion on how to retrieve OPA policy evaluation results using the HCP Terraform API, so they can be surfaced directly in automation pipelines.

Why do we need to solve this problem?

This question typically comes up in environments where Terraform runs are triggered remotely from external automation platforms. Customers execute Terraform through CI/CD pipelines, enforce OPA policies on their workspaces, and expect policy failures to appear directly in their pipeline logs. Instead, they find that when a policy fails, the detailed error description is only visible in the HCP Terraform UI.

This behavior is expected. Unlike Sentinel policies, OPA policy evaluation results are not printed in Terraform CLI output for CLI-driven runs. As a result, automation tools do not automatically display the underlying policy failure details.

For organizations that rely heavily on automation, this can introduce friction. Engineers must leave their pipeline context and navigate to the HCP Terraform UI to understand why a run failed. Pipelines cannot surface meaningful, actionable error messages on their own, and automated failure handling becomes more limited because the detailed policy outcome is not readily available in the execution logs.

How do we solve the problem?

While CLI support for displaying OPA policy results is not available, you can retrieve the evaluation results using the HCP Terraform API.

The suggested approach is to add an additional step in your automation pipeline that retrieves the policy evaluation ID from the run and fetches the policy set outcomes.

1. Retrieve Policy Evaluation ID

After a run completes (or fails), call the API call below. Run_ID can be viewed from the Terraform output, mentioning the URL at which the run can be viewed:

curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/runs/<RUN_ID>/task-stages | jq -r '.data[].relationships["policy-evaluations"]'

e.g. output
{
  "data": [
    {
      "id": "poleval-RykCZLY4hoYzwY4a",
      "type": "policy-evaluations"
    }
  ]
}

From the response, extract the data.id.

2. Retrieve Policy Evaluation Results

Use the data.id instead of the <POLICY_EVALUATION_ID> field below to retrieve the outcomes:

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/policy-evaluations/<POLICY_EVALUATION_ID>/policy-set-outcomes | jq

This response contains the same policy evaluation details shown in the HCP Terraform UI, including:

Policy pass/fail status
Error descriptions
Enforcement level

3. Integrate Into Automation

In your CI/CD system:

Parse the API response
Extract failure descriptions
Print them in pipeline logs
Explicitly fail the pipeline if policy evaluation fails

This enables visibility of OPA policy results without requiring users to access the HCP Terraform UI.