> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/release-orchestration/use-release-orchestration/release-orchestration-execution/opa-governance-for-releases.md).

# Governance of a release - OPA policy

Learn how Harness Policy As Code evaluates OPA policies written in Rego against Release Orchestration entities, on save and on run

Release Orchestration integrates with [Harness Policy As Code](https://developer.harness.io/harness-platform/use-harness-platform/governance/policy-as-code/harness-governance-overview), enabling you to enforce governance rules across release groups, processes, activities, and releases using Open Policy Agent (OPA) policies written in Rego. Policy evaluation catches governance violations either at configuration time, when an entity is saved, or at execution time, when a process or release runs.

The following demo walks through configuring an OPA policy set for Release Orchestration and seeing a policy evaluation in action:

{% embed url="<https://app.arcade.software/share/1BfoxNa2MpHLYLBzx4XW>" %}

### What you will learn from this topic <a href="#what-you-will-learn-from-this-topic" id="what-you-will-learn-from-this-topic"></a>

By the end of this topic, you will be able to:

* Identify which Release Orchestration entities support OPA policy evaluation and [which events trigger evaluation](#entities-and-events-for-policy-evaluation) for each.
* Distinguish [on save and on run policy evaluation](#on-save-and-on-run-policy-evaluation), including how on-run evaluation differentiates regular releases from ad hoc releases.
* Write a policy in Rego against a Release Orchestration entity, using the [sample policy library](#sample-policies-in-the-library) and the evaluation input payload as a reference.
* Test a policy before applying it, and review [evaluation results](#viewing-evaluation-results) for a save or run event.
* Determine what happens to a save or run action when a policy evaluation returns a warning or an error.

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

Before you configure OPA policy evaluation for Release Orchestration, make sure you have the following:

* **Harness Policy As Code fundamentals**: Familiarity with policies, policy sets, entities, and events. Go to the [Harness Policy As Code overview](https://developer.harness.io/harness-platform/use-harness-platform/governance/policy-as-code/harness-governance-overview) to understand the governance model this topic builds on.
* **Rego fundamentals**: Harness policies are written in [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/), the policy language used by Open Policy Agent (OPA). Familiarity with Rego syntax, such as package declarations and `deny` rules that help you write and troubleshoot policies.
* **Release Orchestration concepts**: Understanding of processes, activities, release groups, and releases. Go to the [Releases overview](/release-orchestration/use-release-orchestration/release-orchestration-releases/overview.md) to review these concepts.
* **Regular and ad hoc releases**: Understanding of how a regular release, generated from a release group, differs from an ad hoc release, created on demand outside a release group. Go to [Ad hoc releases](/release-orchestration/use-release-orchestration/release-orchestration-releases/adhoc-releases.md) to review this distinction.
* **Permissions**: Permissions to create and manage policies and policy sets at the appropriate scope (Account, Organization, or Project level). Go to [Policies permissions](https://developer.harness.io/harness-platform/use-harness-platform/platform-access-control/permissions-reference#policies) to review the required permissions.

### Entities and events for policy evaluation <a href="#entities-and-events-for-policy-evaluation" id="entities-and-events-for-policy-evaluation"></a>

When you create a policy set, you select the Release Orchestration entity it applies to and the event that triggers evaluation. Release Orchestration supports the following entities and events.

| Entity        | Supported events |
| ------------- | ---------------- |
| Release group | On Save          |
| Process       | On Save, On Run  |
| Activity      | On Save          |
| Release       | On Run           |

![Entity and event dropdowns in the policy set creation dialog](https://478177610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwRDYqBolZUj6Rwnqx0mm%2Fuploads%2Fgit-blob-4f315bd98c185d1b1f5be23de1e7bb957fe5e08e%2Fro-policy-set-entity-types.png?alt=media)

### On save and on run policy evaluation <a href="#on-save-and-on-run-policy-evaluation" id="on-save-and-on-run-policy-evaluation"></a>

Harness evaluates OPA policies against a release group, a process, or an activity when you save it. This lets you catch governance violations, such as a missing approval activity, a phase without an assigned owner, or an activity with an empty description, at configuration time rather than waiting until the entity runs.

Harness also evaluates OPA policies against a process or a release when it is triggered to run. On-run evaluation for a release applies to both regular releases, generated from a release group, and ad hoc releases, created on demand outside a release group, so you can write policies that apply to one release type, the other, or both. On-run evaluation for a process applies whenever the process is run, whether directly or as part of a release, so you can use it to require that a process be executed only through a release rather than on its own.

The on-run evaluation payload is an expanded representation of the entity and includes fields that are available only at run time. For example, `process.directProcessExecution` is present only on the on-run payload for a process, not on the on-save payload. Go to [Viewing evaluation results](#viewing-evaluation-results) to inspect the exact payload passed to a policy for a given save or run event.

### Writing a policy in Rego <a href="#writing-a-policy-in-rego" id="writing-a-policy-in-rego"></a>

A policy is a Rego module that declares a package and one or more `deny` rules. Each `deny` rule inspects the `input` object, which contains the entity being evaluated, and adds a message to the result when the rule's condition is true.

Every key you see in the evaluation input, described in [Viewing evaluation results](#viewing-evaluation-results), is available under `input` in your policy. The following policy denies a process that is run directly instead of through a release, using the `process.directProcessExecution` field that is present only at run time:

{% code title="Process - Prevent Direct Execution" overflow="wrap" %}

```rego
package release

# Standalone process runs skip the release group's cadence, conflict checks, version, and audit record.
# directProcessExecution is present only on the on-run payload.
deny[msg] {
  input.process.directProcessExecution == true
  msg:= sprintf("process '%s' cannot be run directly; execute it through a release so the run is scheduled, conflict-checked and auditable", [input.process.name])
}
```

{% endcode %}

![Testing Terminal tab showing a Rego policy and its evaluation output](https://478177610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwRDYqBolZUj6Rwnqx0mm%2Fuploads%2Fgit-blob-b73b42d72516df5c13d764a09af4a623ec53b1ad%2Fro-policy-test-rego.png?alt=media)

You can write the same kind of rule against any field on the entity, not only run-time-only fields. For example, the following policy requires a process to always have a description:

```rego
package release

deny[msg] {
  input.process.description == ""
  msg := "process cannot have an empty description"
}
```

The same pattern applies to a release, release group, or activity policy. Reference `input.release`, `input.releaseGroup`, or `input.activity` instead of `input.process`, and check whichever field the policy needs to enforce.

### Sample policies in the library <a href="#sample-policies-in-the-library" id="sample-policies-in-the-library"></a>

The policy editor's **Library** tab includes sample policies that you can filter by entity and copy into a new policy as a starting point. Search or filter by entity name (release group, process, activity, or release) to see the samples available in your account and their Rego source.

![Library tab with sample policies filterable by entity](https://478177610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwRDYqBolZUj6Rwnqx0mm%2Fuploads%2Fgit-blob-1195241a5eefba444ff8eed205dea0ef12f9c6db%2Fro-policy-library-samples.png?alt=media)

### Testing a policy <a href="#testing-a-policy" id="testing-a-policy"></a>

Before you save a policy, use the **Testing Terminal** tab in the policy editor to run it against a sample input and confirm it behaves as expected.

1. In **Policies**, select **New Policy**, or open an existing policy.
2. Write or paste the policy in the code editor.
3. Select **Testing Terminal**, then select **Test** to evaluate the policy against the sample input shown in the panel.
4. Review the output. A policy with a matching `deny` rule shows the resulting message. Adjust the policy and select **Test** again until it produces the expected result.

### Viewing evaluation results <a href="#viewing-evaluation-results" id="viewing-evaluation-results"></a>

Every on-save or on-run evaluation is recorded on the entity's Evaluations tab, along with the policy sets evaluated, their source scope (Account, Organization, or Project), and whether the evaluation passed or failed. Select a policy set to see the individual policies it contains and, for a failed policy, the exact `deny` message it returned.

![Evaluations tab showing policy set results and evaluation status](https://478177610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwRDYqBolZUj6Rwnqx0mm%2Fuploads%2Fgit-blob-10a48983e115285e84e84ad41ab1a95f1bfbc9f1%2Fro-evaluations-tab.png?alt=media)

The Evaluations tab is also where you inspect the full evaluation input payload for a given save or run event, including every field available to a policy at that point, such as `process.directProcessExecution` on an on-run evaluation for a process.

As with other Harness entities, each policy in a policy set applied to Release Orchestration is assigned a severity that determines what happens when the policy evaluation fails:

* **On error (Error and Exit)**: Harness blocks the save or run action and shows a message that the action was blocked by a governance policy, together with the policy's `deny` message.
* **On warning (Warn and Continue)**: Harness shows the policy's `deny` message, but the save or run action proceeds.

![Run blocked with a governance policy error and the deny message](https://478177610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwRDYqBolZUj6Rwnqx0mm%2Fuploads%2Fgit-blob-a7b0bdc68e4ad69d0be9f6af3ada374cc4ac6d2f%2Fro-run-blocked-by-policy.png?alt=media)

### Next steps <a href="#next-steps" id="next-steps"></a>

* Go to the [Harness Policy As Code overview](https://developer.harness.io/harness-platform/use-harness-platform/governance/policy-as-code/harness-governance-overview) to learn about policies, policy sets, and severities.
* Go to [Policy samples](https://developer.harness.io/harness-platform/use-harness-platform/governance/policy-as-code/sample-policy-use-case) to see more Rego examples across other Harness entities.
* Go to [Policy evaluations retention](https://developer.harness.io/harness-platform/use-harness-platform/governance/policy-as-code/opa-evaluations-retention) to understand how long Harness retains evaluation results shown on the Evaluations tab.
* Go to [Ad hoc releases](/release-orchestration/use-release-orchestration/release-orchestration-releases/adhoc-releases.md) to understand how ad hoc releases differ from regular releases.
* Go to [Executing a release](/release-orchestration/use-release-orchestration/release-orchestration-execution/executing-a-release.md) to understand the rest of the release execution flow.

{% @harness-feedback/feedback %}