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, 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.

What you will learn from this topic

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 for each.

• Distinguish 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 and the evaluation input payload as a reference.

• Test a policy before applying it, and review 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

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 to understand the governance model this topic builds on.

• Rego fundamentals: Harness policies are written in Rego, 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 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 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 to review the required permissions.

Entities and events for policy evaluation

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

On save and on run policy evaluation

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 to inspect the exact payload passed to a policy for a given save or run event.

Writing a policy in Rego

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, 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:

Process - Prevent Direct Execution

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])
}

Testing Terminal tab showing a Rego policy and its evaluation output

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:

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

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

Testing a policy

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

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

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

Next steps

• Go to the Harness Policy As Code overview to learn about policies, policy sets, and severities.

• Go to Policy samples to see more Rego examples across other Harness entities.

• Go to Policy evaluations retention to understand how long Harness retains evaluation results shown on the Evaluations tab.

• Go to Ad hoc releases to understand how ad hoc releases differ from regular releases.

• Go to Executing a release to understand the rest of the release execution flow.